07. Raspberry Pi 5 + Pico 2 W 프로젝트 구조 설계

Об этом предложении

지금까지 Raspberry Pi 5와 Pico 2 W를 이용해 다음 내용을 살펴봤다. Raspberry Pi SSH ↓ Pico 2 W MicroPython ↓ GPIO ↓ Serial / UART ↓ Wi-Fi ↓ Network Communication 각 기능을 개별적으로 테스트하는 단계에서는 파일 몇 개만 있어도 충분하다. 하지만 센서, 데이터 저장, 통신, 분석 기능이 추가되기 시작하면 하나의 파일에 모든 코드를 작성하기 어렵다. 예를 들어 프로젝트가 다음과 같이 커질 수 있다. Sensor ↓ Pico 2 W ↓ UART / Wi-Fi ↓ Raspberry Pi 5 ↓ Data Processing ↓ CSV / Database ↓ Visualization ↓ Machine Learning 이 단계부터는 프로젝트 구조를 처음부터 잘 나누는 것 이 중요하다. 이번 글에서는 Raspberry Pi 5와 Pico 2 W를 함께 사용하는 프로젝트를 GitHub에서 관리할 수 있도록 기본적인 프로젝트 구조를 설계한다. 1. Raspberry Pi 5와 Pico 2 W의 역할부터 나누기 폴더를 만들기 전에 두 장치의 역할을 먼저 구분하는 것이 좋다. Pico 2 W Pico 2 W는 마이크로컨트롤러이므로 하드웨어와 가까운 작업을 담당한다. Pico 2 W ├─ GPIO ├─ ADC ├─ PWM ├─ Sensor Reading ├─ Timing ├─ Hardware Control ├─ UART └─ Wi-Fi 즉, Physical Layer 에 가까운 역할을 담당한다. Raspberry Pi 5 Raspberry Pi 5는 Linux 기반 컴퓨터이므로 상대적으로 복잡한 작업을 담당한다. Raspberry Pi 5 ├─ Data Collection ├─ Data Processing ├─ File Storage ├─ Database ├─ Visualization ├─ Networking ├─ Web Server ├─ Signal Processing ├─ Machine Learning └─ System Management 즉, Application / Processing Layer 역할을 맡는다. 2. 전체 시스템 구조 프로젝트 전체를 다음과 같이 생각할 수 있다. ┌─────────────────────────┐ │ Physical World │ │ │ │ Sensor / Electrode │ │ Button / LED / Motor │ └───────────┬─────────────┘ │ ▼ ┌─────────────────────────┐ │ Pico 2 W │ │ │ │ GPIO / ADC / PWM │ │ Sensor Acquisition │ │ Hardware Control │ └───────────┬─────────────┘ │ │ UART / USB / Wi-Fi │ ▼ ┌─────────────────────────┐ │ Raspberry Pi 5 │ │ │ │ Python │ │ Data Processing │ │ Storage │ │ Visualization │ │ Network │ └───────────┬─────────────┘ │ ▼ ┌─────────────────────────┐ │ Mac / GitHub / Server │ └─────────────────────────┘ 이 구조를 그대로 프로젝트 폴더에도 반영하면 관리하기 쉬워진다. 3. Git 저장소는 하나로 관리하기 Raspberry Pi 코드와 Pico 코드를 각각 다른 Repository로 만들어도 되지만 처음에는 하나의 Repository 안에서 분리하는 방식 이 관리하기 편하다. 예를 들어 프로젝트 이름을 BioLoop-Pi 라고 한다면 BioLoop-Pi/ │ ├── pi/ │ └── pico/ 처럼 구성한다. 즉, 하나의 프로젝트 ↓ 하나의 Git Repository ↓ Pi 코드 + Pico 코드 구조이다. 4. 기본 프로젝트 구조 처음 추천하는 구조는 다음과 같다. BioLoop-Pi/ │ ├── README.md ├── .gitignore │ ├── pi/ │ ├── app/ │ │ ├── main.py │ │ ├── serial_reader.py │ │ ├── network_client.py │ │ └── data_logger.py │ │ │ ├── tests/ │ │ │ └── requirements.txt │ ├── pico/ │ ├── main.py │ ├── app.py │ ├── wifi.py │ ├── communication.py │ ├── sensors.py │ │ │ ├── lib/ │ │ │ └── secrets.example.py │ ├── data/ │ ├── raw/ │ └── processed/ │ ├── scripts/ │ ├── docs/ │ └── logs/ 프로젝트가 작을 때는 다소 복잡해 보일 수 있지만 기능이 추가되기 시작하면 이런 구조가 훨씬 관리하기 쉽다. 5. 각각의 폴더 역할 pi/ Raspberry Pi 5에서 실행되는 프로그램을 저장한다. pi/ │ ├── app/ ├── tests/ └── requirements.txt Raspberry Pi에서는 일반 Python을 사용한다. 예: import serial import json import time pico/ Pico 2 W에서 실행되는 MicroPython 코드를 저장한다. pico/ │ ├── main.py ├── app.py ├── wifi.py ├── communication.py ├── sensors.py └── lib/ 이 폴더의 코드는 Pico 내부 Flash로 복사해 실행하게 된다. data/ 센서 데이터를 저장한다. data/ │ ├── raw/ │ └── processed/ raw 는 원본 데이터, data/raw/ processed 는 필터링이나 분석이 끝난 데이터로 구분할 수 있다. data/processed/ docs/ 프로젝트 문서를 저장한다. docs/ │ ├── architecture.md ├── hardware.md ├── protocol.md └── experiments.md 예를 들어 hardware.md → 회로 구성 protocol.md → Pi ↔ Pico 통신 규칙 experiments.md → 실험 기록 처럼 관리할 수 있다. scripts/ 개발 과정에서 반복적으로 사용하는 명령을 자동화한다. 예: scripts/ ├── deploy_pico.sh ├── run_pi.sh └── setup_pi.sh 프로젝트가 어느 정도 커진 뒤 추가해도 된다. logs/ 프로그램 실행 로그를 저장한다. logs/ ├── system.log ├── sensor.log └── error.log 로그 파일은 크기가 계속 증가할 수 있기 때문에 일반적으로 Git에는 포함하지 않는다. 6. Mac을 개발의 기준 Repository로 사용하기 개인 프로젝트라면 Mac에 있는 Git Repository를 주 개발 원본 으로 관리하는 방식이 편하다. 구조는 다음과 같다. Mac │ │ Git ▼ GitHub │ │ git clone / git pull ▼ Raspberry Pi 5 Pico 코드는 같은 Repository의 pico/ 폴더에서 관리한다. Mac │ ├─ pi/ │ └─ pico/ │ │ USB ▼ Pico 2 W 즉 Git Repository 자체를 Pico에 저장하는 것이 아니다. 7. Pico는 Git Repository가 아니다 이 부분이 중요하다. Pico 내부에는 MicroPython Flash 파일 시스템이 있지만 Linux 환경이 아니다. 따라서 Pico 안에서 git status git pull git push 같은 명령을 사용하는 구조가 아니다. Git의 기준 파일은 Mac이나 Raspberry Pi에 저장한다. Git Repository │ ▼ Mac / Raspberry Pi │ │ 필요한 MicroPython 파일 복사 ▼ Pico 2 W 즉 Pico 내부의 파일은 배포된 실행본 이라고 생각하면 이해하기 쉽다. 8. Pico 코드도 항상 Repository에 원본을 보관하기 예를 들어 Pico에서 사용하는 파일이 다음과 같다고 하자. main.py wifi.py sensors.py communication.py 이 파일의 원본은 BioLoop-Pi/pico/ 에 둔다. 그리고 필요한 파일을 Pico 내부로 복사한다. Git Repository pico/ ├── main.py ├── wifi.py ├── sensors.py └── communication.py │ │ Deploy ▼ Pico Flash / ├── main.py ├── wifi.py ├── sensors.py └── communication.py 이렇게 하면 Pico가 고장 나거나 Firmware를 다시 설치해도 코드를 Git에서 복원할 수 있다. 9. Pico의 main.py 는 최대한 단순하게 만들기 처음에는 모든 코드를 main.py 하나에 작성하기 쉽다. 예: import network import socket from machine import Pin, ADC # 수백 줄의 코드... 하지만 프로젝트가 커지면 관리하기 어렵다. 대신 main.py 는 프로그램의 Entry Point 역할만 담당하게 만든다. 예: import app app.main() 그리고 실제 프로그램은 app.py 에서 실행한다. MicroPython의 공식 문서에서도 복잡한 프로그램에서는 main.py 를 간단한 진입점으로 두고 실제 애플리케이션 모듈을 import하여 실행하는 구조를 사용할 수 있다고 설명한다. 10. Pico 애플리케이션 구조 예를 들어 다음과 같이 나눌 수 있다. pico/ │ ├── main.py ├── app.py ├── sensors.py ├── communication.py ├── wifi.py └── lib/ main.py import app app.main() app.py import time from sensors import read_sensor from communication import send_data def main(): while True: value = read_sensor() send_data(value) time.sleep(1) sensors.py from machine import ADC sensor = ADC(26) def read_sensor(): return sensor.read_u16() 이렇게 기능별로 파일을 나누게 된다. 11. MicroPython의 부팅 파일 MicroPython에서는 boot.py main.py 가 특별한 의미를 가진다. 기본적인 실행 순서는 Pico Power ON ↓ boot.py ↓ main.py 이다. MicroPython 문서에서도 boot.py 가 먼저 실행되고 이후 main.py 가 실행되는 부팅 구조를 설명한다. 다만 처음 프로젝트를 만들 때는 반드시 boot.py 를 만들 필요는 없다. 12. boot.py 에 모든 것을 넣지 않기 boot.py 는 초기화 용도로 사용하는 것이 좋다. 예를 들어 Hardware 초기 설정 Network 초기 설정 등을 넣을 수 있다. 하지만 프로그램 전체를 boot.py 안에서 무한 반복시키는 방식은 피하는 것이 좋다. MicroPython 문서 역시 boot.py 는 종료되는 초기화 코드에 적합하며 실제 애플리케이션은 main.py 에서 실행하는 구조를 권장한다. 처음에는 오히려 boot.py 없음 main.py → app.py 실행 정도로 시작해도 충분하다. 13. Raspberry Pi 코드도 기능별로 나누기 Raspberry Pi에서도 모든 코드를 하나의 파일에 넣지 않는다. 예를 들어 pi/app/ │ ├── main.py ├── serial_reader.py ├── network_client.py ├── data_logger.py └── config.py 처럼 구성한다. 14. Raspberry Pi main.py 예: from serial_reader import SerialReader from data_logger import DataLogger def main(): reader = SerialReader() logger = DataLogger() while True: data = reader.read() if data is not None: logger.save(data) if __name__ == "__main__": main() main.py 역시 전체 프로그램의 흐름만 관리하게 만든다. 15. Serial 코드 분리 serial_reader.py import serial class SerialReader: def __init__( self, port="/dev/ttyAMA0", baudrate=115200 ): self.serial = serial.Serial( port, baudrate, timeout=1 ) def read(self): data = self.serial.readline() if not data: return None return ( data .decode("utf-8") .strip() ) 이렇게 하면 Serial 관련 코드를 다른 부분과 분리할 수 있다. 16. 데이터 저장 코드 분리 data_logger.py from datetime import datetime from pathlib import Path class DataLogger: def __init__(self): self.path = Path( "../../data/raw/sensor.csv" ) def save(self, value): timestamp = datetime.now().isoformat() with self.path.open( "a", encoding="utf-8" ) as file: file.write( f"{timestamp},{value}\n" ) 프로젝트가 커지면 Sensor Communication Storage Processing 기능이 서로 섞이지 않게 된다. 17. Raspberry Pi에서는 Python 가상환경 사용하기 Raspberry Pi의 Python 프로젝트에서는 가상환경 을 사용하는 것이 좋다. 가상환경을 사용하면 프로젝트에 필요한 Python 패키지를 시스템 Python과 분리해서 관리할 수 있다. Python 공식 문서에서도 venv 는 프로젝트별로 독립된 Python 패키지 환경을 생성하기 위한 기능이며 일반적으로 .venv 같은 디렉터리를 사용한다고 설명한다. 프로젝트 폴더에서 cd BioLoop-Pi/pi 가상환경을 만든다. python3 -m venv .venv 환경에 따라 venv 패키지가 없다면 먼저 설치한다. sudo apt install python3-venv 18. 가상환경 활성화 source .venv/bin/activate 성공하면 Terminal 앞부분에 (.venv) 가 나타난다. 예: (.venv) minwoo@raspberrypi:~/BioLoop-Pi/pi $ 이 상태에서 설치한 Python 패키지는 해당 프로젝트 환경에 설치된다. 19. 필요한 패키지 설치 예를 들어 UART를 사용한다면 python -m pip install pyserial 추후 데이터 처리에 NumPy를 사용한다면 python -m pip install numpy 처럼 설치한다. 가상환경 안에서 pip 를 사용하면 프로젝트에 필요한 패키지를 시스템 환경과 분리할 수 있다. 20. requirements.txt 프로젝트에 필요한 Python 패키지를 기록한다. 예: pi/requirements.txt 내용: pyserial numpy 다른 Raspberry Pi에서 프로젝트를 실행할 때는 python -m pip install -r requirements.txt 로 필요한 패키지를 설치할 수 있다. 21. .venv 는 GitHub에 올리지 않는다 Python 가상환경은 다른 컴퓨터에서 다시 생성할 수 있기 때문에 Git으로 관리하지 않는다. Python 공식 문서 역시 가상환경은 소스 관리 시스템에 포함하지 않고 필요하면 다시 생성하는 것을 전제로 한다. 따라서 .gitignore 에 .venv/ 를 추가한다. 22. .gitignore 기본 구성 프로젝트 루트에 .gitignore 파일을 만든다. 예: # Python virtual environment .venv/ venv/ # Python cache __pycache__/ *.pyc # macOS .DS_Store # Secrets secrets.py .env # Logs logs/ *.log # Experimental data data/raw/ data/processed/ # IDE .vscode/ .idea/ 필요에 따라 수정하면 된다. 23. 센서 데이터는 Git에 올려야 할까? 일반적으로 대용량 센서 Raw Data는 Git에 계속 올리지 않는 것이 좋다. 예: data/raw/ 에는 실험을 할 때마다 많은 파일이 생길 수 있다. sensor_001.csv sensor_002.csv sensor_003.csv ... 이런 파일을 모두 Git에 넣으면 Repository 크기가 빠르게 증가한다. 따라서 기본적으로 data/raw/ data/processed/ 로 제외할 수 있다. 24. 폴더 자체는 Git에 남기고 싶다면 Git은 빈 디렉터리를 추적하지 않는다. 따라서 data/raw/ 폴더 안에 .gitkeep 같은 빈 파일을 넣는 방법을 사용할 수 있다. 예: data/ ├── raw/ │ └── .gitkeep │ └── processed/ └── .gitkeep .gitignore 설정에 따라 .gitkeep 예외 규칙을 추가하면 된다. 25. Wi-Fi 비밀번호와 API Key는 코드와 분리하기 다음과 같이 직접 작성하면 ssid = "MyWiFi" password = "12345678" GitHub에 코드가 올라갈 때 비밀번호도 함께 올라갈 수 있다. 따라서 Pico에서는 secrets.py 를 별도로 사용한다. 예: SSID = "MyWiFi" PASSWORD = "12345678" 그리고 secrets.py 로 Git에서 제외한다. 26. secrets.example.py 만들기 하지만 secrets.py 를 완전히 제외하면 다른 사람이 어떤 설정값이 필요한지 알기 어렵다. 따라서 secrets.example.py 를 Repository에 넣는다. SSID = "YOUR_WIFI_NAME" PASSWORD = "YOUR_WIFI_PASSWORD" 사용자는 이 파일을 복사해 secrets.py 를 만들면 된다. 27. Raspberry Pi 설정도 같은 방식으로 관리하기 Raspberry Pi에서 사용하는 설정도 코드와 분리하는 것이 좋다. 예: .env PICO_PORT=/dev/ttyAMA0 BAUD_RATE=115200 그리고 .env 로 제외한다. Repository에는 .env.example 을 저장한다. 예: PICO_PORT=/dev/ttyAMA0 BAUD_RATE=115200 28. Pi와 Pico 사이의 통신 규칙 만들기 프로젝트가 커지면 단순히 값을 하나 보내는 것보다 통신 규칙을 정하는 것이 좋다. 예: TEMP:24.8 ADC:32510 STATUS:OK 또는 JSON을 사용할 수도 있다. { "type": "sensor", "temperature": 24.8, "adc": 32510 } 이 규칙을 docs/protocol.md 에 작성한다. 29. protocol.md 예시 # Communication Protocol Baud Rate 115200 Encoding UTF-8 Message Terminator \n 메시지 종류: TEMP:<value> ADC:<value> STATUS:<value> 예: TEMP:24.8 ADC:32510 STATUS:OK 명령: LED:ON LED:OFF START STOP 이렇게 정해두면 Pi와 Pico 프로그램을 각각 수정하더라도 통신 규칙을 쉽게 확인할 수 있다. 30. 프로젝트 구조를 한 단계 더 정리하기 조금 더 체계적으로 만들면 다음처럼 구성할 수 있다. BioLoop-Pi/ │ ├── README.md ├── .gitignore │ ├── pi/ │ │ │ ├── app/ │ │ ├── main.py │ │ ├── serial_reader