Merge pull request #60 from minipadKB/master

Release firmware version `2024.309.1`

.vscode/settings.json

@@ -15,7 +15,9 @@
         "iosfwd": "cpp",
         "limits": "cpp",
         "streambuf": "cpp",
-        "string_view": "cpp"
+        "string_view": "cpp",
+        "cstdint": "cpp",
+        "random": "cpp"
     },
     "cmake.configureOnOpen": false
 }

CHANGELOG.md

@@ -1,3 +1,18 @@
+# 2024.309.1 - Auto-calibration & Gauss correction
+
+This release was long overdue. Auto-calibration has been added, removing the need to manually calibrate the rest- and down positions via minitool.
+It also adds calculations to correct the slightly non-linear relation between magnetic field strength (what the sensor measures) and the actual distance of the magnet.
+
+## Features
+
+- Calibration is now automatically performed, with a definition `AUTO_CALIBRATION_DEADZONE` to introduce a deadzone, considering for rare peaks towards the boundaries
+- Added correction of the relation between the magnetic field strength (the analog value) and the actual, physical distance of the magnet from the sensor. (Co-authored by @RephlexZero)
+
+## Changes
+
+- Removed the `out <bool>` command
+- The whole codebase went under huge re-structuring, improving code quality and maintainability. More can be found at https://github.com/minipadKB/minipad-firmware/pull/56
+
 # 2023.813.1 - QoL Update
 
 This release does a lot of QoL changes, as well as doing the final preparations of the firmware for compabitility with the upcoming configuration software, minitility!</br>

README.md

