Arduino 37종 센서 키트 기반 ROS 2 Sensor Bridge 팀 프로젝트

1. 실습 개요

이번 실습은 아두이노 37종 센서 모듈 키트를 활용하여, 각 팀이 센서 또는 출력 모듈 3개를 선택하고 이를 Arduino와 ROS 2 Humble 환경에 연결하는 센서 브릿지 시스템을 구현하는 간략 팀 프로젝트입니다.

발표는 진행하지 않습니다.
필요하면 PPT를 보조 자료로 사용할 수 있지만, 최종 정리는 README.md 중심으로 제출합니다.

구현 구조는 다음과 같습니다.

이번 실습의 핵심은 센서값을 단순히 읽는 것이 아닙니다.

센서 하드웨어 연결, 통신 프로토콜, Arduino 펌웨어, ROS 2 토픽 구조를 하나의 작은 로봇 시스템처럼 설계하고 README로 문서화하는 것입니다.

2. 팀 구성

각 팀은 2명으로 구성합니다.

역할	주요 담당
팀원 A	Arduino firmware, 센서 배선, 센서 단독 테스트, 패킷 송수신 구현
팀원 B	ROS 2 패키지, 토픽 publish/subscribe, README 정리, 테스트 결과 정리

역할은 나눠도 되지만, 최종적으로 두 팀원 모두 전체 구조를 잘 이해하는 것을 권장합니다.

3. 센서 선택 기준

각 팀은 37종 센서 키트에서 3개 모듈을 선택합니다.

권장 조합은 다음과 같습니다.

입력 센서 2개 + 출력 모듈 1개

이 구성이 좋은 이유는 ROS 2의 양방향 통신을 모두 실습할 수 있기 때문입니다.

예시 조합	구성	실습 방향
조합 1	CDS 광센서 + 버튼 + 부저	조도/버튼 publish, 부저 subscribe 제어
조합 2	온습도 센서 + 리드 스위치 + 릴레이	온습도/스위치 publish, 릴레이 제어
조합 3	장애물 감지 센서 + 충격 센서 + 2색 LED	감지값 publish, LED 제어
조합 4	조이스틱 + 로터리 엔코더 + 부저	조작값 publish, 부저 제어

입력 센서 3개만 선택해도 되지만, 그 경우 ROS 2에서 Arduino로 명령을 보내는 subscribe 실습이 약해집니다.
따라서 가능하면 LED, 부저, 릴레이 같은 출력 모듈을 최소 1개를 포함할 것을 추천합니다. 그러나 모듈이 부족할 경우에는 탄력적으로 선택하시기 바랍니다.

4. 구현해야 할 방향

각 팀은 아래 두 방향을 모두 구현하는 것을 목표로 합니다.

1) Arduino → ROS 2

센서값 읽기
→ 바이너리 패킷 생성
→ Serial.write()로 송신
→ ROS 2 브릿지 노드에서 수신
→ ROS 2 토픽 publish

예시:

CDS 광센서 값 → /sensor/light
버튼 상태 → /sensor/button

2) ROS 2 → Arduino

ROS 2 토픽 publish
→ ROS 2 브릿지 노드가 subscribe
→ 명령 패킷 생성
→ Arduino로 송신
→ 출력 모듈 제어

예시:

/cmd/buzzer → Arduino 부저 ON/OFF
/cmd/led → Arduino LED ON/OFF
/cmd/relay → Arduino 릴레이 제어

5. README.md 작성 요구사항

README는 최종 제출물의 중심입니다.
발표가 없기 때문에 README를 보면 실습 내용을 바로 이해하고 재현할 수 있어야 합니다.

[ README 기본 구조 ]

# TeamXX Sensor Bridge Project

## 1. 프로젝트 개요
## 2. 팀원
## 3. 선택한 센서 및 출력 모듈
## 4. 전체 시스템 구조
## 5. 센서 모듈 조사 내용
## 6. 하드웨어 구조 및 회로 연결
## 7. 배선 연결표
## 8. 통신 프로토콜 설계
## 9. Packet ID 정의
## 10. ROS 2 토픽 설계
## 11. Arduino Firmware 구조
## 12. ROS 2 Sensor Bridge Node 구조
## 13. 빌드 방법
## 14. 실행 방법
## 15. 테스트 방법
## 16. 문제 해결
## 17. 실행 결과

