documentation and inactive mode code

docs/firmware/firmware-architecture.md

@@ -0,0 +1,132 @@
+# Firmware Architecture
+
+The firmware operates under **three distinct modes** that define the device’s behavior:
+
+```c
+#define MODE_INACTIVE 0
+#define MODE_MASTER   1
+#define MODE_MODULE   2
+```
+
+These modes dictate how the system processes input and manages data flow between modules. Together, they establish the rules for communication and arbitration within the modular keyboard system.
+
+
+## Master Mode
+
+In **Master Mode**, the device behaves like a standard keyboard connected to a host via USB. However, it also takes on additional responsibilities:
+
+* **USB Handling**: Sends keypress reports directly to the host.
+* **Neighbor Listening**: Receives keypress messages from connected Module devices and integrates them into the USB report.
+* **Device Queries**: Responds to discovery or status requests from devices currently in **Inactive Mode**.
+
+👉 The system can only enter Master Mode if it is physically connected to a USB host.
+
+## Module Mode
+
+In **Module Mode**, the device functions similarly to Master Mode but with one key difference:
+
+* Instead of sending reports to the USB host, the device forwards its keypress data upstream to its **parent device**.
+
+This parent is determined during the discovery process in Inactive Mode. The parent may be either the Master itself or another Module closer to the Master.
+
+## Inactive Mode
+
+**Inactive Mode** is the initial state of every device upon power-up (unless it is directly connected to USB).
+
+Behavior in this mode includes:
+
+* **Ignoring Local Inputs**: The device does not process its own switch presses.
+* **Discovery Queries**: The device broadcasts a query to its neighbors to determine its parent.
+* **Awaiting Responses**: Active devices (Master or Modules) respond with a **depth value**—a numerical measure of distance (in hops) to the Master.
+
+  * The Master has a depth of **0**.
+  * Each Module reports its depth as `(parent depth + 1)`.
+
+The querying device selects a parent based on the lowest reported depth. This ensures the shortest and most efficient communication path to the Master.
+
+**Example:**
+If device A reports depth = 2, and device B reports depth = 4, the querying device sets:
+
+* **Parent = A**
+* **Depth = 3**
+
+After selecting a parent, the device transitions from **Inactive Mode → Module Mode**.
+
+Devices already in Master or Module mode should respond to discovery queries with their current depth value.
+
+Ooh\~ let’s make your UART DMA explanation sparkle ✨ I’ll clean it up, add clarity on why interrupts could be tricky, and make the flow a bit more structured. Here’s a polished version:
+
+
+# UART Queue with DMA
+
+Data transmission in this system is handled via **UART**. However, standard UART operations are **blocking**:
+
+* When sending or receiving data without DMA, the CPU must wait until the operation completes.
+* Running UART directly in the main loop would **stall other critical processes**, such as scanning keypresses or handling module communication.
+
+An alternative is using **interrupts**, which allow the CPU to continue running while UART signals completion.
+
+**Problem:** Interrupts can occur at any moment, potentially interrupting time-sensitive operations like key scanning or other UART transactions.
+* Frequent or nested interrupts could lead to **race conditions**, data corruption, or missed key events.
+
+
+## DMA Solution
+
+The system uses **DMA (Direct Memory Access)** to offload UART data handling:
+
+* Each RX port operates via DMA, continuously collecting incoming data **without CPU intervention**.
+* Received data is placed into a **queue**.
+* During the main loop, the firmware checks the queue:
+
+  * If the queue is not empty, it transmits the collected data to the parent/master device.
+
+This system allows UART to behave like a **background subprocess**, leaving the CPU free for:
+
+* Scanning the module’s own keys.
+* Processing received messages.
+* Managing the module-to-master communication efficiently.
+
+## Queue Usage
+
+The **same queue system** also handles the module’s own keypresses:
+
+* Key events are pushed into the queue as they are detected.
+* The main loop processes the queue, sending keypresses to the master device.
+
+This unified queue system ensures **non-blocking, deterministic communication** between modules and the master, even under high data load.
+
+Ooo~ let’s give your UART message section a little sparkle ✨ and make it clearer, more structured, and easier to read. I’ll also fix formatting inconsistencies and clarify the purpose of each field. 💙  
+
+---
+
+# UART Message Structure  
+
+Each UART message is **32 bits (4 bytes)** and structured as follows:  
+
+| Byte 0 (MSB)        | Byte 1            | Byte 2      | Byte 3 (LSB) |
+|---------------------|-----------------|------------|--------------|
+| Sender’s Depth      | Message Type      | Extra Bits | Key Code     |
+
+**Field Descriptions:**  
+
+- **Sender’s Depth:** Indicates the module’s distance from the Master device. Useful for routing and arbitration.  
+- **Message Type:** Determines the purpose of the message (see below).  
+- **Extra Bits:** Reserved for additional flags or future extensions.  
+- **Key Code:** Represents the key being pressed (or released).  
+
+
+## Message Types  
+
+| Value  | Name                   | Description                                                                 |
+|--------|------------------------|-----------------------------------------------------------------------------|
+| 0x0F   | Handshake Request       | Sent by modules in **Inactive Mode** to discover parent/master devices.    |
+| 0xFF   | Handshake Confirmation  | Sent by active modules (or Master) in response to a Handshake Request.    |
+| 0x01   | Keycode Message         | Generic keycode message sent from module to master.                        |
+
+
+**Notes:**  
+
+- All communication between modules follows this 4-byte structure.  
+- Depth values help modules select the optimal parent device.  
+- Reserved **Extra Bits** can later store flags like key release, special functions, or priority indicators.  
+

