# Platform Overview

**What you’ll do**
- 플랫폼 하드웨어 구성과 역할을 파악합니다.
- 주행 제어의 핵심 변수인 목표 속도 $v$와 목표 각속도 $\omega$ 관계를 이해합니다.


**Prerequisites**
- [Simulator](https://github.com/cislab-kaist/Mobility_Challenge_Simulator)
- [SDK](https://github.com/Seo12044/KAIST_Mobility_Challenge_SDK.git)
- [Ros2 foxy install](https://docs.ros.org/en/foxy/Installation.html)

**Next**
- {doc}`Vehicle Control Model </page/Introduction/control_model>`
- {doc}`Linux Port Setup </page/Setup_Test/linux_port_setup>`
- {doc}`Dashboard Test </page/Setup_Test/dashboard_test>`
- {doc}`UART Protocol Reference </page/Protocol/uart_protocol>`

이 문서는 자율주행 플랫폼의 하드웨어 구성과 제어 인터페이스의 개요를 다룹니다.

사용자의 알고리즘(인지/판단/제어)은 NVIDIA Jetson Orin NX에서 실행되며, 차량 구동계(모터/서보)를 담당하는 전용 제어 보드와 **USB Serial(UART)** 로 통신합니다.

호스트(Jetson)는 목표 속도 $v$와 목표 각속도 $\omega$를 연산하여 전송하고, 제어 보드는 이를 실제 구동 신호(PWM)로 변환합니다.

상세한 통신 패킷 구조는 {doc}`UART Protocol Reference </page/Protocol/uart_protocol>`를 참고하십시오.

---

## 주요 구성품
플랫폼은 크게 상위 컴퓨팅 유닛과 하부 제어 구동계로 나뉩니다.

- 메인 컴퓨터 (Host): NVIDIA Jetson Orin NX 16GB Module

  - 고성능 AI 연산 및 자율주행 알고리즘 실행

- 제어 회로 : 플랫폼 전용 Low-Level 제어 보드

  - 센서 데이터 처리 및 액추에이터 PID 제어

- 조향 액추에이터: HS-5055MG (디지털 서보모터)

  - Ackermann 조향 구조 제어

- 구동 액추에이터: GM3506 BLDC 모터 (2개)

  - 후륜 구동(RWD), 정밀 속도 제어

---

## 차량 구조 및 특징

![차량소개](/_static/img/introduction/car_housing.png)
<!-- <div class="img-text">
  <img src="/_static/img/introduction/car_housing.png" alt="차량 커버">
  <div>
    <p><b>차량소개</b></p>
    <ul>
      <li>Jetson Orin NX 기반 컴퓨팅</li>
      <li>Ackermann 조향 + 후륜구동 구조</li>
    </ul>
  </div>
   -->
| 항목 | 세부 사양 | 비고 |
| --- | --- | --- |
| **메인 컴퓨터** | NVIDIA Jetson Orin NX (16GB) | Team Code 실행 (인지/계획/제어) |
| **구동 방식** | 후륜 구동 | 짐벌 모터 2개 기반 구동 |
| **조향 방식** | Ackermann Steering |  |
| **조향 서보** | HS-5055MG | 기구적 조향각: $\pm 45^\circ$ ($\approx 0.785\,\mathrm{rad}$), 펌웨어 제한 없음 |
| **구동 모터** | GM3506 BLDC (2개) | $12\,\mathrm{V}$, Load torque: $600\sim1000\,\mathrm{g\cdot cm}$ |
| **전원 시스템** | 4S Li-ion, $4{,}900\,\mathrm{mAh}$ | Jetson 및 제어 보드 통합 전원 |
| **차량 무게**| 약 $2400\,\mathrm{g}$| 배터리 포함 무게 |
| **차량 최대 속도** | $5\,\mathrm{m/s}$ | 펌웨어 제한: $2\,\mathrm{m/s}$ (안전 고려) |
| **조향 제어주기** | $1000\,\mathrm{Hz}$ | 차량 내부 제어 주기 |
---

## UART 연결 및 권장 설정

Jetson과 제어보드는 USB 케이블로 연결되며, 운영체제에서는 시리얼 포트(USB Serial)로 인식됩니다.

| 항목 | 값 | 비고 |
| --- | --- | --- |
| **포트(권장)** | `/dev/ttyKMC` | Ubuntu에서 udev symlink 고정 권장 |
| **USB-UART 브리지(예시)** | FTDI FT232H (VID:PID `0403:6014`) | |
| **플로우컨트롤** | RTS/CTS | 필수 사용 |
| **baud rate** | $9{,}600\, - 2{,}250{,}500\mathrm{bps}$ | 권장 : $921{,}600\mathrm{bps}$ |
- 포트 고정/권한 설정: {doc}`Linux Port Setup </page/Setup_Test/linux_port_setup>`
- GUI로 연결/송수신 확인: {doc}`Dashboard Test </page/Setup_Test/dashboard_test>`
- 바이트 레벨 규격: {doc}`UART Protocol Reference </page/Protocol/uart_protocol>`
- 문제 해결: {doc}`UART Troubleshooting </page/Troubleshooting/uart_troubleshooting>`

---


## 차량 제어 메커니즘 (Vehicle Control)

### 조향 및 구동 원리

**Ackermann Steering**은 저속 선회에서 불필요한 미끄럼을 줄이기 위해, 안쪽/바깥쪽 바퀴의 조향각이 달라지도록 설계된 구조입니다.

### 제어 변수 및 물리 관계식

![차량제어](../../_static/img/introduction/car_control.png)

차량의 움직임은 선속도($v$)와 각속도($\omega$)의 관계를 통해 정의됩니다.


#### 제어 변수 정의
* $v$ (Linear Velocity): 차량 중심의 전진 속도 [$\mathrm{m/s}$]
* $\omega$ (Yaw Rate): 차량의 회전 각속도 [$\mathrm{rad/s}$]
* $\kappa$ (Curvature): 회전 반경의 역수, 주행 경로의 굽은 정도 [$\mathrm{m}^{-1}$]
* $r$ (Radius): 회전 반경 [$\mathrm{m}$]

#### 선속도, 각속도 관계
$$
\omega = v\kappa
$$
UART 통신 레벨에서는 효율성을 위해 **곡률($\kappa$)** 을 사용합니다.

여기서 차량의 곡률($\kappa$)은 다음과 같이 정의됩니다.

#### 곡률 및 회전반경
$$
\kappa = \frac{1}{r}
$$

- UART에서는 곡률 $\kappa$를 사용하므로 직진은 $\kappa=0$으로 표현됩니다.

```{admonition} 방향
:class: tip

* **속도 ($v$):** $v > 0$ (전진), $v < 0$ (후진)
* **각속도 ($\omega$):** $\omega > 0$ (CCW, 좌회전), $\omega < 0$ (CW, 우회전)
* **곡률 ($\kappa$):** 전진($v>0$) 기준, $\kappa > 0$ (좌회전), $\kappa < 0$ (우회전)
```



---

## 제어 인터페이스

### Low-Level Control Interface

주행 알고리즘은 Jetson Orin NX에서 실행합니다. 모터/서보의 저수준 제어(PWM, 엔코더 등)는 전용 제어보드가 담당합니다.

* **통신 방식**: Jetson - 제어 보드 간 USB Serial (UART 프로토콜)
* **API 입력 :** 
1.  **목표 속도 ($v$):** 차량의 이동 속도
2.  **목표 각속도 ($\omega$):** 차량의 회전 속도 설정

* **UART 통신 입력 :** 
1.  **목표 속도 ($v$):** 차량의 이동 속도
2.  **목표 곡률 ($\kappa$):** 차량의 회전 곡률 설정

* Timeout (Deadman Switch): 차량은 마지막 명령을 반복합니다. 호스트 프로그램 종료 시 명시적으로 정지 명령 $(0, 0)$ 을 보내는 것을 권장합니다.

```{admonition} Limits & Safety
:class: warning
안전한 주행과 하드웨어 보호를 위해 다음 제한 사항을 준수하십시오.

1.  **속도 제한:**
    * 차량의 물리적 최대 속도는 $5\,\mathrm{m/s}$이나, **펌웨어 레벨에서 $|v| \le 2.0\,\mathrm{m/s}$로 제한** 됩니다.
    * 제한 속도 초과 명령 시, 펌웨어에서 $2.0\,\mathrm{m/s}$로 클램핑됩니다.

2.  **조향(곡률) 제한:**
    * 하드웨어 보호를 위해 **곡률 $|\kappa| \le 3.0\,\mathrm{m}^{-1}$** 이내 사용을 권장합니다.
    * 물리적 조향각 한계는 $\delta_{\max} \approx 45^\circ (0.785\,\mathrm{rad})$이며, 서보 PWM 신호는 $900 \sim 2100\,\mu\mathrm{s}$ 범위로 제한됩니다.
    * 각속도 명령으로 환산 시: $|\omega| \le |v| \cdot \kappa_{\max}$ 조건을 만족해야 합니다.
```