1) 프로젝트 개요

이번 프로젝트는 Arduino 37종 센서 모듈 키트에서 센서 또는 출력 모듈 3개를 선택하고, Arduino와 ROS 2 Humble 환경을 연결하는 Sensor Bridge 시스템을 구현하는 실습입니다.

발표는 생략하며, 최종 결과는 README.md 중심으로 정리합니다. PPT는 필요할 경우 보조 자료로만 사용합니다.

## 1. 프로젝트 개요

- 팀명: Team01
- 팀원: 홍길동, 김철수
- Arduino 보드: Arduino Uno
- ROS 2 환경: ROS 2 Humble / TurtleBot3 Raspberry Pi
- 통신 방식: USB Serial
- Baudrate: 115200

### 프로젝트 목표

- Arduino에서 센서값을 읽는다.
- Arduino가 센서 데이터를 바이너리 패킷으로 ROS 2 브릿지 노드에 전송한다.
- ROS 2 브릿지 노드는 센서 데이터를 ROS 2 토픽으로 발행한다.
- ROS 2 토픽 명령을 Arduino로 전송하여 출력 모듈을 제어한다.

2) 팀원

팀원 이름과 역할을 정리합니다.

## 2. 팀원

| 이름 | 역할 | 담당 작업 |
|---|---|---|
| 홍길동 | Arduino / 하드웨어 | 센서 배선, Arduino 펌웨어, 패킷 송수신 |
| 김철수 | ROS 2 / 문서 | ROS 2 브릿지 노드, 토픽 설계, README 정리 |

2명 팀이므로 역할을 나누되, 최종적으로는 두 명 모두 전체 구조를 이해해야 합니다.

3) 사용 센서

선택한 센서 또는 출력 모듈 3개를 정리합니다.

권장 구성은 다음과 같습니다.

입력 센서 2개 + 출력 모듈 1개

예시:

## 3. 사용 센서

| 번호 | 모듈 이름 | 구분 | 용도 |
|---:|---|---|---|
| 1 | CDS 광센서 모듈 | 입력 센서 | 조도값 측정 |
| 2 | 버튼 모듈 | 입력 센서 | 버튼 상태 입력 |
| 3 | 부저 모듈 | 출력 모듈 | ROS 2 명령으로 ON/OFF 제어 |

센서 3개가 모두 입력 센서여도 되지만, 출력 모듈이 없으면 ROS 2 → Arduino 방향의 subscribe 실습이 약해집니다.

4) 하드웨어 구조

각 센서 모듈의 핀 구조, 주요 부품, 동작 방식을 정리합니다.

## 4. 하드웨어 구조

### 4.1 CDS 광센서 모듈

| 항목 | 내용 |
|---|---|
| 구분 | 입력 센서 |
| 동작 전압 | 5V |
| 출력 방식 | Analog / Digital |
| 핀 구조 | VCC, GND, AO, DO |
| 주요 부품 | CDS 센서, 비교기, 가변저항, 상태 LED |
| Arduino 연결 | AO → A0 |
| 주의사항 | DO는 가변저항 기준값에 따라 HIGH/LOW 출력 |

### 4.2 버튼 모듈

| 항목 | 내용 |
|---|---|
| 구분 | 입력 센서 |
| 동작 전압 | 5V |
| 출력 방식 | Digital |
| 핀 구조 | VCC, GND, OUT |
| Arduino 연결 | OUT → D2 |
| 주의사항 | 눌렀을 때 HIGH인지 LOW인지 실제 테스트 필요 |

### 4.3 부저 모듈

| 항목 | 내용 |
|---|---|
| 구분 | 출력 모듈 |
| 동작 전압 | 5V |
| 입력 방식 | Digital |
| 핀 구조 | VCC, GND, IN |
| Arduino 연결 | IN → D9 |
| 제어 방식 | HIGH/LOW |
| 주의사항 | Active buzzer / Passive buzzer 구분 필요 |

이 항목에는 가능하면 실제 센서 사진 또는 모듈 구조 이미지를 추가합니다.

