# agh-space-systems-rover/kalman-electronics-master-v3 architecture

> Architecture diagram of the GitHub repository agh-space-systems-rover/kalman-electronics-master-v3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agh-space-systems-rover/kalman-electronics-master-v3
- Repository: https://github.com/agh-space-systems-rover/kalman-electronics-master-v3

## Overview

Master-v3 is rover-control firmware: after STM32 peripheral setup, it initializes application logic and starts FreeRTOS tasks that process UART and CAN communications alongside GPIO-expander and status work. UART packets are parsed, queued, validated, then dispatched to command handlers; CAN has corresponding manager and handler tasks. The command families cover rover subsystems such as motors, the arm, science, drill, and power distribution. Source excerpts establish task creation and UART dispatch, but do not show most parser, CAN, or hardware command implementations, so those links are documented or left unverified.

Main entry points: [`master_lib/shared/tasks.c`](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/tasks.c) (Runtime tasks), [`master_lib/uart/handler/uart_parser.c`](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_parser.c) (UART parser), [`master_lib/uart/handler/uart_packet_handler.c`](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_packet_handler.c) (UART dispatch), [`master_lib/can/handler/can_manager.c`](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/handler/can_manager.c) (CAN manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Firmware startup"]
  node_entry["Boot and peripherals<br/>[main.c]"]
  node_appinit["Application init<br/>[Master_Main.c]"]
  node_config["Peripheral configuration<br/>[config.c]"]
  node_uartdrivers["UART peripherals<br/>[usart.c]"]
end

subgraph group_runtime["RTOS runtime"]
  node_tasksetup["Task creation<br/>[tasks.c]"]
  node_tasks["Runtime tasks<br/>[tasks.c]"]
  node_shared["Shared state and queues<br/>[common.h]"]
  node_timers["Traffic and timeout timers<br/>[timer.c]"]
  node_gpio["GPIO expander<br/>[gpio_expander.c]"]
  node_status["Status reporting<br/>[status_info.c]"]
end

subgraph group_serial["UART communications"]
  node_uartparse["UART parser<br/>[uart_parser.c]"]
  node_uartqueue["UART packet queue"]
  node_uarthandler["UART dispatch"]
  node_uartencode["UART encoder<br/>[uart_encoder.h]"]
end

subgraph group_can["CAN communications"]
  node_canmanager["CAN manager<br/>[can_manager.c]"]
  node_canqueue["CAN packet queue"]
  node_canhandler["CAN dispatch"]
  node_canpacket["CAN packet format<br/>[can_packet.h]"]
end

subgraph group_domain["Rover command domains"]
  node_uartcmd["UART command handlers<br/>[uart_cmd.c]"]
  node_uartdefs["UART command registry<br/>[uart_packet_defs.h]"]
  node_cancommands["CAN command handlers<br/>[can_cmd.c]"]
  node_hardware["Rover hardware actions<br/>[hw.c]"]
end

node_mcu(("Rover MCU"))
node_external(("Rover clients and modules"))
node_canbus(("CAN bus devices"))

node_mcu -->|"boots"| node_entry
node_entry -->|"initializes peripherals"| node_config
node_entry -->|"calls Init"| node_appinit
node_appinit -.->|"creates tasks"| node_tasksetup
node_tasksetup -->|"registers"| node_tasks
node_tasks -->|"starts parser"| node_uartparse
node_tasks -->|"starts handler"| node_uarthandler
node_tasks -->|"starts encoder"| node_uartencode
node_tasks -->|"starts manager"| node_canmanager
node_tasks -->|"starts handler"| node_canhandler
node_tasks -->|"starts task"| node_gpio
node_tasks -->|"starts task"| node_status
node_uartdrivers -.->|"provides input"| node_uartparse
node_uartparse -.->|"enqueues packets"| node_uartqueue
node_uartqueue -->|"dequeues packets"| node_uarthandler
node_uarthandler -->|"looks up command"| node_uartdefs
node_uarthandler -.->|"executes handler"| node_uartcmd
node_uartcmd -.->|"controls hardware"| node_hardware
node_uartencode -.->|"sends responses"| node_external
node_external -.->|"sends commands"| node_uartparse
node_canmanager -.->|"queues packets"| node_canqueue
node_canqueue -.->|"dispatches packets"| node_canhandler
node_canhandler -.->|"processes frames"| node_canpacket
node_canhandler -.->|"executes commands"| node_cancommands
node_cancommands -.->|"controls hardware"| node_hardware
node_canmanager -.->|"receives and sends"| node_canbus
node_timers -.->|"triggers actions"| node_uartcmd
node_timers -.->|"triggers actions"| node_cancommands
node_shared -.->|"shares runtime state"| node_uartparse
node_shared -.->|"shares runtime state"| node_canmanager

click node_entry "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/Core/Src/main.c"
click node_appinit "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/Src/Master_Main/Master_Main.c"
click node_tasksetup "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/tasks.c"
click node_tasks "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/tasks.c"
click node_shared "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/common.h"
click node_timers "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/timers/timer.c"
click node_config "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/Src/config.c"
click node_uartdrivers "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/Core/Src/usart.c"
click node_uartparse "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_parser.c"
click node_uartqueue "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_packet_handler.c"
click node_uarthandler "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_packet_handler.c"
click node_uartencode "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_encoder.h"
click node_uartcmd "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/commands/uart_cmd.c"
click node_uartdefs "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/uart_packet_defs.h"
click node_canmanager "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/handler/can_manager.c"
click node_canqueue "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/handler/can_packet_handler.c"
click node_canhandler "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/handler/can_packet_handler.c"
click node_cancommands "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/commands/can_cmd.c"
click node_canpacket "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/can_packet.h"
click node_hardware "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/hw/hw.c"
click node_gpio "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/gpio_expander.c"
click node_status "https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/status_info.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_appinit,node_config,node_uartdrivers,node_external toneBlue
class node_tasksetup,node_tasks,node_shared,node_timers,node_gpio,node_status toneAmber
class node_uartparse,node_uartqueue,node_uarthandler,node_uartencode toneMint
class node_canmanager,node_canqueue,node_canhandler,node_canpacket toneRose
class node_uartcmd,node_uartdefs,node_cancommands,node_hardware,node_mcu,node_canbus toneIndigo
```

## Components

### Firmware startup

- [Boot and peripherals](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/Core/Src/main.c): `Core/Src/main.c`
- [Application init](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/Src/Master_Main/Master_Main.c): `Src/Master_Main/Master_Main.c`
- [Peripheral configuration](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/Src/config.c): `Src/config.c`
- [UART peripherals](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/Core/Src/usart.c): `Core/Src/usart.c`

### RTOS runtime

- [Task creation](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/tasks.c): `master_lib/shared/tasks.c`
- [Runtime tasks](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/tasks.c): `master_lib/shared/tasks.c`
- [Shared state and queues](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/common.h): `master_lib/shared/common.h`
- [Traffic and timeout timers](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/timers/timer.c): `master_lib/timers/timer.c`
- [GPIO expander](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/gpio_expander.c): `master_lib/shared/gpio_expander.c`
- [Status reporting](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/shared/status_info.c): `master_lib/shared/status_info.c`

### UART communications

- [UART parser](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_parser.c): `master_lib/uart/handler/uart_parser.c`
- [UART packet queue](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_packet_handler.c): `master_lib/uart/handler/uart_packet_handler.c`
- [UART dispatch](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_packet_handler.c): `master_lib/uart/handler/uart_packet_handler.c`
- [UART encoder](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/handler/uart_encoder.h): `master_lib/uart/handler/uart_encoder.h`

### CAN communications

- [CAN manager](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/handler/can_manager.c): `master_lib/can/handler/can_manager.c`
- [CAN packet queue](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/handler/can_packet_handler.c): `master_lib/can/handler/can_packet_handler.c`
- [CAN dispatch](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/handler/can_packet_handler.c): `master_lib/can/handler/can_packet_handler.c`
- [CAN packet format](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/can_packet.h): `master_lib/can/can_packet.h`

### Rover command domains

- [UART command handlers](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/commands/uart_cmd.c): `master_lib/uart/commands/uart_cmd.c`
- [UART command registry](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/uart/uart_packet_defs.h): `master_lib/uart/uart_packet_defs.h`
- [CAN command handlers](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/can/commands/can_cmd.c): `master_lib/can/commands/can_cmd.c`
- [Rover hardware actions](https://github.com/agh-space-systems-rover/kalman-electronics-master-v3/blob/master/master_lib/hw/hw.c): `master_lib/hw/hw.c`

### Other components

- **Rover MCU**
- **Rover clients and modules**
- **CAN bus devices**

## Connections

- Rover MCU → Boot and peripherals: boots (evidence: `Core/Src/main.c`)
- Boot and peripherals → Peripheral configuration: initializes peripherals (evidence: `Core/Src/main.c`)
- Boot and peripherals → Application init: calls Init (evidence: `Core/Src/main.c`)
- Application init → Task creation: creates tasks
- Task creation → Runtime tasks: registers (evidence: `master_lib/shared/tasks.c`)
- Runtime tasks → UART parser: starts parser (evidence: `master_lib/shared/tasks.c`)
- Runtime tasks → UART dispatch: starts handler (evidence: `master_lib/shared/tasks.c`)
- Runtime tasks → UART encoder: starts encoder (evidence: `master_lib/shared/tasks.c`)
- Runtime tasks → CAN manager: starts manager (evidence: `master_lib/shared/tasks.c`)
- Runtime tasks → CAN dispatch: starts handler (evidence: `master_lib/shared/tasks.c`)
- Runtime tasks → GPIO expander: starts task (evidence: `master_lib/shared/tasks.c`)
- Runtime tasks → Status reporting: starts task (evidence: `master_lib/shared/tasks.c`)
- UART peripherals → UART parser: provides input
- UART parser → UART packet queue: enqueues packets
- UART packet queue → UART dispatch: dequeues packets (evidence: `master_lib/uart/handler/uart_packet_handler.c`)
- UART dispatch → UART command registry: looks up command (evidence: `master_lib/uart/handler/uart_packet_handler.c`)
- UART dispatch → UART command handlers: executes handler
- UART command handlers → Rover hardware actions: controls hardware
- UART encoder → Rover clients and modules: sends responses
- Rover clients and modules → UART parser: sends commands
- CAN manager → CAN packet queue: queues packets
- CAN packet queue → CAN dispatch: dispatches packets (evidence: `master_lib/can/handler/can_packet_handler.c`)
- CAN dispatch → CAN packet format: processes frames (evidence: `master_lib/can/handler/can_packet_handler.c`)
- CAN dispatch → CAN command handlers: executes commands
- CAN command handlers → Rover hardware actions: controls hardware
- CAN manager → CAN bus devices: receives and sends
- Traffic and timeout timers → UART command handlers: triggers actions
- Traffic and timeout timers → CAN command handlers: triggers actions
- Shared state and queues → UART parser: shares runtime state
- Shared state and queues → CAN manager: shares runtime state
