# pcb-yun/logcar architecture

> Architecture diagram of the GitHub repository pcb-yun/logcar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pcb-yun/logcar
- Repository: https://github.com/pcb-yun/logcar

## Overview

This is a RoboCup logistics robot project with STM32/FreeRTOS control firmware and a Raspberry Pi vision program. The main operational workflow sequences pickup, navigation, sorting or transfer, and return-home actions; navigation turns targets into chassis motion, while sensor and actuator drivers interface with the hardware. Separate branches provide vision-based recognition, OLED/media display, and a serial command shell with games. Relationships reflect the README and shown source references/calls; unsampled implementations are represented only where documented.

Main entry points: [`Applications/LogCar_mission/mission.c`](https://github.com/pcb-yun/logcar/blob/main/Applications/LogCar_mission/mission.c) (Mission scheduler), [`Applications/nav/nav_core.c`](https://github.com/pcb-yun/logcar/blob/main/Applications/nav/nav_core.c) (Navigation core), [`Applications/turntable/turntable_port.c`](https://github.com/pcb-yun/logcar/blob/main/Applications/turntable/turntable_port.c) (Turntable control), [`vision/main.py`](https://github.com/pcb-yun/logcar/blob/main/vision/main.py) (Vision dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mission["Mission orchestration"]
  node_mcu["STM32 firmware<br/>[main.c]"]
  node_mission_task["Mission scheduler<br/>[mission.c]"]
  node_events["RTOS events<br/>[Events.h]"]
end

subgraph group_navigation["Navigation and motion"]
  node_nav_core["Navigation core<br/>[nav_core.c]"]
  node_nav_map["Map and targets<br/>[nav_map.c]"]
  node_nav_local["Localization<br/>[nav_local.c]"]
  node_nav_track["Path tracking<br/>[nav_track.c]"]
  node_chassis["Chassis control<br/>[chassis.c]"]
  node_motion["Motion control<br/>[motion_control.c]"]
  node_kinematics["Wheel kinematics<br/>[kinematics.c]"]
end

subgraph group_handling["Handling and hardware"]
  node_mission_arm["Arm actions<br/>[arm_action.c]"]
  node_turntable["Turntable control<br/>[turntable_port.c]"]
  node_turntable_ctrl["Turntable mechanism<br/>[turntable_ctrl.c]"]
  node_sensors["Sensor drivers<br/>[sensor.c]"]
  node_rpi_link["Vision serial link<br/>[rpi_sensor_port.c]"]
  node_step_driver["Stepper driver<br/>[step_port_dlc.c]"]
  node_servo_driver["Servo driver<br/>[servo_driver.c]"]
end

subgraph group_vision["Vision system"]
  node_vision_main["Vision dispatcher<br/>[main.py]"]
  node_color_detect["Color detection<br/>[yanse.py]"]
  node_ring_detect["Ring detection<br/>[yuanhuan.py]"]
end

subgraph group_interfaces["Operator interfaces"]
  node_shell["Serial shell<br/>[shell.c]"]
  node_shell_port["Shell port<br/>[shell_port.c]"]
  node_display["OLED display<br/>[dsp_tool.c]"]
  node_media["Display media<br/>[show_media.c]"]
end

node_operator(("Operator"))
node_pi_camera(("CSI camera"))

node_mission_task -->|"navigates"| node_nav_core
node_mission_task -->|"reads targets"| node_nav_map
node_mission_task -->|"starts tracking"| node_nav_track
node_mission_task -->|"commands motion"| node_chassis
node_mission_task -->|"runs actions"| node_mission_arm
node_mission_task -->|"sorts materials"| node_turntable
node_mission_task -->|"reads sensors"| node_sensors
node_mission_task -->|"requests recognition"| node_rpi_link
node_nav_core -->|"looks up targets"| node_nav_map
node_nav_core -->|"uses localization"| node_nav_local
node_nav_core -->|"sets velocity"| node_motion
node_chassis -->|"delegates motion"| node_motion
node_motion -->|"solves wheel speeds"| node_kinematics
node_motion -->|"sends motor commands"| node_step_driver
node_turntable -->|"controls mechanism"| node_turntable_ctrl
node_turntable -->|"detects color"| node_sensors
node_turntable -->|"requests color"| node_rpi_link
node_turntable_ctrl -->|"drives servos"| node_servo_driver
node_pi_camera -->|"provides frames"| node_vision_main
node_vision_main -->|"dispatches color"| node_color_detect
node_vision_main -->|"dispatches ring"| node_ring_detect
node_vision_main -->|"sends results"| node_rpi_link
node_operator -->|"enters commands"| node_shell
node_shell -.->|"uses serial port"| node_shell_port
node_operator -->|"views status"| node_display
node_display -->|"renders media"| node_media
node_mission_task -->|"waits on flags"| node_events
node_mcu -.->|"runs mission task"| node_mission_task

click node_mcu "https://github.com/pcb-yun/logcar/blob/main/Core/Src/main.c"
click node_mission_task "https://github.com/pcb-yun/logcar/blob/main/Applications/LogCar_mission/mission.c"
click node_nav_core "https://github.com/pcb-yun/logcar/blob/main/Applications/nav/nav_core.c"
click node_nav_map "https://github.com/pcb-yun/logcar/blob/main/Applications/nav/nav_map.c"
click node_nav_local "https://github.com/pcb-yun/logcar/blob/main/Applications/nav/localization/nav_local.c"
click node_nav_track "https://github.com/pcb-yun/logcar/blob/main/Applications/nav/nav_track.c"
click node_chassis "https://github.com/pcb-yun/logcar/blob/main/Applications/chassis/chassis.c"
click node_motion "https://github.com/pcb-yun/logcar/blob/main/Applications/chassis/motion/motion_control.c"
click node_kinematics "https://github.com/pcb-yun/logcar/blob/main/Applications/chassis/kinematics/kinematics.c"
click node_mission_arm "https://github.com/pcb-yun/logcar/blob/main/Applications/arm/arm_action.c"
click node_turntable "https://github.com/pcb-yun/logcar/blob/main/Applications/turntable/turntable_port.c"
click node_turntable_ctrl "https://github.com/pcb-yun/logcar/blob/main/Applications/turntable/turntable_ctrl.c"
click node_sensors "https://github.com/pcb-yun/logcar/blob/main/Drivers/User/SENSOR/sensor.c"
click node_rpi_link "https://github.com/pcb-yun/logcar/blob/main/Drivers/User/SENSOR/rpi_sensor_port.c"
click node_step_driver "https://github.com/pcb-yun/logcar/blob/main/Drivers/User/STEP/step_port_dlc.c"
click node_servo_driver "https://github.com/pcb-yun/logcar/blob/main/Drivers/User/SERVO/servo_driver.c"
click node_vision_main "https://github.com/pcb-yun/logcar/blob/main/vision/main.py"
click node_color_detect "https://github.com/pcb-yun/logcar/blob/main/vision/yanse.py"
click node_ring_detect "https://github.com/pcb-yun/logcar/blob/main/vision/yuanhuan.py"
click node_shell "https://github.com/pcb-yun/logcar/blob/main/Applications/letter_shell/src/shell.c"
click node_shell_port "https://github.com/pcb-yun/logcar/blob/main/Applications/letter_shell/shell_port.c"
click node_display "https://github.com/pcb-yun/logcar/blob/main/Applications/Display/dsp_tool.c"
click node_media "https://github.com/pcb-yun/logcar/blob/main/Applications/Display/show_media.c"
click node_events "https://github.com/pcb-yun/logcar/blob/main/Drivers/User/RTOS/Events.h"

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_mcu,node_mission_task,node_events toneBlue
class node_nav_core,node_nav_map,node_nav_local,node_nav_track,node_chassis,node_motion,node_kinematics toneAmber
class node_mission_arm,node_turntable,node_turntable_ctrl,node_sensors,node_rpi_link,node_step_driver,node_servo_driver toneMint
class node_vision_main,node_color_detect,node_ring_detect toneRose
class node_shell,node_shell_port,node_display,node_media,node_operator,node_pi_camera toneIndigo
```

## Components

### Mission orchestration

- [STM32 firmware](https://github.com/pcb-yun/logcar/blob/main/Core/Src/main.c): `Core/Src/main.c`
- [Mission scheduler](https://github.com/pcb-yun/logcar/blob/main/Applications/LogCar_mission/mission.c): `Applications/LogCar_mission/mission.c`
- [RTOS events](https://github.com/pcb-yun/logcar/blob/main/Drivers/User/RTOS/Events.h): `Drivers/User/RTOS/Events.h`

### Navigation and motion

- [Navigation core](https://github.com/pcb-yun/logcar/blob/main/Applications/nav/nav_core.c): `Applications/nav/nav_core.c`
- [Map and targets](https://github.com/pcb-yun/logcar/blob/main/Applications/nav/nav_map.c): `Applications/nav/nav_map.c`
- [Localization](https://github.com/pcb-yun/logcar/blob/main/Applications/nav/localization/nav_local.c): `Applications/nav/localization/nav_local.c`
- [Path tracking](https://github.com/pcb-yun/logcar/blob/main/Applications/nav/nav_track.c): `Applications/nav/nav_track.c`
- [Chassis control](https://github.com/pcb-yun/logcar/blob/main/Applications/chassis/chassis.c): `Applications/chassis/chassis.c`
- [Motion control](https://github.com/pcb-yun/logcar/blob/main/Applications/chassis/motion/motion_control.c): `Applications/chassis/motion/motion_control.c`
- [Wheel kinematics](https://github.com/pcb-yun/logcar/blob/main/Applications/chassis/kinematics/kinematics.c): `Applications/chassis/kinematics/kinematics.c`

### Handling and hardware

- [Arm actions](https://github.com/pcb-yun/logcar/blob/main/Applications/arm/arm_action.c): `Applications/arm/arm_action.c`
- [Turntable control](https://github.com/pcb-yun/logcar/blob/main/Applications/turntable/turntable_port.c): `Applications/turntable/turntable_port.c`
- [Turntable mechanism](https://github.com/pcb-yun/logcar/blob/main/Applications/turntable/turntable_ctrl.c): `Applications/turntable/turntable_ctrl.c`
- [Sensor drivers](https://github.com/pcb-yun/logcar/blob/main/Drivers/User/SENSOR/sensor.c): `Drivers/User/SENSOR/sensor.c`
- [Vision serial link](https://github.com/pcb-yun/logcar/blob/main/Drivers/User/SENSOR/rpi_sensor_port.c): `Drivers/User/SENSOR/rpi_sensor_port.c`
- [Stepper driver](https://github.com/pcb-yun/logcar/blob/main/Drivers/User/STEP/step_port_dlc.c): `Drivers/User/STEP/step_port_dlc.c`
- [Servo driver](https://github.com/pcb-yun/logcar/blob/main/Drivers/User/SERVO/servo_driver.c): `Drivers/User/SERVO/servo_driver.c`

### Vision system

- [Vision dispatcher](https://github.com/pcb-yun/logcar/blob/main/vision/main.py): `vision/main.py`
- [Color detection](https://github.com/pcb-yun/logcar/blob/main/vision/yanse.py): `vision/yanse.py`
- [Ring detection](https://github.com/pcb-yun/logcar/blob/main/vision/yuanhuan.py): `vision/yuanhuan.py`

### Operator interfaces

- [Serial shell](https://github.com/pcb-yun/logcar/blob/main/Applications/letter_shell/src/shell.c): `Applications/letter_shell/src/shell.c`
- [Shell port](https://github.com/pcb-yun/logcar/blob/main/Applications/letter_shell/shell_port.c): `Applications/letter_shell/shell_port.c`
- [OLED display](https://github.com/pcb-yun/logcar/blob/main/Applications/Display/dsp_tool.c): `Applications/Display/dsp_tool.c`
- [Display media](https://github.com/pcb-yun/logcar/blob/main/Applications/Display/show_media.c): `Applications/Display/show_media.c`

### Other components

- **Operator**
- **CSI camera**

## Connections

- Mission scheduler → Navigation core: navigates (evidence: `Applications/LogCar_mission/mission.c`)
- Mission scheduler → Map and targets: reads targets (evidence: `Applications/LogCar_mission/mission.c`)
- Mission scheduler → Path tracking: starts tracking (evidence: `Applications/LogCar_mission/mission.c`)
- Mission scheduler → Chassis control: commands motion (evidence: `Applications/LogCar_mission/mission.c`)
- Mission scheduler → Arm actions: runs actions (evidence: `Applications/LogCar_mission/mission.c`)
- Mission scheduler → Turntable control: sorts materials (evidence: `Applications/LogCar_mission/mission.c`)
- Mission scheduler → Sensor drivers: reads sensors (evidence: `Applications/LogCar_mission/mission.c`)
- Mission scheduler → Vision serial link: requests recognition (evidence: `Applications/LogCar_mission/mission.c`)
- Navigation core → Map and targets: looks up targets (evidence: `Applications/nav/nav_core.c`)
- Navigation core → Localization: uses localization (evidence: `Applications/nav/nav_core.c`)
- Navigation core → Motion control: sets velocity (evidence: `Applications/nav/nav_core.c`)
- Chassis control → Motion control: delegates motion (evidence: `Applications/chassis/chassis.c`)
- Motion control → Wheel kinematics: solves wheel speeds (evidence: `Applications/chassis/motion/motion_control.c`)
- Motion control → Stepper driver: sends motor commands (evidence: `Applications/chassis/motion/motion_control.c`)
- Turntable control → Turntable mechanism: controls mechanism (evidence: `Applications/turntable/turntable_port.c`)
- Turntable control → Sensor drivers: detects color (evidence: `Applications/turntable/turntable_port.c`)
- Turntable control → Vision serial link: requests color (evidence: `Applications/turntable/turntable_port.c`)
- Turntable mechanism → Servo driver: drives servos
- CSI camera → Vision dispatcher: provides frames (evidence: `README.md`)
- Vision dispatcher → Color detection: dispatches color (evidence: `vision/main.py`)
- Vision dispatcher → Ring detection: dispatches ring (evidence: `vision/main.py`)
- Vision dispatcher → Vision serial link: sends results (evidence: `README.md`)
- Operator → Serial shell: enters commands (evidence: `README.md`)
- Serial shell → Shell port: uses serial port
- Operator → OLED display: views status (evidence: `README.md`)
- OLED display → Display media: renders media (evidence: `Applications/Display/dsp_tool.c`)
- Mission scheduler → RTOS events: waits on flags (evidence: `Applications/LogCar_mission/mission.c`)
- STM32 firmware → Mission scheduler: runs mission task