![sensor_module_structure](hardware/sensor_module_structure.png)

5) 배선 연결표

Arduino와 센서 모듈 사이의 실제 연결 핀을 표로 정리합니다.

## 5. 배선 연결표

| 모듈 | VCC | GND | Signal | Arduino Pin |
|---|---|---|---|---|
| CDS 광센서 | 5V | GND | AO | A0 |
| 버튼 모듈 | 5V | GND | OUT | D2 |
| 부저 모듈 | 5V | GND | IN | D9 |

추가로 회로 연결 사진 또는 배선도를 포함합니다.

### 배선도

![wiring_diagram](hardware/wiring_diagram.png)

### 실제 연결 사진(배선도 작성이 어려울 경우 사진으로 대체 가능함)

![real_wiring_photo](hardware/real_wiring_photo.jpg)

주의사항도 같이 작성합니다.

### 연결 주의사항

- 모든 GND는 Arduino GND와 공통으로 연결한다.
- 3.3V 전용 센서는 5V에 직접 연결하지 않는다.
- 아날로그 출력은 A0, A1 등 아날로그 핀에 연결한다.
- 디지털 입력/출력은 D2, D3, D9 등 디지털 핀에 연결한다.
- Arduino와 TurtleBot3 또는 PC는 USB Serial로 연결한다.

6) 통신 프로토콜

Arduino와 ROS 2 브릿지 노드 사이의 시리얼 통신 프로토콜을 정의합니다.

## 6. 통신 프로토콜

본 프로젝트는 문자열 기반 Serial.println() 방식이 아니라, Serial.write() 기반 바이너리 패킷 통신을 사용한다.

### 6.1 기본 패킷 구조

| 필드 | 크기 | 설명 |
|---|---:|---|
| Start | 3 bytes | 0xAA 0xAA 0xAA |
| Packet ID | 1 byte | 센서 데이터 또는 명령 종류 |
| Length | 1 byte | Payload 길이 |
| Sequence | 1 byte | 패킷 순서 번호 |
| Payload | N bytes | 실제 센서값 또는 제어 명령 |
| Checksum | 1 byte | 오류 검출 |
| End | 2 bytes | 0xAA 0xEE |

### 6.2 전체 패킷 길이

Total Length = 9 + Payload Length

### 6.3 Checksum 계산 방식

Checksum은 Packet ID, Length, Sequence, Payload 전체 바이트를 더한 뒤 하위 1바이트만 사용한다.

```cpp
checksum = (packet_id + length + sequence + payload_sum) & 0xFF;

7) ROS2 토픽 정리

---

## 7. ROS 2 토픽

ROS 2에서 publish 또는 subscribe할 토픽을 정의합니다.

```markdown
## 7. ROS 2 토픽

| 구분 | 토픽 이름 | 메시지 타입 | 방향 | 설명 |
|---|---|---|---|---|
| Publish | /sensor/light | std_msgs/msg/Int32 | Arduino → ROS 2 | 조도값 발행 |
| Publish | /sensor/button | std_msgs/msg/Bool | Arduino → ROS 2 | 버튼 상태 발행 |
| Subscribe | /cmd/buzzer | std_msgs/msg/Bool | ROS 2 → Arduino | 부저 ON/OFF 제어 |

Packet ID와 ROS 2 토픽의 관계도 반드시 작성합니다.

### Packet ID 정의

| Packet ID | 방향 | 이름 | Payload 구조 | Length | ROS 2 토픽 |
|---|---|---|---|---:|---|
| 0x10 | Arduino → ROS 2 | LIGHT_DATA | uint16_t light | 2 | /sensor/light |
| 0x11 | Arduino → ROS 2 | BUTTON_DATA | uint8_t state | 1 | /sensor/button |
| 0x20 | ROS 2 → Arduino | BUZZER_CMD | uint8_t state | 1 | /cmd/buzzer |

중요 원칙:

Arduino firmware의 Packet ID와 ROS 2 bridge node의 Packet ID는 반드시 같아야 한다.

8) 빌드 방법

ROS 2 패키지 빌드 방법을 작성합니다.

## 8. 빌드 방법

### 8.1 워크스페이스 이동

