Write firmware for the Ferris keyboard (#9634)

* Write firmware for the Ferris keyboard

Took inspiration from the gergoplex and the ergodox_ez firmware for the
split matrix with io_expander on the right hand.
Cleaned up a lot of bit fiddling on the mcu side by taking inspiration
from the `split_custom` in quantum.
Still bit fiddling on the mcp side as it is particularly natural to do
so with the abstractions provided by the i2c protocol. Would be good to
clean that up and abstract away the wiring from the generic i2c code in
a similar fashion as quantum and the mcp side behave.

One improvement over the ergodox_ez and the gergoplex firmwares is that
the wiring is straight forward as opposed to swapping rows and columns
in two different places that end up cancelling out for some reason.

At this stage, I have flashed this firmware to a board and have verified
that all keys are behaving as intended by shorting pins.
I still have to solder in some switches and test that everything works
correctly at normal typing speeds, but I don't expect any major issues
given I'm building up on previous effort, including the debouncing code
from the ergodox_ez.

* Remove rotation from info.json and label the keys as per default keymap

* Comply with minor review feedback points

* Use CUSTOM_MATRIX=lite to remove boilerplate

* Update keyboards/handwired/ferris/info.json

Didn't play nicely in the configurator

Co-authored-by: Ryan <fauxpark@gmail.com>

* Remove MIDI_ENABLE from rules.mk

Co-authored-by: Ryan <fauxpark@gmail.com>

* Remove FAUXCLICKY_ENABLE from rules.mk

Co-authored-by: Ryan <fauxpark@gmail.com>

* Prefer wait_ms over _delay_ms

Co-authored-by: Ryan <fauxpark@gmail.com>

* Remove unused include

Co-authored-by: Ryan <fauxpark@gmail.com>

* Remove unused include

Co-authored-by: Ryan <fauxpark@gmail.com>

* Remove unused include

Co-authored-by: Ryan <fauxpark@gmail.com>

* Remove unused includeh

Co-authored-by: Ryan <fauxpark@gmail.com>

* Use dprint over print and remove include for print.h

* Remove all unused includes

* Remove unused code

* Cleanups thanks to code review

* Move more personal settings from the ferris config to the default keymap config

These setting happen to be unused in the default keymap at the moment,
as it has only one layer with no homerow modifiers and no mouse key; but
I would like to keep it there for two reasons:
* It can serve as an example to people creating their own keymap
* I plan to design a more usable default keymap that uses these features
  once this PR which adds the Ferris keyboard is merged.

* Consolidate mcp logic inside matrix.c

Co-authored-by: Ryan <fauxpark@gmail.com>

9 files changed, 578 insertions, 0 deletions

diff --git a/keyboards/handwired/ferris/config.h b/keyboards/handwired/ferris/config.h
new file mode 100644
index 0000000000..33494d9273
--- /dev/null
+++ b/keyboards/handwired/ferris/config.h
@@ -0,0 +1,60 @@
+/*
+Copyright 2020 Pierre Chevalier <pierrechevalier83@gmail.com>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#pragma once
+
+/* USB Device descriptor parameter */
+#define VENDOR_ID 0xC2AB
+#define PRODUCT_ID 0x0000
+#define DEVICE_VER 0x0001
+#define MANUFACTURER Pierre
+#define PRODUCT Ferris the keeb
+#define DESCRIPTION A minimalistic 34 - keys split keyboard
+
+/* key matrix size */
+#define MATRIX_ROWS 8
+#define MATRIX_COLS 10
+
+#define MATRIX_ROWS_PER_SIDE (MATRIX_ROWS / 2)
+#define MATRIX_COLS_PER_SIDE (MATRIX_COLS / 2)
+
+#define UNUSED_MCU 14
+#define UNUSED_MCP 7
+
+// wiring
+#define MATRIX_ROW_PINS_MCU \
+    { B3, B2, B1, F0 }
+#define MATRIX_COL_PINS_MCU \
+    { D6, D7, B4, B5, B6 }
+#define UNUSED_PINS_MCU \
+    { B0, B7, C6, C7, D2, D3, D4, D5, E6, F1, F4, F5, F6, F7 }
+#define MATRIX_ROW_PINS_MCP \
+    { B0, B1, B2, B3 }
+#define MATRIX_COL_PINS_MCP \
+    { A0, A1, A2, A3, A4 }
+#define UNUSED_PINS_MCP \
+    { B4, B5, B6, B7, A5, A6, A7 }
+
+/* COL2ROW, ROW2COL*/
+#define DIODE_DIRECTION COL2ROW
+
+/* define if matrix has ghost (lacks anti-ghosting diodes) */
+//#define MATRIX_HAS_GHOST
+
+/* Debounce reduces chatter (unintended double-presses) - set 0 if debouncing is not needed */
+#define DEBOUNCE 5
+
diff --git a/keyboards/handwired/ferris/ferris.c b/keyboards/handwired/ferris/ferris.c
new file mode 100644
index 0000000000..0e132fa984
--- /dev/null
+++ b/keyboards/handwired/ferris/ferris.c
@@ -0,0 +1,17 @@
+/*
+Copyright 2020 Pierre Chevalier <pierrechevalier83@gmail.com>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+#include "ferris.h"
diff --git a/keyboards/handwired/ferris/ferris.h b/keyboards/handwired/ferris/ferris.h
new file mode 100644
index 0000000000..4602637ca6
--- /dev/null
+++ b/keyboards/handwired/ferris/ferris.h
@@ -0,0 +1,43 @@
+/*
+Copyright 2020 Pierre Chevalier <pierrechevalier83@gmail.com>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#pragma once
+
+#include "quantum.h"
+
+// clang-format off
+
+/*              left hand                           right hand      */
+#define LAYOUT(\
+    K0_0, K0_1, K0_2, K0_3, K0_4,       K0_5, K0_6, K0_7, K0_8, K0_9,\
+    K1_0, K1_1, K1_2, K1_3, K1_4,       K1_5, K1_6, K1_7, K1_8, K1_9,\
+    K2_0, K2_1, K2_2, K2_3, K2_4,       K2_5, K2_6, K2_7, K2_8, K2_9,\
+                        K3_3, K3_4,   K3_5, K3_6)\
+/* matrix positions */\
+{\
+    {K0_0,  K0_1,  K0_2,  K0_3,  K0_4},\
+    {K1_0,  K1_1,  K1_2,  K1_3,  K1_4},\
+    {K2_0,  K2_1,  K2_2,  K2_3,  K2_4},\
+    {KC_NO, KC_NO, KC_NO, K3_3,  K3_4},\
+	\
+	{K0_5,  K0_6,  K0_7,  K0_8,  K0_9},\
+	{K1_5,  K1_6,  K1_7,  K1_8,  K1_9},\
+	{K2_5,  K2_6,  K2_7,  K2_8,  K2_9},\
+	{K3_5,  K3_6, KC_NO,  KC_NO, KC_NO}\
+}
+
+// clang-format on
diff --git a/keyboards/handwired/ferris/info.json b/keyboards/handwired/ferris/info.json
new file mode 100644
index 0000000000..ffffb58ecf
--- /dev/null
+++ b/keyboards/handwired/ferris/info.json
@@ -0,0 +1,54 @@
+{
+    "keyboard_name": "Ferris",
+    "url": "https://github.com/pierrechevalier83/ferris/",
+    "maintainer": "@pierrec83",
+    "width": 12,
+    "height": 4.75,
+    "layouts": {
+        "LAYOUT": {
+            "layout": [
+                {"x": 0, "y": 0.93},
+                {"x": 1, "y": 0.31},
+                {"x": 2, "y": 0},
+                {"x": 3, "y": 0.28},
+                {"x": 4, "y": 0.42},
+
+                {"x": 7, "y": 0.42},
+                {"x": 8, "y": 0.28},
+                {"x": 9, "y": 0},
+                {"x": 10, "y": 0.31},
+                {"x": 11, "y": 0.93},
+
+                {"x": 0, "y": 1.93},
+                {"x": 1, "y": 1.31},
+                {"x": 2, "y": 1},
+                {"x": 3, "y": 1.28},
+                {"x": 4, "y": 1.42},
+
+                {"x": 7, "y": 1.42},
+                {"x": 8, "y": 1.28},
+                {"x": 9, "y": 1},
+                {"x": 10, "y": 1.31},
+                {"x": 11, "y": 1.93},
+
+                {"x": 0, "y": 2.93},
+                {"x": 1, "y": 2.31},
+                {"x": 2, "y": 2},
+                {"x": 3, "y": 2.28},
+                {"x": 4, "y": 2.42},
+
+                {"x": 7, "y": 2.42},
+                {"x": 8, "y": 2.28},
+                {"x": 9, "y": 2},
+                {"x": 10, "y": 2.31},
+                {"x": 11, "y": 2.93},
+
+                {"x": 3.5, "y": 3.75},
+                {"x": 4.5, "y": 4},
+
+                {"x": 6.5, "y": 4},
+                {"x": 7.5, "y": 3.75}
+            ]
+        }
+    }
+}
diff --git a/keyboards/handwired/ferris/keymaps/default/config.h b/keyboards/handwired/ferris/keymaps/default/config.h
new file mode 100644
index 0000000000..cf0fb7478e
--- /dev/null
+++ b/keyboards/handwired/ferris/keymaps/default/config.h
@@ -0,0 +1,39 @@
+/*
+Copyright 2020 Pierre Chevalier <pierrechevalier83@gmail.com>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#pragma once
+// Set the mouse settings to a comfortable speed/accuracy trade-off,
+// assuming a screen refresh rate of 60 Htz or higher
+// The default is 50. This makes the mouse ~3 times faster and more accurate
+#define MOUSEKEY_INTERVAL 16
+// The default is 20. Since we made the mouse about 3 times faster with the previous setting,
+// give it more time to accelerate to max speed to retain precise control over short distances.
+#define MOUSEKEY_TIME_TO_MAX 40
+// The default is 300. Let's try and make this as low as possible while keeping the cursor responsive
+#define MOUSEKEY_DELAY 100
+// It makes sense to use the same delay for the mouseweel
+#define MOUSEKEY_WHEEL_DELAY 100
+// The default is 100
+#define MOUSEKEY_WHEEL_INTERVAL 50
+// The default is 40
+#define MOUSEKEY_WHEEL_TIME_TO_MAX 100
+
+// Pick good defaults for enabling homerow modifiers
+#define TAPPING_TERM 200
+#define PERMISSIVE_HOLD
+#define IGNORE_MOD_TAP_INTERRUPT
+#define TAPPING_FORCE_HOLD
diff --git a/keyboards/handwired/ferris/keymaps/default/keymap.c b/keyboards/handwired/ferris/keymaps/default/keymap.c
new file mode 100644
index 0000000000..faf5203e7d
--- /dev/null
+++ b/keyboards/handwired/ferris/keymaps/default/keymap.c
@@ -0,0 +1,39 @@
+/*
+Copyright 2020 Pierre Chevalier <pierrechevalier83@gmail.com>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include QMK_KEYBOARD_H
+
+// Blank template at the bottom
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+/* Keymap 0: Qwerty
+ *
+ * ,-----------------------------.      ,-----------------------------.
+ * |  Q  |  W  |  E  |  R  |  T  |      |  Y  |  U  |  I  |  O  |  P  |
+ * |-----+-----+-----+-----+-----|      |-----------------------------|
+ * |  A  |  S  |  D  |  F  |  G  |      |  H  |  J  |  K  |  L  |  ;  |
+ * |-----+-----+-----+-----+-----+      |-----------------------------|
+ * |  Z  |  X  |  C  |  V  |  B  |      |  N  |  M  |  <  |  >  |  ?  |
+ * `-----+-----+-----+-----+-----+--. ,-+-----------------------------'
+ *                     | BSPC | SPC | | SPC | ENT |
+ *                     '------------' '-----------'
+ */
+[0] = LAYOUT(
+    KC_Q, KC_W, KC_E, KC_R, KC_T,       KC_Y, KC_U, KC_I,    KC_O,   KC_P,
+    KC_A, KC_S, KC_D, KC_F, KC_G,       KC_H, KC_J, KC_K,    KC_L,   KC_SCLN,
+    KC_Z, KC_X, KC_C, KC_V, KC_B,       KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH,
+                   KC_BSPC, KC_SPC,   KC_SPC, KC_ENT)
+};
diff --git a/keyboards/handwired/ferris/matrix.c b/keyboards/handwired/ferris/matrix.c
new file mode 100644
index 0000000000..e13c35d358
--- /dev/null
+++ b/keyboards/handwired/ferris/matrix.c
@@ -0,0 +1,282 @@
+/*
+Copyright 2013 Oleg Kostyuk <cub.uanic@gmail.com>
+          2020 Pierre Chevalier <pierrechevalier83@gmail.com>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/*
+ * This code was heavily inspired by the ergodox_ez keymap, and modernized
+ * to take advantage of the quantum.h microcontroller agnostics gpio control
+ * abstractions and use the macros defined in config.h for the wiring as opposed
+ * to repeating that information all over the place.
+ */
+
+#include QMK_KEYBOARD_H
+#include "i2c_master.h"
+
+extern i2c_status_t mcp23017_status;
+#define I2C_TIMEOUT 1000
+
+// For a better understanding of the i2c protocol, this is a good read:
+// https://www.robot-electronics.co.uk/i2c-tutorial
+
+// I2C address:
+// See the datasheet, section 3.3.1 on addressing I2C devices and figure 3-6 for an
+// illustration
+// http://ww1.microchip.com/downloads/en/devicedoc/20001952c.pdf
+// All address pins of the mcp23017 are connected to the ground on the ferris
+// | 0  | 1  | 0  | 0  | A2 | A1 | A0 |
+// | 0  | 1  | 0  | 0  | 0  | 0  | 0  |
+#define I2C_ADDR 0b0100000
+#define I2C_ADDR_WRITE ((I2C_ADDR << 1) | I2C_WRITE)
+#define I2C_ADDR_READ ((I2C_ADDR << 1) | I2C_READ)
+
+// Register addresses
+// See https://github.com/adafruit/Adafruit-MCP23017-Arduino-Library/blob/master/Adafruit_MCP23017.h
+#define IODIRA 0x00  // i/o direction register
+#define IODIRB 0x01
+#define GPPUA 0x0C  // GPIO pull-up resistor register
+#define GPPUB 0x0D
+#define GPIOA 0x12  // general purpose i/o port register (write modifies OLAT)
+#define GPIOB 0x13
+#define OLATA 0x14  // output latch register
+#define OLATB 0x15
+
+bool         i2c_initialized = 0;
+i2c_status_t mcp23017_status = I2C_ADDR;
+
+uint8_t init_mcp23017(void) {
+    print("starting init");
+    mcp23017_status = I2C_ADDR;
+
+    // I2C subsystem
+    if (i2c_initialized == 0) {
+        i2c_init();  // on pins D(1,0)
+        i2c_initialized = true;
+        wait_ms(I2C_TIMEOUT);
+    }
+
+    // set pin direction
+    // - unused  : input  : 1
+    // - input   : input  : 1
+    // - driving : output : 0
+    mcp23017_status = i2c_start(I2C_ADDR_WRITE, I2C_TIMEOUT);
+    if (mcp23017_status) goto out;
+    mcp23017_status = i2c_write(IODIRA, I2C_TIMEOUT);
+    if (mcp23017_status) goto out;
+    // This means: we will read all the bits on GPIOA
+    mcp23017_status = i2c_write(0b11111111, I2C_TIMEOUT);
+    if (mcp23017_status) goto out;
+    // This means: we will write to the pins 0-4 on GPIOB (in select_rows)
+    mcp23017_status = i2c_write(0b11110000, I2C_TIMEOUT);
+    if (mcp23017_status) goto out;
+    i2c_stop();
+
+    // set pull-up
+    // - unused  : on  : 1
+    // - input   : on  : 1
+    // - driving : off : 0
+    mcp23017_status = i2c_start(I2C_ADDR_WRITE, I2C_TIMEOUT);
+    if (mcp23017_status) goto out;
+    mcp23017_status = i2c_write(GPPUA, I2C_TIMEOUT);
+    if (mcp23017_status) goto out;
+    // This means: we will read all the bits on GPIOA
+    mcp23017_status = i2c_write(0b11111111, I2C_TIMEOUT);
+    if (mcp23017_status) goto out;
+    // This means: we will write to the pins 0-4 on GPIOB (in select_rows)
+    mcp23017_status = i2c_write(0b11110000, I2C_TIMEOUT);
+    if (mcp23017_status) goto out;
+
+out:
+    i2c_stop();
+    return mcp23017_status;
+}
+
+/* matrix state(1:on, 0:off) */
+static matrix_row_t matrix[MATRIX_ROWS];      // debounced values
+
+static matrix_row_t read_cols(uint8_t row);
+static void         init_cols(void);
+static void         unselect_rows(void);
+static void         select_row(uint8_t row);
+
+static uint8_t mcp23017_reset_loop;
+
+void matrix_init_custom(void) {
+    // initialize row and col
+
+    mcp23017_status = init_mcp23017();
+
+    unselect_rows();
+    init_cols();
+
+    // initialize matrix state: all keys off
+    for (uint8_t i = 0; i < MATRIX_ROWS; i++) {
+        matrix[i]     = 0;
+    }
+}
+
+void matrix_power_up(void) {
+    mcp23017_status = init_mcp23017();
+
+    unselect_rows();
+    init_cols();
+
+    // initialize matrix state: all keys off
+    for (uint8_t i = 0; i < MATRIX_ROWS; i++) {
+        matrix[i] = 0;
+    }
+}
+
+// Reads and stores a row, returning
+// whether a change occurred.
+static inline bool store_matrix_row(matrix_row_t current_matrix[], uint8_t index) {
+    matrix_row_t temp = read_cols(index);
+    if (current_matrix[index] != temp) {
+        current_matrix[index] = temp;
+        return true;
+    }
+    return false;
+}
+
+bool matrix_scan_custom(matrix_row_t current_matrix[]) {
+    if (mcp23017_status) {  // if there was an error
+        if (++mcp23017_reset_loop == 0) {
+            // if (++mcp23017_reset_loop >= 1300) {
+            // since mcp23017_reset_loop is 8 bit - we'll try to reset once in 255 matrix scans
+            // this will be approx bit more frequent than once per second
+            dprint("trying to reset mcp23017\n");
+            mcp23017_status = init_mcp23017();
+            if (mcp23017_status) {
+                dprint("right side not responding\n");
+            } else {
+                dprint("right side attached\n");
+            }
+        }
+    }
+
+    bool changed = false;
+    for (uint8_t i = 0; i < MATRIX_ROWS_PER_SIDE; i++) {
+        // select rows from left and right hands
+        uint8_t left_index  = i;
+        uint8_t right_index = i + MATRIX_ROWS_PER_SIDE;
+        select_row(left_index);
+        select_row(right_index);
+
+        // we don't need a 30us delay anymore, because selecting a
+        // left-hand row requires more than 30us for i2c.
+
+        changed |= store_matrix_row(current_matrix, left_index);
+        changed |= store_matrix_row(current_matrix, right_index);
+
+        unselect_rows();
+    }
+
+    return changed;
+}
+
+static void init_cols(void) {
+    // init on mcp23017
+    // not needed, already done as part of init_mcp23017()
+
+    // init on mcu
+    pin_t matrix_col_pins_mcu[MATRIX_COLS_PER_SIDE] = MATRIX_COL_PINS_MCU;
+    for (int pin_index = 0; pin_index < MATRIX_COLS_PER_SIDE; pin_index++) {
+        pin_t pin = matrix_col_pins_mcu[pin_index];
+        setPinInput(pin);
+        writePinHigh(pin);
+    }
+}
+
+static matrix_row_t read_cols(uint8_t row) {
+    if (row < MATRIX_ROWS_PER_SIDE) {
+        pin_t        matrix_col_pins_mcu[MATRIX_COLS_PER_SIDE] = MATRIX_COL_PINS_MCU;
+        matrix_row_t current_row_value                         = 0;
+        // For each col...
+        for (uint8_t col_index = 0; col_index < MATRIX_COLS_PER_SIDE; col_index++) {
+            // Select the col pin to read (active low)
+            uint8_t pin_state = readPin(matrix_col_pins_mcu[col_index]);
+
+            // Populate the matrix row with the state of the col pin
+            current_row_value |= pin_state ? 0 : (MATRIX_ROW_SHIFTER << col_index);
+        }
+        return current_row_value;
+    } else {
+        if (mcp23017_status) {  // if there was an error
+            return 0;
+        } else {
+            uint8_t data    = 0;
+            mcp23017_status = i2c_start(I2C_ADDR_WRITE, I2C_TIMEOUT);
+            if (mcp23017_status) goto out;
+            mcp23017_status = i2c_write(GPIOA, I2C_TIMEOUT);
+            if (mcp23017_status) goto out;
+            mcp23017_status = i2c_start(I2C_ADDR_READ, I2C_TIMEOUT);
+            if (mcp23017_status) goto out;
+            mcp23017_status = i2c_read_nack(I2C_TIMEOUT);
+            if (mcp23017_status < 0) goto out;
+            // We read all the pins on GPIOA.
+            // The initial state was all ones and any depressed key at a given column for the currently selected row will have its bit flipped to zero.
+            // The return value is a row as represented in the generic matrix code were the rightmost bits represent the lower columns and zeroes represent non-depressed keys while ones represent depressed keys.
+            // Since the pins connected to eact columns are sequential, and counting from zero up (col 5 -> GPIOA0, col 6 -> GPIOA1 and so on), the only transformation needed is a bitwise not to swap all zeroes and ones.
+            data            = ~((uint8_t)mcp23017_status);
+            mcp23017_status = I2C_STATUS_SUCCESS;
+        out:
+            i2c_stop();
+            // return reverse_bits(data, MATRIX_COLS_PER_SIDE);
+            return data;
+        }
+    }
+}
+
+static void unselect_rows(void) {
+    // no need to unselect on mcp23017, because the select step sets all
+    // the other row bits high, and it's not changing to a different
+    // direction
+
+    // unselect rows on microcontroller
+    pin_t matrix_row_pins_mcu[MATRIX_ROWS_PER_SIDE] = MATRIX_ROW_PINS_MCU;
+    for (int pin_index = 0; pin_index < MATRIX_ROWS_PER_SIDE; pin_index++) {
+        pin_t pin = matrix_row_pins_mcu[pin_index];
+        setPinInput(pin);
+        writePinLow(pin);
+    }
+}
+
+static void select_row(uint8_t row) {
+    if (row < MATRIX_ROWS_PER_SIDE) {
+        // select on atmega32u4
+        pin_t matrix_row_pins_mcu[MATRIX_ROWS_PER_SIDE] = MATRIX_ROW_PINS_MCU;
+        pin_t pin                                       = matrix_row_pins_mcu[row];
+        setPinOutput(pin);
+        writePinLow(pin);
+    } else {
+        // select on mcp23017
+        if (mcp23017_status) {  // if there was an error
+                                // do nothing
+        } else {
+            mcp23017_status = i2c_start(I2C_ADDR_WRITE, I2C_TIMEOUT);
+            if (mcp23017_status) goto out;
+            mcp23017_status = i2c_write(GPIOB, I2C_TIMEOUT);
+            if (mcp23017_status) goto out;
+            // Select the desired row by writing a byte for the entire GPIOB bus where only the bit representing the row we want to select is a zero (write instruction) and every other bit is a one.
+            // Note that the row - MATRIX_ROWS_PER_SIDE reflects the fact that being on the right hand, the columns are numbered from MATRIX_ROWS_PER_SIDE to MATRIX_ROWS, but the pins we want to write to are indexed from zero up on the GPIOB bus.
+            mcp23017_status = i2c_write(0xFF & ~(1 << (row - MATRIX_ROWS_PER_SIDE)), I2C_TIMEOUT);
+
+            if (mcp23017_status) goto out;
+        out:
+            i2c_stop();
+        }
+    }
+}
diff --git a/keyboards/handwired/ferris/readme.md b/keyboards/handwired/ferris/readme.md
new file mode 100644
index 0000000000..23aeca874c
--- /dev/null
+++ b/keyboards/handwired/ferris/readme.md
@@ -0,0 +1,16 @@
+# Ferris
+
+![Ferris, top view](https://imgur.com/V4QuaGs.jpg)
+![Ferris, bottom view](https://i.imgur.com/7DJYME8.jpg)
+
+A split 34 keys column staggered keyboard named and decorated after the rustlang mascott. All PCB files and some thoughts on the design are available on the [project's github page](https://github.com/pierrechevalier83/ferris)
+
+* Keyboard Maintainer: [Pierre Chevalier](https://github.com/pierrechevalier83)
+* Hardware Supported: Ferris PCB
+* Hardware Availability: Still in prototype stage
+
+Make example for this keyboard (after setting up your build environment):
+
+    make handwired/ferris:default
+
+See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
diff --git a/keyboards/handwired/ferris/rules.mk b/keyboards/handwired/ferris/rules.mk
new file mode 100644
index 0000000000..8645dbba0d
--- /dev/null
+++ b/keyboards/handwired/ferris/rules.mk
@@ -0,0 +1,28 @@
+# MCU name
+MCU = atmega32u4
+
+# Bootloader selection
+BOOTLOADER = atmel-dfu
+
+#   change yes to no to disable
+#
+BOOTMAGIC_ENABLE = no       # Virtual DIP switch configuration
+MOUSEKEY_ENABLE = yes       # Mouse keys
+EXTRAKEY_ENABLE = yes       # Audio control and System control
+CONSOLE_ENABLE = no         # Console for debug
+COMMAND_ENABLE = no         # Commands for debug and configuration
+# Do not enable SLEEP_LED_ENABLE. it uses the same timer as BACKLIGHT_ENABLE
+SLEEP_LED_ENABLE = no       # Breathing sleep LED during USB suspend
+# if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
+NKRO_ENABLE = no            # USB Nkey Rollover
+BACKLIGHT_ENABLE = no       # Enable keyboard backlight functionality
+RGBLIGHT_ENABLE = no        # Enable keyboard RGB underglow
+BLUETOOTH_ENABLE = no       # Enable Bluetooth
+AUDIO_ENABLE = no           # Audio output
+UNICODE_ENABLE = yes
+CUSTOM_MATRIX = lite
+NO_USB_STARTUP_CHECK = yes
+LTO_ENABLE = yes
+
+SRC += matrix.c
+QUANTUM_LIB_SRC += i2c_master.c