diff --git a/README.md b/README.md index 3f28f19..b8ed565 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,35 @@ # mic -Orange Pi Zero 2W 기반 Wi-Fi 라발리에 마이크 송신기와 Mac 수신/믹서 프로젝트입니다. +Orange Pi Zero 2W를 사용하는 Wi-Fi 라발리에 마이크 송신기와 Mac 수신/믹서 프로젝트입니다. + +## 먼저 읽어야 할 문서 + +이 프로젝트에 참여하는 AI는 어떤 작업을 시작하기 전에 반드시 아래 문서를 먼저 읽어야 합니다. + +- `docs/00-ai-collaboration-rules.md`: AI 협업 기본 규칙 + +특히 사용자가 계획을 확정하고 실행을 지시하기 전까지는 코드를 만들지 않습니다. 구현 언어는 C++입니다. ```text -USB lavalier -> Orange Pi Zero 2W -> 2.4/5 GHz Wi-Fi router -> Mac mixer +USB 라발리에 마이크 -> Orange Pi Zero 2W -> 2.4/5 GHz Wi-Fi 공유기 -> Mac 믹서 ``` -## Structure +## 프로젝트 구조 -- `client/`: Orange Pi에서 실행하는 마이크 송신기 -- `server/`: Mac에서 실행하는 UDP 수신/믹서 -- `os/`: Orange Pi OS 이미지 보관 위치 -- `docs/`: 보드 세팅과 스트리밍 실행 가이드 +- `client/`: Orange Pi에서 실행할 마이크 송신기 소프트웨어 +- `server/`: Mac에서 실행할 수신/믹서 소프트웨어 +- `os/`: Orange Pi에 설치할 OS 이미지 보관 위치 +- `docs/`: 보드 설정과 실행 절차 문서 +- `plans/`: AI 작업 플랜 기록 위치 -## Current Direction +## 현재 방향 -- OS: official Orange Pi Debian 12 Bookworm Server, Linux 6.1 -- Language: C++ +- 임베디드 보드: Orange Pi Zero 2W +- OS 기준: Orange Pi 공식 Debian 12 Bookworm Server, Linux 6.1 +- 구현 언어: C++ -## Docs +## 문서 -- `docs/01-orange-pi-os.md` +- `docs/00-ai-collaboration-rules.md`: AI 협업 기본 규칙 +- `docs/01-orange-pi-os.md`: Orange Pi Zero 2W OS 설치 준비 +- `plans/README.md`: 플랜 파일 작성 형식 diff --git a/docs/00-ai-collaboration-rules.md b/docs/00-ai-collaboration-rules.md new file mode 100644 index 0000000..f958967 --- /dev/null +++ b/docs/00-ai-collaboration-rules.md @@ -0,0 +1,174 @@ +# AI 협업 기본 규칙 + +이 문서는 이 프로젝트에 참여하는 모든 AI와 사람이 공통으로 따라야 할 기본 규칙입니다. + +프로젝트의 방향이 흔들리지 않도록, 새로 참여하는 AI는 작업을 시작하기 전에 반드시 이 문서를 먼저 읽어야 합니다. + +## 프로젝트 요약 + +이 프로젝트는 Orange Pi Zero 2W를 마이크 송신기로 사용하고, Mac을 수신기이자 믹서로 사용하는 Wi-Fi 오디오 시스템입니다. + +```text +USB 라발리에 마이크 -> Orange Pi Zero 2W -> 2.4/5 GHz Wi-Fi 공유기 -> Mac 수신/믹서 +``` + +## 현재 기준 + +- 임베디드 장비: Orange Pi Zero 2W +- 저장장치: microSD Ultra 32GB +- 권장 OS: Orange Pi 공식 Debian 12 Bookworm Server, Linux 6.1 +- 구현 언어: C++ +- `client/`: Orange Pi에서 실행할 송신기 소프트웨어 +- `server/`: Mac에서 실행할 수신기/믹서 소프트웨어 +- `os/`: Orange Pi에 설치할 OS 이미지 보관 위치 +- `docs/`: 프로젝트 문서 +- `plans/`: AI 작업 플랜 기록 위치 + +## 가장 중요한 규칙 + +사용자가 명확하게 계획을 확정하고 실행하라고 말하기 전까지는 코드를 만들지 않습니다. + +다음과 같은 작업은 사용자 승인 없이 진행하지 않습니다. + +- C++ 소스 코드 생성 +- 빌드 시스템 생성 +- 테스트 코드 생성 +- 패키지 설치 스크립트 생성 +- 기존 코드 구조 변경 +- 프로토콜, 아키텍처, 라이브러리 선택 확정 + +문서 정리, 현재 상태 확인, 파일 목록 확인, OS 이미지 검증처럼 코드가 아닌 준비 작업은 사용자의 요청 범위 안에서만 수행합니다. + +## 언어 규칙 + +- 구현 언어는 C++입니다. +- Python 기반 송신기, 수신기, 테스트 코드는 만들지 않습니다. +- 임시 분석이나 파일 확인을 위해 로컬 도구를 사용할 수는 있지만, 프로젝트 산출물로 Python 코드를 추가하지 않습니다. +- 문서는 기본적으로 한국어로 작성합니다. +- 외부 링크, 파일명, 명령어, 패키지명은 원문을 유지합니다. + +## 작업 방식 + +AI는 작업을 시작하기 전에 먼저 현재 저장소 상태를 확인해야 합니다. + +권장 확인 항목: + +- 현재 브랜치와 변경사항 +- `README.md` +- `docs/00-ai-collaboration-rules.md` +- 관련 디렉터리의 파일 목록 +- 사용자가 직접 만든 변경사항 여부 + +작업 중 사용자가 만든 변경사항을 되돌리지 않습니다. 변경사항이 작업과 충돌하면 되돌리기보다 사용자에게 확인합니다. + +## 계획 우선 원칙 + +코드 구현이 필요한 단계에서는 먼저 계획을 작성합니다. + +계획에는 다음 항목을 포함합니다. + +- 목표 +- 대상 환경 +- 사용할 언어와 라이브러리 후보 +- 송신기와 수신기의 역할 분리 +- 오디오 캡처 방식 +- 네트워크 전송 방식 +- 지연 시간과 안정성 목표 +- 검증 방법 + +사용자가 계획을 확인하고 실행을 지시한 뒤에만 구현을 시작합니다. + +## 플랜 파일 작성 규칙 + +AI가 작업을 진행할 때는 `plans/` 폴더에 자신의 작업 플랜을 기록합니다. + +기본 절차: + +1. 자신의 대화 또는 작업 단위를 식별할 임시 고유 UUID를 생성합니다. +2. `plans/{uuid}.md` 파일을 생성합니다. +3. 해당 파일에 자신이 할 일 목록을 작성합니다. +4. 작업을 순차적으로 진행하면서 같은 `.md` 파일의 할 일 상태와 메모를 수정합니다. +5. 작업 완료 후 결과 요약을 같은 파일에 남깁니다. + +플랜 파일은 작업의 흐름을 남기기 위한 기록입니다. 사용자가 실행을 지시하지 않은 코드 구현을 정당화하는 용도로 사용하지 않습니다. + +권장 형식은 `plans/README.md`를 따릅니다. + +## 설계 원칙 + +초기 목표는 복잡한 기능보다 안정적인 오디오 경로 확인입니다. + +우선순위: + +1. Orange Pi에서 USB 라발리에 마이크 인식 +2. Mac에서 UDP 수신 가능 여부 확인 +3. 단일 송신기 오디오 전송 검증 +4. 지연 시간과 끊김 확인 +5. 다중 송신기 믹싱 +6. 압축, 동기화, 자동 검색, UI 같은 확장 기능 검토 + +초기 설계에서 지나치게 복잡한 기능을 먼저 넣지 않습니다. + +## OS 이미지 규칙 + +`os/` 폴더에는 Orange Pi OS 이미지 파일을 보관할 수 있습니다. + +다운로드한 원본 압축 파일인 `.7z`는 커밋할 수 있습니다. 단, 압축을 풀어서 나온 실제 디스크 이미지 파일은 용량이 크고 Git에 적합하지 않으므로 커밋하지 않습니다. + +커밋하지 않는 파일 예시: + +```text +os/*.img +os/*.img.* +os/*/*.img +os/*/*.img.* +``` + +일반 ARM64 Debian/Ubuntu 이미지가 아니라 Orange Pi Zero 2W 전용 이미지를 사용해야 합니다. + +## 외부 정보 확인 + +OS 다운로드 링크, 보드 지원 상태, 라이브러리 지원 여부처럼 시간이 지나며 바뀔 수 있는 정보는 가능한 최신 공식 자료를 확인합니다. + +우선순위: + +1. Orange Pi 공식 문서 +2. 라이브러리 공식 문서 +3. 운영체제 공식 문서 +4. 커뮤니티 자료 + +커뮤니티 자료를 사용할 경우 공식 자료가 아니라는 점을 명확히 표시합니다. + +## 문서 수정 규칙 + +문서를 수정할 때는 다음 기준을 지킵니다. + +- 한국어로 자연스럽게 작성합니다. +- 실제로 결정된 내용과 후보를 구분합니다. +- 추측은 결정처럼 쓰지 않습니다. +- 명령어는 검증된 경우에만 절차로 적습니다. +- 아직 구현되지 않은 기능을 이미 있는 기능처럼 설명하지 않습니다. + +## 금지 사항 + +다음 작업은 하지 않습니다. + +- 사용자 승인 없는 코드 생성 +- 사용자 승인 없는 대규모 구조 변경 +- Python 기반 구현 추가 +- 압축 해제된 `.img` OS 이미지 파일 커밋 +- 보드 전용 이미지가 아닌 일반 ARM64 이미지를 권장 +- 확인되지 않은 성능 수치를 확정값처럼 작성 +- 사용자가 만든 변경사항 되돌리기 + +## 새 AI를 위한 첫 행동 + +새로 참여한 AI는 다음 순서로 시작합니다. + +1. `README.md`를 읽습니다. +2. `docs/00-ai-collaboration-rules.md`를 읽습니다. +3. 현재 Git 변경사항을 확인합니다. +4. 사용자의 최신 요청을 확인합니다. +5. 작업이 필요한 경우 임시 UUID를 만들고 `plans/{uuid}.md`에 할 일 목록을 작성합니다. +6. 코드가 필요한 작업이면 먼저 계획을 제시합니다. +7. 사용자가 실행을 지시하기 전까지 구현하지 않습니다. diff --git a/docs/01-orange-pi-os.md b/docs/01-orange-pi-os.md index 27b5805..9966bb3 100644 --- a/docs/01-orange-pi-os.md +++ b/docs/01-orange-pi-os.md @@ -1,44 +1,67 @@ -# Orange Pi Zero 2W OS setup +# Orange Pi Zero 2W OS 설치 준비 -## Recommended image +## 권장 이미지 -Use the official Debian 12 Bookworm server image for Orange Pi Zero 2W: +Orange Pi Zero 2W용 공식 Debian 12 Bookworm Server 이미지를 우선 사용합니다. ```text -orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z +Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z ``` -Orange Pi's Zero 2W wiki lists Debian 12 Bookworm with Linux 6.1 as supported, and its Linux 6.1 driver table marks Wi-Fi, Type-C USB2.0, TF card boot, and related board features as OK. +이 이미지를 권장하는 이유는 다음과 같습니다. -Official references: +- 서버 이미지라 불필요한 데스크톱 환경이 없습니다. +- 마이크 송신기처럼 headless로 동작하는 장비에 적합합니다. +- Linux 6.1 기반 공식 이미지라 Zero 2W의 Wi-Fi, USB, TF 카드 부팅 등 기본 보드 기능을 기대할 수 있습니다. +- 이후 C++ 기반 송신기 소프트웨어를 올리기 좋은 가벼운 출발점입니다. + +공식 참고 링크: - https://www.orangepi.org/orangepiwiki/index.php/Orange_Pi_Zero_2W - https://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html +- http://www.orangepi.cn/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html -## Flashing +## 이미지 파일 확인 -1. Download the image into `os/`. -2. Extract the `.7z` file to get the `.img`. -3. Flash the `.img` to the microSD with Balena Etcher, Raspberry Pi Imager, or another verified imaging tool. -4. Mount the flashed boot/root partition and configure first-run Wi-Fi before inserting it into the Orange Pi. +`os/` 폴더에 다운로드한 압축 파일을 보관합니다. -## Headless Wi-Fi first boot +```text +os/Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z +``` -On the flashed SD card, find: +압축 파일 안에는 보통 다음 파일들이 들어 있습니다. + +```text +Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.img +Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.img.sha +``` + +`.img` 파일은 microSD에 실제로 기록할 OS 이미지이고, `.sha` 파일은 이미지 무결성 검증에 사용합니다. + +## microSD에 기록하기 + +1. `.7z` 압축 파일을 풉니다. +2. 나온 `.img` 파일을 확인합니다. +3. Balena Etcher, Raspberry Pi Imager, Win32 Disk Imager 같은 도구로 `.img` 파일을 microSD에 기록합니다. +4. 기록이 끝나면 microSD를 다시 마운트해서 첫 부팅용 Wi-Fi 설정을 준비합니다. + +## Headless Wi-Fi 첫 부팅 설정 + +키보드와 모니터 없이 처음 부팅하려면, 기록된 microSD의 boot 파티션에서 다음 파일을 찾습니다. ```text /boot/orangepi_first_run.txt.template ``` -Copy it to: +이 파일을 복사해서 아래 이름으로 만듭니다. ```text /boot/orangepi_first_run.txt ``` -Then set the Wi-Fi fields. `os/orangepi_first_run.example.txt` contains a local example for Korea region code `KR`. +그다음 Wi-Fi 관련 값을 수정합니다. 예시는 `os/orangepi_first_run.example.txt`에 있습니다. -The important values are: +중요한 값은 다음과 같습니다. ```text FR_net_change_defaults=1 @@ -49,19 +72,27 @@ FR_net_wifi_key='YOUR_WIFI_PASSWORD' FR_net_wifi_countrycode='KR' ``` -## First login +한국에서 사용할 경우 국가 코드는 `KR`로 둡니다. -For official Debian/Ubuntu Orange Pi images, the usual default accounts are: +## 첫 로그인 + +Orange Pi 공식 Debian/Ubuntu 이미지의 기본 계정은 보통 다음과 같습니다. ```text orangepi / orangepi root / orangepi ``` -Change the password on first login. +첫 로그인 후에는 반드시 비밀번호를 변경합니다. ```bash passwd sudo passwd root ``` +## 다음 단계 + +OS 부팅과 SSH 접속이 확인되면, USB 라발리에 마이크 인식 여부와 Wi-Fi 연결 안정성을 확인합니다. + +송신기와 수신기 소프트웨어는 이후 C++ 기준으로 설계하고 구현합니다. + diff --git a/os/README.md b/os/README.md index ad3fd25..71f6bf0 100644 --- a/os/README.md +++ b/os/README.md @@ -1,26 +1,43 @@ -# OS image storage +# OS 이미지 보관 위치 -Put the Orange Pi Zero 2W OS image files here, but do not commit them. +이 폴더는 Orange Pi Zero 2W에 설치할 OS 이미지 파일을 보관하는 곳입니다. -Recommended first image: +다운로드한 원본 `.7z` 파일은 이 폴더에 보관하고 Git에 커밋할 수 있습니다. 단, 압축을 풀어서 나온 `.img` 파일은 용량이 크고 Git에 적합하지 않으므로 커밋하지 않습니다. + +`.gitignore`에서는 다음 파일만 제외합니다. ```text -orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z +os/*.img +os/*.img.* +os/*/*.img +os/*/*.img.* ``` -Why this one: +## 권장 이미지 -- Debian 12 Bookworm server image keeps the transmitter small and headless. -- Linux 6.1 is listed by Orange Pi as supporting Wi-Fi, Type-C USB2.0, TF card boot, and the usual board peripherals on Zero 2W. -- A server image gives us a small, headless baseline for the future C++ transmitter. +첫 설치 이미지로는 다음 파일을 권장합니다. -Official pages: +```text +Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z +``` + +## 권장 이유 + +- Debian 12 Bookworm Server 이미지는 가볍고 headless 장비에 적합합니다. +- 마이크 송신기처럼 GUI가 필요 없는 장비에서는 서버 이미지가 더 안정적인 출발점입니다. +- Linux 6.1 기반 공식 이미지라 Orange Pi Zero 2W의 Wi-Fi, USB, TF 카드 부팅 등 기본 기능을 기대할 수 있습니다. +- 이후 C++ 기반 송신기 소프트웨어를 올리기 좋은 기준 환경입니다. + +## 공식 참고 링크 - https://www.orangepi.org/orangepiwiki/index.php/Orange_Pi_Zero_2W - https://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html +- http://www.orangepi.cn/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html -Notes: +## 주의사항 -- Use the Zero 2W-specific image only. A generic ARM64 Debian or Ubuntu image will usually miss the board kernel/DTB/Wi-Fi pieces. -- The official download page may redirect to external storage such as Google Drive. -- Keep `.7z`, `.img`, `.xz`, and similar files in this folder locally; `.gitignore` excludes them. +- 일반 ARM64 Debian/Ubuntu 이미지가 아니라, 반드시 Orange Pi Zero 2W 전용 이미지를 사용해야 합니다. +- 보드 전용 이미지가 아니면 커널, DTB, Wi-Fi 드라이버 문제로 부팅이나 네트워크 연결이 실패할 수 있습니다. +- 공식 다운로드 페이지가 Google Drive 같은 외부 저장소로 연결될 수 있습니다. +- 다운로드한 `.7z` 원본 압축 파일은 이 폴더에 보관하고 Git에 올릴 수 있습니다. +- 압축을 풀어서 나온 `.img` 파일은 이 폴더에 보관하더라도 Git에는 올리지 않습니다. diff --git a/plans/README.md b/plans/README.md new file mode 100644 index 0000000..cb74d2e --- /dev/null +++ b/plans/README.md @@ -0,0 +1,39 @@ +# 플랜 폴더 + +이 폴더는 AI가 작업을 진행하기 전에 자신의 작업 계획을 기록하는 곳입니다. + +각 AI는 작업 단위마다 임시 고유 UUID를 만들고, 아래 형식의 파일을 생성합니다. + +```text +plans/{uuid}.md +``` + +플랜 파일에는 자신이 할 일 목록을 작성하고, 작업을 순차적으로 진행하면서 상태를 계속 갱신합니다. + +예시: + +```text +plans/00000000-0000-0000-0000-000000000000.md +``` + +## 기본 형식 + +```markdown +# 작업 플랜 + +- UUID: `{uuid}` +- 작업자: `{AI 이름 또는 식별자}` +- 생성 시각: `{YYYY-MM-DD HH:mm}` +- 요청 요약: `{사용자의 최신 요청 요약}` + +## 할 일 + +- [ ] 현재 요청 확인 +- [ ] 관련 문서 확인 +- [ ] 작업 수행 +- [ ] 결과 검증 +- [ ] 완료 내용 정리 +``` + +작업이 진행되면 완료된 항목을 `[x]`로 바꾸고, 필요한 메모를 같은 파일에 남깁니다. +