```bash
cd ~/turtlebot3_ws

8.2 패키지 빌드

colcon build --packages-select team01_sensor_bridge

8.3 환경 설정

source install/setup.bash

`package.xml`에는 아래 항목이 반드시 있어야 합니다.

```xml
<export>
  <build_type>ament_cmake</build_type>
</export>

9) 실행 방법

Arduino 연결, 포트 확인, 브릿지 노드 실행 방법을 정리합니다.

## 9. 실행 방법

### 9.1 Arduino 연결 확인

```bash
ls /dev/ttyACM*
ls /dev/ttyUSB*

9.2 시리얼 권한 설정

sudo usermod -aG dialout $USER

권한 설정 후에는 재로그인 또는 재부팅한다.

9.3 ROS 2 브릿지 노드 실행

ros2 launch team01_sensor_bridge sensor_bridge.launch.py

10) 테스트 방법

---

## 10. 테스트 방법

센서 입력, 토픽 발행, 명령 구독, 출력 모듈 제어 테스트 방법을 작성합니다.

```markdown
## 10. 테스트 방법

### 10.1 토픽 목록 확인

```bash
ros2 topic list

10.2 조도 센서값 확인

ros2 topic echo /sensor/light

10.3 버튼 상태 확인

ros2 topic echo /sensor/button

10.4 부저 ON 명령

ros2 topic pub /cmd/buzzer std_msgs/msg/Bool "{data: true}"

10.5 부저 OFF 명령

ros2 topic pub /cmd/buzzer std_msgs/msg/Bool "{data: false}"

10.6 테스트 계획표(옵션)

테스트 계획표도 포함합니다.

```markdown
### 10.6 테스트 계획표

| 테스트 항목 | 확인 내용 | 통과 기준 |
|---|---|---|
| 센서 단독 테스트 | Arduino에서 센서값 확인 | 값이 정상적으로 변화 |
| 배선 테스트 | VCC/GND/Signal 확인 | 센서 오동작 없음 |
| 패킷 송신 테스트 | Arduino Serial.write 확인 | Start/End/Length 정상 |
| Checksum 테스트 | Checksum 계산 비교 | 오류 패킷 폐기 |
| ROS 2 수신 테스트 | 브릿지 노드 실행 | 패킷 파싱 성공 |
| Topic Publish 테스트 | ros2 topic echo | 센서값 출력 |
| Topic Subscribe 테스트 | ros2 topic pub | 출력 모듈 동작 |

11) 문제 해결

실습 중 자주 발생하는 문제와 해결 방법을 작성합니다.

## 11. 문제 해결

| 문제 | 원인 | 해결 방법 |
|---|---|---|
| `/dev/ttyACM0`가 보이지 않음 | Arduino 연결 불량 또는 케이블 문제 | USB 케이블 교체, 포트 재확인 |
| Permission denied 발생 | dialout 권한 없음 | `sudo usermod -aG dialout $USER` 실행 후 재부팅 |
| 센서값이 변하지 않음 | 배선 오류 또는 핀 번호 오류 | VCC/GND/Signal 연결 재확인 |
| 패킷 파싱 실패 | Start/End byte 불일치 | Arduino와 ROS 2의 패킷 구조 비교 |
| Checksum 오류 | 계산 방식 불일치 | 양쪽 checksum 계산 코드 통일 |
| 토픽이 보이지 않음 | 노드 실행 실패 | `ros2 node list`, `ros2 topic list` 확인 |
| 출력 모듈이 동작하지 않음 | Packet ID 또는 Payload 오류 | `/cmd/...` 토픽과 Arduino 명령 파싱 확인 |

12) 실행 결과

실제 실행 결과를 캡처 또는 표로 정리합니다.

## 12. 실행 결과

### 12.1 ros2 topic list 결과

```bash
/sensor/light
/sensor/button
/cmd/buzzer

12.2 조도 센서 출력 결과

data: 745
---
data: 620
---
data: 301

12.3 버튼 출력 결과

data: false
---
data: true

12.4 부저 제어 결과

명령	결과
/cmd/buzzer true	부저 ON
/cmd/buzzer false	부저 OFF

이미지도 포함할 수 있습니다.

```markdown
![topic_echo_capture](test/topic_echo_capture.png)