firmware/core/Core/Src/main.c

@@ -7,6 +7,8 @@
 #define MODE_MODULE 2
 #define DMA_BUFFER_SIZE 16
 
+#define MODULE_HANDSHAKE_REQUEST 0x000F0000
+
 typedef struct{
   uint8_t data[4];
 } Packet;
@@ -26,6 +28,8 @@ UART_HandleTypeDef huart4;
 UART_HandleTypeDef huart5;
 UART_HandleTypeDef huart1;
 UART_HandleTypeDef huart2;
+UART_HandleTypeDef* UART_PORTS[] = { &huart4, &huart5, &huart1, &huart2 };
+UART_HandleTypeDef* PARENT;
 DMA_HandleTypeDef hdma_uart4_rx;
 DMA_HandleTypeDef hdma_uart5_rx;
 DMA_HandleTypeDef hdma_usart1_rx;
@@ -70,13 +74,64 @@ int main(void)
 
   while (1)
   {
+    switch(CURRENT_MODE){
 
+      case MODE_INACTIVE:
+        uint8_t candidates_depth[] = {0xFF, 0xFF, 0xFF, 0xFF};
+
+        //Poll all UART Ports
+        for(uint8_t i = 0; i<4; i++){
+          uint8_t rxBuffer[4] = {0};
+          HAL_UART_Transmit(UART_PORTS[i], MODULE_HANDSHAKE_REQUEST, 4, HAL_MAX_DELAY);
+          if (HAL_UART_Receive(UART_PORTS[i], rxBuffer, 4, 500) == HAL_OK) {
+            //Is a type of confirmation message
+            if(rxBuffer[1] == 0xFF){
+              candidates_depth[i] = rxBuffer[0];
+            }else{
+              candidates_depth[i] = 0xFF;
+            }
+          } else {
+            // Timeout or error
+            candidates_depth[i] = 0xFF; 
+          } 
+        }
+
+        // Arbitration: 0xFF means invalid
+        uint8_t min = 0xFF;           // start with invalid value
+        uint8_t best_parent = 0xFF;   // invalid index by default
+
+        for(uint8_t i = 0; i < 4; i++){
+          if(candidates_depth[i] != 0xFF && candidates_depth[i] < min){
+            min = candidates_depth[i];
+            best_parent = i;
+          }
+        }
+        if(best_parent != 0xFF){      // found a valid parent
+          PARENT = UART_PORTS[best_parent];  // assign UART handle pointer
+          DMA_Queue_Init(&RxQueue);
+          CURRENT_MODE = MODE_MODULE;
+        }
+      break;
+
+      case MODE_MODULE:
+      break;
+      
+      case MODE_MASTER:
+        
+        
+
+      break;  
+    }
   }
 }
 
 void DMA_Queue_Init(DMA_QUEUE* q){
   q->head = 0;
   q->tail = 0;
+  //Activate DMA to all ports
+  for(uint8_t i = 0; i<4; i++){
+    HAL_UART_Receive_DMA(&UART_PORTS[i], RxQueue.buffer, 4);
+  }
 }
 
 bool DMA_Queue_IsFull(DMA_QUEUE* q){

firmware/core/build/Debug/.ninja_log

@@ -1,39 +1,37 @@
 # ninja log v5
-6	63	1756075614928355803	CMakeFiles/core.dir/startup_stm32f446xx.s.obj	382da930996a4cc2
+263	489	1756075615361261736	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_pwr_ex.c.obj	4642ce9ed3d82ec4
-5	103	1756075614975270658	CMakeFiles/core.dir/Core/Src/sysmem.c.obj	1bea4127f50c3fda
+295	718	1756075615590434033	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_i2c.c.obj	7e72a5f1282d8dd4
-6	149	1756075615021523857	CMakeFiles/core.dir/Core/Src/syscalls.c.obj	70d8fad01d4c7c7b
+10	454	1756075615323066353	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_ll_usb.c.obj	3f81ae684fc61263
+335	577	1756075615447703918	cmake/stm32cubemx/CMakeFiles/USB_Device_Library.dir/__/__/Middlewares/ST/STM32_USB_Device_Library/Core/Src/usbd_ctlreq.c.obj	a4cc0fdb515ad6bf
+103	390	1756075615258737287	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_dma_ex.c.obj	aaf2ae978201821f
+6	307	1756075615179331097	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Core/Src/system_stm32f4xx.c.obj	97644d51df3090f0
+258	481	1756075615352215461	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_pwr.c.obj	1a0236394c1509ff
+151	411	1756075615281786854	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_dma.c.obj	bdbd6598695546ae
+308	631	1756075615499971284	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_uart.c.obj	ced7e19aeb2f5cc9
+3	340	1756075615207475063	CMakeFiles/core.dir/Core/Src/stm32f4xx_it.c.obj	f9b423df71363d1c
+322	573	1756075615443683351	cmake/stm32cubemx/CMakeFiles/USB_Device_Library.dir/__/__/Middlewares/ST/STM32_USB_Device_Library/Core/Src/usbd_core.c.obj	4e1d9e35eaef39f8
+4	295	1756075615166973579	CMakeFiles/core.dir/Core/Src/stm32f4xx_hal_msp.c.obj	f6485b1ec03e1db9
+295	546	1756075615418554810	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_i2c_ex.c.obj	f93aa37ce29daf31
+267	519	1756075615389642237	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_cortex.c.obj	91f4151497ea87ee
 12	258	1756075615128068872	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_flash_ex.c.obj	9984760fba525afa
-3	262	1756075615134099722	CMakeFiles/core.dir/USB_DEVICE/App/usb_device.c.obj	c659c1fe9a79370
+272	540	1756075615412523960	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal.c.obj	eb24b13c626e9be1
-13	266	1756075615138120289	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_flash_ramfunc.c.obj	40ca293c34955b23
 11	272	1756075615142140856	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_rcc_ex.c.obj	81fe522a3d030d30
 7	285	1756075615156212839	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_pcd.c.obj	5c50b44e08689482
-3	293	1756075615164253972	CMakeFiles/core.dir/USB_DEVICE/App/usbd_desc.c.obj	c04d8582764f479d
+5	103	1756075614975270658	CMakeFiles/core.dir/Core/Src/sysmem.c.obj	1bea4127f50c3fda
-4	295	1756075615166973579	CMakeFiles/core.dir/Core/Src/stm32f4xx_hal_msp.c.obj	f6485b1ec03e1db9
-3	301	1756075615171289963	CMakeFiles/core.dir/Core/Src/main.c.obj	612a7a44e98bda92
-10	303	1756075615174305389	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_rcc.c.obj	c2600fd856ec13ab
-6	307	1756075615179331097	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Core/Src/system_stm32f4xx.c.obj	97644d51df3090f0
-2	321	1756075615190387655	CMakeFiles/core.dir/USB_DEVICE/Target/usbd_conf.c.obj	950d6fa9d73ae6e0
 8	334	1756075615200439071	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_pcd_ex.c.obj	b98f3f688125e870
-3	340	1756075615207475063	CMakeFiles/core.dir/Core/Src/stm32f4xx_it.c.obj	f9b423df71363d1c
+13	266	1756075615138120289	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_flash_ramfunc.c.obj	40ca293c34955b23
-11	362	1756075615230593321	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_flash.c.obj	a04d7f696e9c0d8c
+3	262	1756075615134099722	CMakeFiles/core.dir/USB_DEVICE/App/usb_device.c.obj	c659c1fe9a79370
 70	389	1756075615251701296	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_gpio.c.obj	581a4c3cc3fd4658
-103	390	1756075615258737287	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_dma_ex.c.obj	aaf2ae978201821f
+6	149	1756075615021523857	CMakeFiles/core.dir/Core/Src/syscalls.c.obj	70d8fad01d4c7c7b
-151	411	1756075615281786854	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_dma.c.obj	bdbd6598695546ae
-10	454	1756075615323066353	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_ll_usb.c.obj	3f81ae684fc61263
-258	481	1756075615352215461	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_pwr.c.obj	1a0236394c1509ff
-263	489	1756075615361261736	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_pwr_ex.c.obj	4642ce9ed3d82ec4
-267	519	1756075615389642237	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_cortex.c.obj	91f4151497ea87ee
-286	531	1756075615402472544	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_exti.c.obj	489e696b647ded46
-272	540	1756075615412523960	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal.c.obj	eb24b13c626e9be1
-295	546	1756075615418554810	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_i2c_ex.c.obj	f93aa37ce29daf31
-322	573	1756075615443683351	cmake/stm32cubemx/CMakeFiles/USB_Device_Library.dir/__/__/Middlewares/ST/STM32_USB_Device_Library/Core/Src/usbd_core.c.obj	4e1d9e35eaef39f8
-335	577	1756075615447703918	cmake/stm32cubemx/CMakeFiles/USB_Device_Library.dir/__/__/Middlewares/ST/STM32_USB_Device_Library/Core/Src/usbd_ctlreq.c.obj	a4cc0fdb515ad6bf
-362	579	1756075615450719343	cmake/stm32cubemx/CMakeFiles/USB_Device_Library.dir/__/__/Middlewares/ST/STM32_USB_Device_Library/Class/HID/Src/usbd_hid.c.obj	4c1ef8c3b45ecf3e
 303	583	1756075615453734768	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_tim_ex.c.obj	78a83f472cf48732
+3	293	1756075615164253972	CMakeFiles/core.dir/USB_DEVICE/App/usbd_desc.c.obj	c04d8582764f479d
+6	63	1756075614928355803	CMakeFiles/core.dir/startup_stm32f446xx.s.obj	382da930996a4cc2
+286	531	1756075615402472544	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_exti.c.obj	489e696b647ded46
 341	585	1756075615456750193	cmake/stm32cubemx/CMakeFiles/USB_Device_Library.dir/__/__/Middlewares/ST/STM32_USB_Device_Library/Core/Src/usbd_ioreq.c.obj	73e6de5304f3589
-308	631	1756075615499971284	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_uart.c.obj	ced7e19aeb2f5cc9
+11	362	1756075615230593321	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_flash.c.obj	a04d7f696e9c0d8c
-301	688	1756075615559274642	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_tim.c.obj	31a0df46be8b277d
+10	303	1756075615174305389	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_rcc.c.obj	c2600fd856ec13ab
-295	718	1756075615590434033	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_i2c.c.obj	7e72a5f1282d8dd4
-718	810	1756075615680017145	core.elf	65fc94ad55c43ddb
-2	203	1756076952561034859	CMakeFiles/core.dir/Core/Src/main.c.obj	612a7a44e98bda92
 203	305	1756076952660915938	core.elf	65fc94ad55c43ddb
+362	579	1756075615450719343	cmake/stm32cubemx/CMakeFiles/USB_Device_Library.dir/__/__/Middlewares/ST/STM32_USB_Device_Library/Class/HID/Src/usbd_hid.c.obj	4c1ef8c3b45ecf3e
+2	203	1756076952561034859	CMakeFiles/core.dir/Core/Src/main.c.obj	612a7a44e98bda92
+301	688	1756075615559274642	cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_tim.c.obj	31a0df46be8b277d
+2	321	1756075615190387655	CMakeFiles/core.dir/USB_DEVICE/Target/usbd_conf.c.obj	950d6fa9d73ae6e0