@@ -3,7 +3,7 @@
 # minipad-firmware
 
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![Discord](https://img.shields.io/discord/1056311828344483840?label=discord&color=7289da)](https://discord.gg/minipad)
+[![Discord](https://img.shields.io/discord/1056311828344483840?label=discord&color=7289da)](https://discord.gg/hQJ6dq7qBa)
 [![Downloads](https://img.shields.io/github/downloads/minipadkb/minipad-firmware/total)](https://github.com/minipadKB/minipad-firmware/releases/latest)
 [![Latest Release](https://img.shields.io/github/v/release/minipadkb/minipad-firmware?color=dd00dd)](https://github.com/minipadKB/minipad-firmware/releases/latest)
 
@@ -32,7 +32,7 @@ Here is a list of features that are both planned and available:
 - Software-based low pass filter for analog stability
 - Configurable keychar pressed upon key interaction
 - Serial communication protocol for configuration
-- UI application for configuration, [minitility](https://github.com/minipadkb/minitility)
+- A command-line tool for configuration, [minitool](https://github.com/minipadkb/minitool)
 
 Planned Features 🗒️
 -
@@ -41,7 +41,7 @@ Planned Features 🗒️
 
 # Installation ⚡
 
-To flash this firmware on your minipad or other RP2040 board, please refer to our [firmware installation guide](https://minipad.minii.moe/docs/minipad/install-firmware). In there, you can find the instructions on how to initially load the firmware on the keypad, and how to update it later on.
+To flash this firmware on your minipad or other RP2040 board, please refer to our [firmware installation guide](https://minipadkb.github.io/minipad-wiki/docs/minipad/install-firmware). In there, you can find the instructions on how to initially load the firmware on the keypad, and how to update it later on.
 
 # Setup for development 💻
 
@@ -52,12 +52,12 @@ After that is done, clone the repository with `git clone https://github.com/mini
 
 If you are not familiar with the usage of PlatformIO, a Quick Start guide can be found [here](https://docs.platformio.org/en/stable/integration/ide/vscode.html).
 
-Note: Uploading the firmware only works if the micro controller is set into bootloader mode. This can be done using the BOOTSEL button on development boards or setting the minipad into bootloader mode via minitility. A guide on the latter can be found [here](https://minipad.minii.moe/docs/minitility/get-started).
+Note: Uploading the firmware only works if the micro controller is set into bootloader mode. This can be done using the BOOTSEL button on development boards or setting the minipad into bootloader mode/flashing directly via minitool. Help on the latter can be found [here](https://github.com/minipadkb/minitool?tab=readme-ov-file#usage).
 
 # Minipad Serial Protocol (MSP) 🔗
 
 The firmware is being configured and accessed from the host device via Serial communication at a baud rate of 115200.
-We are working on a web-based UI application called "minitility" for communicating with the firmware. You can find the git repository [here](https://github.com/minipadkb/minitility).
+There is a command-line utility tool called "minitool" for communicating with the firmware. You can find the git repository [here](https://github.com/minipadkb/minitool).
 
 All data sent via the serial interface is being interpreted as a command with the following syntax:
 `command arg0 arg1 arg2 ...`. The command and it's arguments are split by whitespaces, ending with a newline character.
@@ -92,9 +92,9 @@ Here is a list of commands and examples for them:
 *Description*: Sets the name of the minipad, used to distinguish different devices visually.
 
 *Command*: `out`</br>
-*Syntax*: `out [bool]`</br>
-*Example*: `out true`, `out 0`, `out`</br>
-*Description*: Enables/Disables the output mode. The output mode writes the sensor values to the serial monitor. If no parameter is specified, the values are written once.
+*Syntax*: `out`</br>
+*Example*: `out`</br>
+*Description*: Returns the sensor values and magnet distance of all Hall Effect keys.
 
 *Command*: `echo` (debug-exclusive)</br>
 *Syntax*: `echo <string>`</br>

include/config/configuration.hpp

@@ -1,7 +1,7 @@
 #pragma once
 
-#include "config/keys/he_key.hpp"
-#include "config/keys/digital_key.hpp"
+#include "config/keys/he_key_config.hpp"
+#include "config/keys/digital_key_config.hpp"
 
 // Configuration for the whole firmware, containing the name of the keypad and it's configurations.
 struct Configuration
@@ -13,16 +13,16 @@ struct Configuration
     char name[128] = "minipad";
 
     // A list of all hall effect key configurations. (rapid trigger, hysteresis, calibration, ...)
-    HEKey heKeys[HE_KEYS];
+    HEKeyConfig heKeys[HE_KEYS];
 
     // A list of all digital key configurations. (key char, hid state, ...)
-    DigitalKey digitalKeys[DIGITAL_KEYS];
+    DigitalKeyConfig digitalKeys[DIGITAL_KEYS];
 
     // Returns the version constant of the latest Configuration layout.
     static uint32_t getVersion()
     {
         // Version of the configuration in the format YYMMDDhhmm (e.g. 2301030040 for 12:44am on the 3rd january 2023)
-        int64_t version = 2308130046;
+        int64_t version = 2308161815;
 
         return version;
     }

include/config/configuration_controller.hpp

@@ -27,13 +27,15 @@ inline class ConfigurationController
     {
         Configuration config;
 
-        // Populate the hall effect keys array with the correct amount of hall effect keys.
+        // Populate the Hall Effect keys array with the correct amount of Hall Effect keys.
+        // Assign the key char from z downwards (z, y, x, w, v, ...). After 26 keys, stick to an 'a' key to not overflow.
         for (uint8_t i = 0; i < HE_KEYS; i++)
-            config.heKeys[i] = HEKey(i);
+            config.heKeys[i] = HEKeyConfig(i >= 26 ? 'a' : (char)('z' - i));
 
         // Populate the digital keys array with the correct amount of digital keys.
+    // Assign the key char from a forwards (a, b, c, d, e, ...). After 26 keys, stick to an 'z' key to not overflow.
         for (uint8_t i = 0; i < DIGITAL_KEYS; i++)
-            config.digitalKeys[i] = DigitalKey(i);
+            config.digitalKeys[i] = DigitalKeyConfig(i >= 26 ? 'z' : (char)('a' + i));
 
         return config;
     };

include/config/keys/digital_key_config.hpp

@@ -0,0 +1,17 @@
+#pragma once
+
+#include <cstdint>
+#include "config/keys/key_config.hpp"
+
+// Configuration for the digital keys of the keypad.
+struct DigitalKeyConfig : KeyConfig
+{
+    // Default constructor for the DigitalKeyConfig struct for initializing the arrays in the Configuration struct.
+    DigitalKeyConfig() : KeyConfig('\0') {}
+
+    // Initialize with the specified key char.
+    DigitalKeyConfig(char keyChar) : KeyConfig(keyChar) {}
+
+    // This struct is empty on purpose. The only purpose it serves is explicitly having
+    // a type for the digital keys, instead of differentiating between KeyConfig and DigitalKeyConfig.
+};

include/config/keys/he_key.hpp → include/config/keys/he_key_config.hpp

@@ -1,19 +1,17 @@
 #pragma once
 
 #include <cstdint>
-#include "config/keys/key.hpp"
-#include "config/keys/key_type.hpp"
+#include "config/keys/key_config.hpp"
 #include "definitions.hpp"
 
-// Configuration for the hall effect keys of the keypad, containing the actuation points, calibration, sensitivities etc. of the key.
-struct HEKey : Key
+// Configuration for the Hall Effect keys of the keypad, containing the actuation points, calibration, sensitivities etc. of the key.
+struct HEKeyConfig : KeyConfig
 {
-    // Default constructor for the HEKey struct for initializing the arrays in the Configuration struct.
-    HEKey() : Key(KeyType::HallEffect, 0, '\0') {}
+    // Default constructor for the HEKeyConfig struct for initializing the arrays in the Configuration struct.
+    HEKeyConfig() : KeyConfig('\0') {}
 
-    // Initialize with the correct type for identifying the type of key that a Key object was initialized as (e.g. HEKey) and index.
-    // Assign the key char from z downwards (z, y, x, w, v, ...). After 26 keys, stick to an 'a' key to not overflow.
-    HEKey(uint8_t index) : Key(KeyType::HallEffect, index, index >= 26 ? 'a' : (char)('z' - index)) {}
+    // Initialize with the specified key char.
+    HEKeyConfig(char keyChar) : KeyConfig(keyChar) {}
 
     // Bool whether rapid trigger is enabled or not.
     bool rapidTrigger = false;
@@ -32,8 +30,4 @@ struct HEKey : Key
 
     // The value below which the key is no longer pressed and rapid trigger is no longer active in rapid trigger mode.
     uint16_t upperHysteresis = (uint16_t)(TRAVEL_DISTANCE_IN_0_01MM * 0.675);
-
-    // The value read when the keys are in rest position/all the way down.
-    uint16_t restPosition = pow(2, ANALOG_RESOLUTION) - 1; // Set to the outer boundaries in order to make
-    uint16_t downPosition = 0;                             // them overwritable by the calibration code.
 };

include/config/keys/key_config.hpp

@@ -0,0 +1,16 @@
+#pragma once
+
+#include <cstdint>
+
+// The base configuration struct for the DigitalKeyConfig and HEKeyConfig struct, containing the common fields.
+struct KeyConfig
+{
+    // Require every key config to be initialized with a key char.
+    KeyConfig(char keyChar) : keyChar(keyChar) {}
+
+    // The corresponding key sent via HID interface.
+    char keyChar;
+
+    // Bools whether HID commands are sent on the key.
+    bool hidEnabled = false;
+};

include/definitions.hpp

@@ -1,7 +1,7 @@
 #pragma once
 
 // The version of this firmware in the YYYY.MDD.PATCH format. (e.g. 2022.1219.2 for the 2nd release on the 19th december 2022)
-#define FIRMWARE_VERSION "2023.813.1"
+#define FIRMWARE_VERSION "2024.309.1"
 
 // ┌───────────────────────────────────────────────────────────────────────────────────────────────────┐
 // │                                                                                                   │
@@ -26,7 +26,33 @@
 // This value is important to reset the rapid trigger state properly with continuous rapid trigger.
 #define CONTINUOUS_RAPID_TRIGGER_THRESHOLD 10
 
-// The resolution for the ADCs on the RP2040. The maximum compatible value on it is 16 bit.
+// This number will be added to the down position and substracted from the rest position on bounary update
+// to introduce a deadzone at the boundaries. This might be desired since values might fluctuate.
+// e.g. if the value fluctuates around 1970 in rest position but peaks at 1975, this would counteract it.
+// 10 may seem like much at first but when "smashing" the button a lot it'll be just right.
+#define SENSOR_BOUNDARY_DEADZONE 10
+
+// The minimum difference between the rest position and the deadzone-applied down position.
+// It is important to mantain a minimum analog range to prevent "crazy behavior".
+#define SENSOR_BOUNDARY_MIN_DISTANCE 200
+
+// Flag for enabling gauss correction. This improves the accuracy of the sensor readings by correcting the curve of
+// the relation between the magnetic field strength near the sensor and the distance of the magnet from the sensor.
+// If this firmware is used on a device with different magnets, the values below have to be adjusted or gauss correction has to be disabled.
+#define USE_GAUSS_CORRECTION_LUT
+
+// Variables for the equation to calculate the ADC reading into a physical distance. These numbers are chosen by trial-and-error, making the curve fit.
+// These values are only effective on magnets like the ones used in the Gateron-KS 20 or the Wooting Lekkers, which are based on them.
+// This gauss correction is also dependent on the hardware specifications. The switch should be as close to the Hall Effect sensor as possible.
+// The Hall Effect sensor used is the 49E sensor, therefore these values are highly tailored towards the hardware of the minipad.
+// If this firmware is used on a device with different magnets/hardware, these values have to be adjusted or gauss correction has to be disabled.
+// The equation for the gauss correction is based off the following Desmos sheet and can be used for adjustments: https://www.desmos.com/calculator/ps4wd127tu
+#define GAUSS_CORRECTION_PARAM_A 6647.8446648
+#define GAUSS_CORRECTION_PARAM_B -0.00609446727442
+#define GAUSS_CORRECTION_PARAM_C -721.743991123
+#define GAUSS_CORRECTION_PARAM_D 4525.58542876
+
+// The resolution for the ADCs on the RP2040. The theoretical maximum value on it is 16 bit (uint16_t).
 #define ANALOG_RESOLUTION 12
 
 // The buffer size of any serial input. Defined here for consistent use across the serial handler and avoiding of magic numbers.

include/handlers/key_handler.hpp

@@ -0,0 +1,41 @@
+#pragma once
+#pragma GCC diagnostic ignored "-Wtype-limits"
+
+#include "config/configuration_controller.hpp"
+#include "handlers/keys/he_key.hpp"
+#include "handlers/keys/digital_key.hpp"
+#include "helpers/sma_filter.hpp"
+#include "helpers/gauss_lut.hpp"
+#include "definitions.hpp"
+
+inline class KeyHandler
+{
+public:
+    KeyHandler()
+    {
+        // Assign indicies and their corresponding HEKeyConfig to all Hall Effect keys.
+        for (uint8_t i = 0; i < HE_KEYS; i++)
+            heKeys[i] = HEKey(i, &ConfigController.config.heKeys[i]);
+
+        // Assign indicies and their corresponding DigitalKeyConfig to all digital keys.
+        for (uint8_t i = 0; i < DIGITAL_KEYS; i++)
+            digitalKeys[i] = DigitalKey(i, &ConfigController.config.digitalKeys[i]);
+    }
+
+    void handle();
+    bool outputMode;
+    HEKey heKeys[HE_KEYS];
+    DigitalKey digitalKeys[DIGITAL_KEYS];
+
+private:
+    void updateSensorBoundaries(HEKey &key);
+    void checkHEKey(HEKey &key);
+    void checkDigitalKey(DigitalKey &key);
+    void scanHEKey(HEKey &key);
+    void scanDigitalKey(DigitalKey &key);
+    void setPressedState(Key &key, bool pressed);
+
+#ifdef USE_GAUSS_CORRECTION_LUT
+    GaussLUT gaussLUT = GaussLUT(GAUSS_CORRECTION_PARAM_A, GAUSS_CORRECTION_PARAM_B, GAUSS_CORRECTION_PARAM_C, GAUSS_CORRECTION_PARAM_D);
+#endif
+} KeyHandler;