[ 추가 권장 항목 ]

기본 구조 1~12번은 반드시 작성하시고, 아래 항목도 작성해서 README 뒤쪽에 추가해 주시면 자료를 참조하데 도움이 될 것입니다.

13) Arduino Firmware 구조

## 13. Arduino Firmware 구조

Arduino firmware는 다음 기능을 수행한다.

1. 센서 핀 초기화
2. 센서값 읽기
3. Payload 생성
4. Checksum 계산
5. Serial.write() 기반 바이너리 패킷 송신
6. ROS 2 명령 패킷 수신
7. 명령 패킷 파싱
8. 출력 모듈 제어

### 주요 함수

```cpp
uint8_t calcChecksum(uint8_t packet_id,
                     uint8_t length,
                     uint8_t sequence,
                     uint8_t *payload);

void sendPacket(uint8_t packet_id,
                uint8_t *payload,
                uint8_t length);

void readSensors();

void handleCommandPacket();

14) 센서 브릿지 노드 구조

---

## 14. ROS 2 Sensor Bridge Node 구조

```markdown
## 14. ROS 2 Sensor Bridge Node 구조

ROS 2 브릿지 노드는 다음 기능을 수행한다.

1. 시리얼 포트 열기
2. 수신 버퍼 관리
3. Start bytes 탐색
4. Length 기반 전체 패킷 길이 계산
5. End bytes 확인
6. Checksum 검증
7. Packet ID 분기 처리
8. Payload를 센서값으로 변환
9. ROS 2 토픽 publish
10. ROS 2 토픽 subscribe
11. Arduino 명령 패킷 송신

권장 패키지 구조:

team01_sensor_bridge/
├── package.xml
├── resource
│   └── team01_sensor_bridge
├── setup.cfg
├── setup.py
└── team01_sensor_bridge
    ├── arduino_sensor_bridge.py
    └── __init__.py

15) 최종 제출 폴더 구조

## 15. 최종 제출 폴더 구조

```text
team01_sensor_bridge_project/
├── README.md
├── firmware/
│   └── team01_sensor_bridge/
│       └── team01_sensor_bridge.ino
├── ros2_package/
│   └── team01_sensor_bridge/
│       ├── CMakeLists.txt
│       ├── package.xml
│       ├── README.md
│       ├── include/
│       ├── src/
│       ├── launch/
│       └── config/
├── hardware/
│   ├── wiring_diagram.png
│   ├── sensor_module_structure.png
│   └── real_wiring_photo.jpg
├── test/
│   ├── test_plan.md
│   ├── test_result.md
│   └── topic_echo_capture.png
└── video/
    └── demo_video_link.txt

16) 최종 제출물

---

## 16. 최종 제출물

```markdown
## 16. 최종 제출물

| 번호 | 제출물 | 필수 여부 |
|---:|---|---|
| 1 | README.md | 필수 |
| 2 | Arduino firmware 소스 | 필수 |
| 3 | ROS 2 Humble 패키지 소스 | 필수 |
| 4 | 센서 하드웨어 구조 자료 | 필수 |
| 5 | Arduino 배선 연결도 또는 실제 배선 사진 | 필수 |
| 6 | 통신 프로토콜 정의표 | 필수 |
| 7 | ROS 2 토픽 정의표 | 필수 |
| 8 | 테스트 결과 캡처 | 필수 |
| 9 | 실행 영상 또는 영상 링크 | 권장 |

17) 팀별 개발 순서

## 17. 팀별 개발 순서

1. 센서 또는 모듈 3개 선택
2. 센서 핀 구조와 동작 전압 확인
3. README 초안 작성
4. 배선 연결표 작성
5. Arduino 단독 센서 테스트
6. Packet ID와 Payload 구조 정의
7. Arduino 바이너리 패킷 송신 구현
8. ROS 2 패키지 생성
9. 시리얼 수신 파서 구현
10. ROS 2 topic publish 구현
11. ROS 2 topic subscribe 구현
12. Arduino 출력 모듈 제어 구현
13. ros2 topic echo/pub 테스트
14. README에 실행 방법과 테스트 결과 정리
15. 최종 폴더 구조로 제출