diff --git a/docs/firmware/firmware-architecture.md b/docs/firmware/firmware-architecture.md new file mode 100644 index 00000000..7396ae74 --- /dev/null +++ b/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. + diff --git a/firmware/core/Core/Src/main.c b/firmware/core/Core/Src/main.c index efbf3b27..a4810228 100644 --- a/firmware/core/Core/Src/main.c +++ b/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){ diff --git a/firmware/core/build/Debug/.cmake/api/v1/reply/index-2025-08-24T22-46-03-0622.json b/firmware/core/build/Debug/.cmake/api/v1/reply/index-2025-08-25T00-55-58-0523.json similarity index 100% rename from firmware/core/build/Debug/.cmake/api/v1/reply/index-2025-08-24T22-46-03-0622.json rename to firmware/core/build/Debug/.cmake/api/v1/reply/index-2025-08-25T00-55-58-0523.json diff --git a/firmware/core/build/Debug/.ninja_deps b/firmware/core/build/Debug/.ninja_deps index 2649110a..2b6ea040 100644 Binary files a/firmware/core/build/Debug/.ninja_deps and b/firmware/core/build/Debug/.ninja_deps differ diff --git a/firmware/core/build/Debug/.ninja_log b/firmware/core/build/Debug/.ninja_log index 34261335..5b3cf47b 100644 --- a/firmware/core/build/Debug/.ninja_log +++ b/firmware/core/build/Debug/.ninja_log @@ -1,39 +1,37 @@ # ninja log v5 -6 63 1756075614928355803 CMakeFiles/core.dir/startup_stm32f446xx.s.obj 382da930996a4cc2 -5 103 1756075614975270658 CMakeFiles/core.dir/Core/Src/sysmem.c.obj 1bea4127f50c3fda -6 149 1756075615021523857 CMakeFiles/core.dir/Core/Src/syscalls.c.obj 70d8fad01d4c7c7b +263 489 1756075615361261736 cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_pwr_ex.c.obj 4642ce9ed3d82ec4 +295 718 1756075615590434033 cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_i2c.c.obj 7e72a5f1282d8dd4 +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 -13 266 1756075615138120289 cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_flash_ramfunc.c.obj 40ca293c34955b23 +272 540 1756075615412523960 cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal.c.obj eb24b13c626e9be1 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 -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 +5 103 1756075614975270658 CMakeFiles/core.dir/Core/Src/sysmem.c.obj 1bea4127f50c3fda 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 -11 362 1756075615230593321 cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_flash.c.obj a04d7f696e9c0d8c +13 266 1756075615138120289 cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_flash_ramfunc.c.obj 40ca293c34955b23 +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 -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 +6 149 1756075615021523857 CMakeFiles/core.dir/Core/Src/syscalls.c.obj 70d8fad01d4c7c7b 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 -301 688 1756075615559274642 cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_tim.c.obj 31a0df46be8b277d -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 +11 362 1756075615230593321 cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_flash.c.obj a04d7f696e9c0d8c +10 303 1756075615174305389 cmake/stm32cubemx/CMakeFiles/STM32_Drivers.dir/__/__/Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_rcc.c.obj c2600fd856ec13ab 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