xiaoai-patch 딥다이브
— 작은 스피커로 배우는 리눅스 시스템 조립법

1프로젝트 한줄 요약

xiaoai-patch는 XiaoAi 스피커의 루트 파일시스템을 수정하고, 음악 재생·음성비서·기기 제어 프로그램을 추가하는 스크립트와 빌드 레시피 모음입니다. 이 저장소에서 배울 핵심은 AI 모델을 만드는 법보다, 여러 프로그램을 작은 리눅스 기기 안에서 함께 동작시키는 법입니다.

재료는 기기에서 얻거나 펌웨어 업데이트에서 추출한 원본 이미지입니다. Makefile의 extract는 이미지를 디렉토리로 풀고, patch는 설정과 파일을 바꿉니다. build는 새 이미지를 만들고, release는 메타데이터·업데이트 도구·선택적인 커널 이미지까지 묶습니다.

추가 프로그램은 별도 빌드 엔진인 packages.sh가 준비합니다. 여기에 음악 서버 MPD, AirPlay 수신 도구 Shairport Sync, 동기 재생 도구 Snapcast, 깨우는 말 감지 도구 Porcupine, Python 웹 API가 연결됩니다. 이들을 이 저장소가 전부 직접 구현한 것은 아닙니다. 외부 소스를 가져와 기기에 맞게 빌드하고 배치하는 연결 코드가 중심입니다.

1-1. 무엇이 들어오고, 무엇이 나오는가

research/lx06/install.md는 커널을 수정하거나 다시 빌드하지 않고, 기존 순정 커널 이미지를 함께 배포한다고 명시합니다. packages/kernel-headers가 있다는 사실은 커널 자체를 새로 만든다는 뜻이 아닙니다. 사용자 공간 프로그램을 컴파일할 때 필요한 헤더를 준비하는 작업과 구분해야 합니다.

1-2. 음성비서는 어느 컴퓨터에서 생각할까

스피커에서는 Porcupine이 깨우는 말을 감지하고, 셸 런처가 음성을 녹음합니다. packages/porcupine/config/launcher는 녹음 데이터를 Home Assistant의 STT API로 보냅니다. README와 음성비서 문서에서는 Whisper를 그 제공자 예로 들지만, 이 저장소에 Whisper 모델을 스피커 안에서 추론하는 구현은 없습니다.

런처는 시작 시 확인한 API 실행 상태에 따라, 비어 있지 않은 인식 문장을 로컬 /intent로 먼저 보냅니다. API가 사용 불가로 표시되어 있거나 로컬 조회가 실패하면 Home Assistant의 /api/conversation/process에 보냅니다. 따라서 “로컬 기기를 활용한다”와 “모든 처리가 외부 통신 없이 끝난다”는 서로 다른 조건입니다.

2왜 주목받는가

선정 근거는 2026-10-23의 TrendShift Daily #24입니다. 같은 날 GitHub 기준 스타 492·포크 54입니다. 스타·포크 수와 일일 순위만으로 “어떤 사건 때문에 급상승했다”는 인과관계를 단정할 수는 없습니다.

아래는 프로젝트의 구조를 바탕으로 한 관심을 끌 만한 이유에 대한 해석입니다. 음성비서의 화려한 대화보다, 이미 있는 스피커를 사용자가 선택한 서비스로 다시 구성한다는 점에 이 프로젝트의 매력이 있습니다.

2-1. 하드웨어 재사용과 서비스 선택권

scripts/20_disable_services.sh는 제조사 관련 서비스의 자동 시작 링크를 제거합니다. scripts/24_remove_property_bin.sh는 관련 실행 파일과 라이브러리를 정리합니다. 그 자리에 음악 재생·발견·제어용 프로그램을 넣는 접근입니다.

README는 패치를 조절하면 원래 XiaoAi 기능과 새 프로그램을 함께 유지할 수도 있다고 설명합니다. 그러나 기본 스크립트는 여러 제조사 기능을 제거하도록 작성되어 있습니다. 병행 사용은 자동으로 보장되는 기본 동작이 아니라, 사용자가 수정하고 검증해야 하는 구성입니다.

2-2. 여러 오디오 생태계를 한 기기에 조합한다

여기서 장점은 기존 오픈소스 도구를 작은 장치에 맞춰 결합할 수 있다는 데 있습니다. 각 도구의 설정·리소스·호환성 문제도 함께 관리해야 합니다.

2-3. 대안과 비교하면 선택 기준이 선명해진다

이는 개별 상용 제품의 성능 평가가 아니라, 구현 방식의 비교입니다. xiaoai-patch의 장점은 이미 가진 호환 기기를 재활용할 때 커집니다. 새 장치를 구매해야 하거나 안정적인 완제품 경험이 우선이라면 판단이 달라집니다.

2-4. 최근 변경도 시스템 통합의 현실을 보여 준다

HEAD c26bef8은 2026-09-29의 LX06 부팅 반복 문제 문서 수정입니다. 일부 Foresee/ESMT NAND를 예전 커널이 인식하지 못하는 상황을 다룹니다. 최신 푸시가 새 기능 코드라는 뜻은 아니며, 장치별 복구 경험이 문서에 쌓이는 것도 중요한 유지보수입니다.

이 레포의 교육적 가치는 기능 목록보다, 하드웨어 제약이 빌드 옵션과 운영 절차를 어떻게 바꾸는지 드러낸다는 데 있습니다. 다음 절부터는 그 연결을 파일과 함수 단위로 따라갑니다.

3기술 스택 전체 지도

2026-10-23 GitHub 기준 주 언어는 Makefile입니다. 실제로는 최상위 Makefile과 많은 셸 레시피가 조립을 담당합니다. package.mk라는 이름만 보고 모두 GNU Make 문법이라고 생각하면 안 됩니다. packages.sh의 load_package()가 이 파일을 Bash의 source로 읽습니다.

3-1. 백엔드: 기기 제어 API와 음성 처리 연결

api/requirements.txt의 Flask-MQTT·paho-mqtt·tflite-runtime·numpy는 주석 처리된 항목입니다. 설치되는 의존성처럼 세면 안 됩니다. 특히 numpy는 임시 공간의 가용 메모리를 초과한다는 주석이 있습니다. 실제로 모델 추론을 구현했다는 근거로 삼을 수 없습니다.

api/main.py는 app.run(debug=False, host='0.0.0.0', port=80)로 시작합니다. 별도의 데이터베이스 서버는 보이지 않으며, 설정은 /data/listener와 /data/tts.conf, 시스템 정보는 /proc·/sys·UCI 파일에서 읽습니다.

3-2. 프론트엔드: 빌드 단계가 없는 작은 관리 화면

api/static/index.html은 Materialize 1.0.0을 CDN 주소로 참조합니다. 동작은 api/static/app.js의 순수 JavaScript이며 React·Vue·TypeScript 코드는 없습니다. 저장소 전체에서 package.json·Cargo.toml·pyproject.toml·go.mod도 발견되지 않았습니다.

관리 화면은 외부 CDN에서 Materialize의 CSS와 JavaScript를 불러오므로, 파일을 기기에 둔다고 완전한 오프라인 화면이 되는 것은 아닙니다.

3-3. 오디오와 시스템 라이브러리

이 버전은 레시피가 요청하는 버전입니다. 레시피 선언만으로 실제 배포 이미지의 설치 버전까지 확정할 수는 없습니다. 같은 저장소 커밋이어도 범위 의존성이나 master가 가리키는 내용은 다운로드 시점에 달라질 수 있습니다.

3-4. 인프라·빌드: 오래된 대상과 현재 빌드 환경의 연결

.github/workflows/build-packages.yaml은 actions/checkout@v6·actions/upload-artifact@v7를 선언합니다. .github/workflows/build-release.yaml은 actions/download-artifact@v8, docker/login-action@v4, actions/attest@v4 등을 사용합니다. 이 버전 표기는 워크플로의 선언값이며, 실행 성공 여부와는 별개입니다.

Dockerfile의 pip3 install meson ninja도 정확한 버전을 지정하지 않습니다. 버전 문자열이 여러 곳에 적혀 있어도, 입력 전체가 고정되어야 같은 결과를 다시 만들 수 있습니다. 이 차이가 재현 가능한 빌드를 공부하는 첫 단서입니다.

4아키텍처 심화 분석

4-1. 먼저 전체 시스템을 두 장으로 나눈다

한 장은 개발 컴퓨터에서 이미지를 만드는 경로이고, 다른 한 장은 완성된 이미지가 스피커에서 실행되는 경로입니다. 이 둘을 섞으면 Docker가 스피커 안에서 돌아간다거나, Python API가 펌웨어를 컴파일한다는 식의 오해가 생깁니다.

Makefile의 all: extract patch build release에는 패키지 컴파일이 포함되지 않습니다. 패키지 준비는 별도 단계이며, scripts/92_copy_build_packages.sh는 결과 폴더가 없으면 건너뜁니다. 따라서 all이라는 이름만으로 모든 입력이 자동 생성된다고 판단하면 안 됩니다. 병렬 Make 실행의 안전한 순서까지 이 선언 하나가 보장하는 것도 아닙니다.

음성 루프는 packages/porcupine/config/launcher에 있고, Flask의 /intent는 단순한 문장 매칭을 맡습니다. 서버가 음성 전체를 중계하는 구조가 아니라, 셸 런처가 Home Assistant와 직접 통신한다는 점이 중요합니다.

4-2. 패턴 ① 단계별 파이프라인과 훅

packages.sh의 commence_build()는 모든 패키지에 공통인 작업 순서를 정합니다. func_exists()로 함수가 있는지 확인하고, 레시피가 제공한 단계만 실행합니다. 공통 뼈대는 엔진이 소유하고 세부 동작은 패키지가 채우는 방식입니다.

# packages.sh의 build_stages에 선언된 순서
preconfigure_package
configure_package
premake_package
make_package
preinstall_package
install_package
postinstall_package

# 각 단계 전에 존재 여부를 확인한 뒤 호출
if func_exists ${stage}; then
    ${stage}
fi

예를 들어 packages/mpd/package.mk의 configure_package()는 Meson의 크로스 파일을 넘기고, packages/alsa-lib/package.mk는 Autotools의 ./configure에 컴파일러와 호스트 정보를 넘깁니다. 두 도구의 차이는 레시피 안에 머물고, 바깥 실행 순서는 같습니다.

reset_package_vars()는 변수뿐 아니라 이전 레시피의 훅 함수도 unset -f로 지웁니다. 이 작업이 없다면 앞 패키지의 install_package()가 뒤 패키지에 남아 실행될 수 있습니다. 전역 상태를 사용하는 설계에서는 초기화가 실행 흐름의 일부입니다.

4-3. 패턴 ② 의존성 그래프와 상태 캐시

process_package()는 먼저 패키지를 읽고, PACKAGE_DEPENDS에 적힌 이름들을 재귀 호출합니다. 의존성 빌드가 전역 변수를 덮어쓰므로, 돌아온 다음 현재 패키지에 대해 init_package()를 다시 호출합니다.

# packages.sh의 process_package()에서 핵심 부분 발췌
local current_package=${PACKAGE}
init_package

if [[ ! -z "${PACKAGE_DEPENDS}" ]]; then
    for depend in ${PACKAGE_DEPENDS}
    do
        process_package $depend
    done
    PACKAGE=${current_package}
    init_package
fi

PACKAGES_PROCESSED 배열은 같은 실행에서 이미 방문한 이름을 다시 순회하지 않도록 합니다. 패키지 초기화 전에 이름을 등록하므로 빌드 완료 목록은 아닙니다. 이는 중복 방지 장치이며, 순환 의존성의 경로와 원인을 알려 주는 검사기는 아닙니다. 그래프의 방문 여부와 “현재 방문 중” 상태를 분리하는 설계와 비교해 볼 수 있습니다.

update_package_status()는 build_id와 build_status를 .status 파일에 기록합니다. package_needs_building()은 완료 상태가 아니거나, 의존성이 이번 BUILD_ID에서 새로 빌드되었으면 재빌드를 요구합니다. 반환값 0은 빌드 필요, 1은 생략 가능, 2는 오류입니다.

이 캐시는 레시피 내용·컴파일 옵션·원격 소스의 해시 전체를 비교하는 방식이 아닙니다. 레시피를 바꿨는데 상태만 보고 생략할 가능성을 검토해야 합니다. “이전 실행을 기억한다”와 “현재 입력이 동일함을 증명한다”는 다른 수준의 기능입니다.

4-4. 패턴 ③ 관리 API를 시스템 명령의 어댑터로 쓰기

api/main.py의 set_volume_level()는 숫자 범위와 믹서 이름을 검사합니다. 이어서 api/utils.py의 set_volume()가 0~100 값을 0~255로 바꾸고 amixer를 호출합니다. HTTP 요청을 장치 제어로 번역하는 작은 어댑터입니다.

# api/utils.py의 set_volume()에서 발췌
volume = max(0, min(100, volume))
volume = int(volume * 255 / 100)
result = subprocess.run(
    ['amixer', 'set', mixer, f'{volume}'],
    capture_output=True,
    check=True
)

manage_service(service, action)도 같은 원리입니다. api/const.py의 services_allowed에 있는 서비스와 start·stop·restart 동작만 허용한 뒤 /etc/init.d를 호출합니다. 명령 경계에서 입력을 좁히는 방식을 배울 수 있습니다.

서비스 자체는 packages/core_api/config/api.init의 start_service()가 procd에 등록합니다. Python 프로세스와 _xiaoai._tcp mDNS 광고를 별도 인스턴스로 띄웁니다. 관리 API, 프로세스 감독, 네트워크 발견은 서로 다른 책임입니다.

4-5. 패턴 ④ 로컬 명령 우선, 외부 처리로 이어지는 음성 흐름

get_stt_settings()는 Home Assistant가 제공하는 샘플레이트·채널·비트 수를 읽고 런처 값을 조정합니다. 녹음 후 통째로 보내기보다 녹음→변환→전송을 파이프로 잇고, tee로 중간 음성도 남깁니다. 재생 볼륨을 줄이고 끝에 복원하는 동작까지 하나의 루프에 들어 있습니다.

api/intents.py의 get_intents()는 소문자 변환, 일부 악센트와 구두점 제거, YAML의 대체어 적용을 거친 뒤 문장 목록에서 정확히 일치하는 항목을 찾습니다. 자연어 모델이 아니라 규칙 기반 분기입니다. 성공한 로컬 명령은 런처의 intent_run()으로 실행합니다.

하나의 요청이 어느 경계에서 다른 프로그램으로 넘어가는지 추적하면, 복잡한 시스템도 입력·변환·출력의 연결로 읽을 수 있습니다. 다음 절에서는 그 경계를 디렉토리 지도에 표시합니다.

5디렉토리 구조 해부

다음은 주요 경로를 골라 줄인 트리입니다. 파일 경로와 실습 명령은 최상위 Makefile이 있는 저장소 루트를 기준으로 합니다.

5-1. 이름이 비슷한 두 종류의 패치를 구분한다

세 번째 경로는 상류 프로그램이 오래된 기기 환경에서 컴파일되도록 조정하는 데 쓰입니다. 첫 두 경로는 기기에 들어갈 파일의 동작을 바꿉니다. 같은 patch 명령을 써도 입력과 결과가 다릅니다.

5-2. 파일·줄 수로 보는 규모

집계 기준은 git ls-files의 추적 파일입니다. 줄 수는 NUL 바이트가 없고 UTF-8로 읽히는 텍스트의 줄바꿈 수이며, 빈 줄과 주석을 포함합니다. 일반 파일을 가리키는 심볼릭 링크는 대상 내용을 각각 세고, 끊어진 링크와 디렉토리 링크는 제외합니다. 바이너리·이미지·압축 소스도 제외합니다. 외부 프로젝트 전체의 소스 규모나 실행 코드만의 줄 수를 뜻하지 않습니다.

추적 파일 전체는 418개입니다. 셸 분류에는 확장자가 .sh인 파일과, 확장자에 관계없이 #!/bin/sh·#!/bin/bash로 시작하는 파일을 포함합니다. API 폴더의 Python 5개는 752줄이며, 전체 Python 1,618줄과 구분됩니다. C/C++ 구현이 이 저장소 안에 대량 포함되어 있다는 뜻도 아닙니다.

5-3. 초보자를 위한 세 가지 읽기 경로

1. 이미지 경로: Makefile → scripts/10_apply_patches.sh → 모델 패치 → scripts/92_copy_build_packages.sh.
2. API 경로: api/static/app.js → api/main.py → api/config.py 또는 api/utils.py.
3. 음성 경로: docs/voice-assistant.md → packages/porcupine/config/launcher → api/intents.py → api/intents.yaml.

처음부터 182개 레시피를 순서대로 읽을 필요는 없습니다. 작은 요청 하나를 고르고, 그것이 지나가는 파일을 끝까지 따라가는 편이 구조를 이해하기 쉽습니다.

6학습 포인트 (기술별)

6-1. 셸: 표준 입출력으로 프로그램 연결하기

런처의 음성 전송은 유닉스 파이프의 실제 사례입니다. 녹음 도구는 소리를 바이트로 내보내고, FFmpeg는 형식을 바꾸며, curl은 그 바이트를 전송합니다. 각 프로그램이 상대방의 내부 구현을 몰라도 표준 입출력이라는 약속으로 협력합니다.

# launcher의 긴 전송 구간을 구조만 남겨 표현한 도식
녹음 명령
  | tee /tmp/input.wav
  | FFmpeg 형식·채널·샘플레이트 변환
  | tee /tmp/stt.wav
  | curl로 Home Assistant에 전송

tee는 관찰을 쉽게 하지만 음성과 로그가 임시 파일에 남습니다. cleanup()은 일부 파일을 지우고 log()는 /tmp/stt.log에 문자를 기록합니다. 디버깅 가능성과 데이터 보관 범위가 같은 코드에서 결정되는 것입니다.

실습 아이디어: 각 파이프의 입력 형식·출력 형식·실패 시 표시를 종이에 적어 보세요. 런처는 ffmpeg 존재 여부를 확인하는 구간이 있지만, 전송 파이프에서는 여전히 ffmpeg를 호출합니다. 이 정적 관찰을 “대체 경로가 완성되어 있는가?”라는 검토 질문으로 바꾸면 좋습니다.

6-2. 종료 코드: 실패가 어디서 사라지는가

scripts/10_apply_patches.sh는 여러 패치를 적용한 뒤 마지막에 true를 실행합니다. 이 스크립트에는 즉시 중단 설정이 없어서, 중간의 패치 실패가 최종 종료 코드에 반영되지 않을 수 있습니다. 바깥 Makefile이 스크립트 종료 코드를 검사하더라도, 안쪽에서 성공으로 바뀌면 놓칠 수 있습니다.

# scripts/10_apply_patches.sh의 핵심 발췌
for PATCHFILE in patches/*.patch patches/${MODEL}/*.patch; do
  patch -p1 --no-backup-if-mismatch -r /dev/null \
    -d ${ROOTFS} < ${PATCHFILE}
done

true

실습 아이디어: 첫 번째·중간·마지막 패치가 실패하는 경우를 각각 추적해 보세요. “실패 로그가 있다”와 “상위 작업이 실패한다”를 다른 칸에 적습니다. 일반적인 파이프 종료 상태는 GNU Bash 공식 문서와 대조할 수 있습니다.

여기서 곧바로 모든 곳에 set -e를 넣자는 결론을 내릴 필요는 없습니다. 의도적으로 실패를 허용한 단계도 있을 수 있으므로, 어떤 오류는 계속 진행하고 어떤 오류는 중단할지 계약부터 정하는 것이 학습의 핵심입니다.

6-3. 크로스컴파일: CPU 이름만 맞으면 충분한가

packages/toolchain/package.mk의 on_exit_build()는 컴파일러뿐 아니라 BUILD_CFLAGS·BUILD_LDFLAGS·pkg-config 경로를 함께 설정합니다. 헤더·링커·동적 로더·공유 라이브러리가 대상 시스템과 맞아야 실행할 수 있기 때문입니다.

research/lx06/boot에는 AArch64 커널과 32비트 사용자 공간 지원이 보이지만, 기본 패키지 출력은 armv7입니다. CPU가 64비트를 지원한다는 사실만으로 사용자 공간 전체를 64비트로 바꿀 수 있다고 판단하면 안 됩니다.

실습 아이디어: MPD 레시피에서 컴파일러·sysroot·pkg-config·설치 경로가 어디서 오는지 선으로 연결하세요. packages/toolchain/config/meson-cross-file.in과 CMake 템플릿을 비교하면 같은 대상 정보를 도구별로 표현하는 방법을 배울 수 있습니다.

6-4. 오디오: 형식·샘플레이트·채널을 분리하기

런처 기본 녹음 설정은 16,000Hz·1채널이며, STT 전송 기본값은 8,000Hz·16비트·1채널입니다. 이후 get_stt_settings()가 제공자 응답에 맞춰 전송 값을 조정합니다. 문서의 설정 예시는 STT_RATE=16000이므로 코드의 기본값과 같지 않습니다.

# 압축하지 않은 PCM 데이터량의 개념 계산
바이트/초 = 샘플레이트 × 채널 수 × 비트 수 ÷ 8
16,000 × 1 × 16 ÷ 8 = 32,000바이트/초
5초 녹음 ≈ 160,000바이트

# WAV 헤더·네트워크 부가 정보는 제외한 값

실습 아이디어: 48,000Hz·2채널·16비트로 바꾸면 초당 192,000바이트가 됩니다. 같은 길이라도 왜 메모리·전송 비용이 6배가 되는지 계산해 보세요. 이어서 packages/mpd/config/mpd.conf의 FIFO 형식 48000:16:2를 해석해 봅니다.

6-5. HTTP 계약: 선언한 기능과 실행 분기를 맞춰 보기

api/intents.yaml에는 Next 명령이 있고, get_intents()는 일치하면 그 이름을 반환합니다. 그러나 런처의 intent_run()에는 Next 처리 분기가 없습니다. 로컬 매칭은 성공해서 Home Assistant 경로도 생략할 수 있으므로, 목록에 있다는 사실만으로 실제 동작까지 구현되었다고 볼 수 없습니다.

실습 아이디어: YAML의 모든 action과 런처 분기 목록을 대조하는 표를 만들어 보세요. 반환 가능한 값과 처리 가능한 값의 집합이 같은지 확인하는 일은 API·이벤트·메시지 시스템에서도 반복되는 작업입니다.

ConfigManager.to_dict()는 이름에 token이 들어간 키를 API 응답에서 제외합니다. 이는 표시 범위를 줄이는 처리이며, 파일 자체의 암호화나 접근 제어를 구현한 것은 아닙니다. 데이터를 읽는 곳·저장하는 곳·보여 주는 곳을 나눠 생각해 보세요.

6-6. 파일 형식: 무결성 검사와 진위 검증의 차이

tools/mico_firmware.py의 ImageHeader·SegmentHeader는 바이너리 구조를 정의합니다. Firmware.verify()는 매직 값 0x31524448·0x32524448, 서명 영역의 길이, CRC32, 파일명에 포함된 MD5 일부를 검사합니다.

성공 로그는 제조사 정품 펌웨어라는 취지의 표현을 쓰지만, 이 함수에서 공개키로 서명을 암호학적으로 검증하는 연산은 보이지 않습니다. signature라는 변수명이나 해시 일치만으로 누가 만든 파일인지 증명했다고 해석하면 안 됩니다.

실습 아이디어: “형식이 맞는가”, “데이터가 손상되지 않았는가”, “신뢰하는 제작자가 만들었는가”를 세 열로 나누고 각 검사를 분류하세요. 이 파일은 실행하지 말고 구조체 필드와 verify()의 읽기 순서를 추적합니다.

소스 읽기는 함수 이름을 외우는 일이 아니라, 입력을 받아 약속한 결과를 끝까지 내보내는지 확인하는 일입니다. 잘 만든 연결과 빠진 연결을 함께 찾는 습관이 중요합니다.

7하드웨어 / 시스템 요구사항

7-1. 공부용 컴퓨터와 빌드용 컴퓨터

README는 패키지 빌드에 1시간 이상이 걸릴 수 있다고 안내합니다. 호스트 RAM·디스크의 확정 최소치는 README에 명시되어 있지 않습니다.

코드에 aarch64 호스트 분기가 있어도 README는 Apple M1·Windows 호스트를 미지원·미검증으로 표시합니다. 반면 LX06의 설치 안내는 Ubuntu 24.04와 Windows 10의 USB 기록 절차를 설명합니다. 빌드 호스트 지원과 기록 도구 지원을 분리해야 두 설명이 모순처럼 보이지 않습니다.

7-2. 모델별 상태를 읽는 방법

Home Assistant 사용자 구성 요소의 DEVICES_COMPATIBLE는 LX06·L06A·L09A만 포함합니다. 펌웨어 패치 지원 범위와 사용자 구성 요소가 받아들이는 모델 목록도 같지 않습니다.

7-3. 저장 공간은 이미지 형식과 함께 봐야 한다

build_squashfs는 크기가 지정된 기준보다 크거나 같으면 경고를 출력하고 종료 코드 1로 중단합니다. 표의 숫자만으로 실제 파티션의 여유 공간까지 보장되지는 않습니다. 리눅스 커널 문서가 설명하듯 SquashFS는 압축된 읽기 전용 파일시스템이므로, 앱을 넣을 때 이미지 자체를 다시 만드는 방식이 자연스럽습니다.

LX06 문서는 RAM 128MB·256MB 변형을 적고 있습니다. MPD 설정의 input_cache는 20MB이며, 업데이트 도구는 기본 가용 메모리 기준을 45000KB로 둡니다. 모두 같은 “메모리” 이야기지만, 물리 RAM·프로세스 버퍼·업데이트 시 남아 있어야 할 공간은 별도 항목입니다.

지원 모델 이름이 같아도 메모리·무선 칩·NAND·기존 커널이 다를 수 있으므로, 호환성은 부품과 버전의 조합으로 판단해야 합니다.

8직접 해볼 수 있는 실습 과제

모든 과제의 명령은 저장소 루트에서 읽기 전용으로 사용합니다. Makefile과 packages.sh 등의 내용을 출력하거나 검색하는 명령이며, 저장소의 Python 모듈을 import하거나 셸 스크립트를 실행할 필요는 없습니다.

# 저장소 루트에서 파일을 읽기만 합니다
sed -n '1,110p' Makefile
rg -n '^all:|^extract|^patch:|^build|^release' Makefile
sed -n '1,35p' scripts/92_copy_build_packages.sh

sed -n '173,207p' api/main.py
sed -n '50,87p' api/utils.py
rg -n 'volume_controls|mysoftvol|notifyvol' api/const.py

rg -n 'action:|Next' api/intents.yaml
sed -n '1,110p' api/intents.py
sed -n '146,167p' packages/porcupine/config/launcher
sed -n '264,309p' packages/porcupine/config/launcher

sed -n '1,15p' packages/core_api/package.mk
sed -n '1,10p' packages/python3/package.mk
sed -n '425,456p' packages.sh
sed -n '549,599p' packages.sh

cat api/requirements.txt
sed -n '1,12p' packages/squeezelite/package.mk
cat scripts/10_apply_patches.sh
cat .github/workflows/build-packages.yaml

실습의 성공 기준은 스피커를 바꾸는 데 있지 않고, 코드가 약속한 동작을 근거 파일과 함께 설명할 수 있게 되는 데 있습니다.

9관련 기술 심화 학습 로드맵

아래 로드맵은 레포의 도구를 실행하는 일정이 아니라, 읽은 코드를 일반적인 시스템 지식으로 확장하는 일정입니다. 하드웨어 작업은 별도 실습으로 분리하고, 먼저 모델과 무관하게 설명할 수 있는 개념을 익힙니다.

9-1. 셸 다음에는 프로세스의 생명주기로 확장하기

packages/porcupine/config/porcupine.init의 start_service()·stop_service()·reload_service()를 비교하세요. 시작 명령만이 아니라 자식 프로세스 정리, PID 파일, LED 상태, 재시작 정책이 하나의 서비스 경험을 만듭니다.

API와 리스너 모두 procd_set_param respawn 3600 5 0을 선언합니다. 숫자의 정확한 의미는 사용하는 procd 버전 문서와 대조해 읽고, “재시작 설정이 있다”는 사실만으로 장애 복구가 모두 해결된다고 해석하지 않습니다.

9-2. 업데이트 다음에는 상태 전이로 확장하기

bin/update.sh의 get_boot() → set_target_partitions() → flash_image() → switch_boot()를 종이에 이어 보세요. 현재 사용하지 않는 파티션을 고르는 의도와, 기록 후 다음 부팅 대상을 바꾸는 순서를 이해하는 것이 목표입니다.

이어 “기록 명령이 실패하면 부팅 전환을 막는가?”를 점검합니다. flash_image()의 실패 경로에는 오류 출력으로 이어지는 분기가 있고, 호출부에는 파이프도 있습니다. 실행하지 않고도 실패를 상위로 확실히 전달하는 설계인지 검토할 수 있습니다.

9-3. 마지막에는 제품의 약속을 검토하기

“지원한다”, “로컬이다”, “오픈소스다”, “검증했다” 같은 표현을 보이면 무엇을 근거로 하는지 되묻습니다. 예를 들어 Porcupine 레시피는 C 예제를 컴파일하면서 상류의 libpv_porcupine.so도 복사합니다. 저장소의 빌드 코드가 공개되어 있다는 것과 모든 포함 바이너리의 내부 구현도 저장소에 포함된다는 것은 다릅니다.

Home Assistant 구성 요소의 custom_components/xiaoai_assist/manifest.json은 0.0.1이고, 해당 디렉토리에는 구성 흐름과 상수·번역 등이 있습니다. 완성된 엔티티 플랫폼으로 취급하기보다 validate_input()의 연결 검사와 설정 흐름을 배우는 자료로 읽는 편이 정확합니다.

학습의 끝은 특정 스피커의 명령을 외우는 것이 아니라, 다른 리눅스 장치에서도 같은 경계를 찾아 설명할 수 있게 되는 것입니다.

10핵심 키워드 사전

새 단어를 만나면 이 표의 정의를 읽고, 실제 사용하는 파일 한 곳을 다시 찾아보세요. 예를 들어 ABI는 툴체인 설정, STT는 런처의 HTTP 헤더, mDNS는 packages/core_api/config/api.init에서 확인할 수 있습니다.

11참고 링크

11-1. 저장소와 핵심 소스

아래 코드 링크와 글 속 파일 경로는 커밋 c26bef8 기준이며, 기본 브랜치의 미래 상태와 다를 수 있습니다.

• 공식 저장소 · README: 목적·지원 범위·준비 사항
• Makefile: 이미지 생성·모델 분기·배포 포장
• packages.sh: 의존성·훅·상태 캐시
• 툴체인 레시피 · 빌드용 Dockerfile
• Python API · Python 의존성 선언
• 장치 제어·시스템 정보 함수 · 관리 화면 JavaScript
• 음성 루프와 intent_run() · 로컬 명령 매칭
• 업데이트·파티션 선택 · 바이너리 형식 읽기·검사
• 릴리스 워크플로 · Home Assistant 설정 흐름 초안

11-2. 설치 문맥과 관련 기술의 공식 자료

• LX06 설치 문서: 백업과 NAND 부팅 반복 사례
• 프로젝트 음성비서 문서 · FAQ
• 리눅스 커널: SquashFS 구조와 읽기 전용 압축 파일시스템
• GNU Bash: 파이프라인과 종료 상태
• Home Assistant: STT 제공자와 음성 스트림
• MPD 공식 저장소 · Shairport Sync 공식 저장소 · Snapcast 공식 저장소
• 최신 릴리스 2026.3.26 (2026-10-23 GitHub 기준) · 분석 기준 커밋
• TrendShift — 선정 순위: 2026-10-23 Daily #24.

현재 상태 (2026-10-23 확인)

코드의 동작 설명은 커밋 c26bef8을, 지원 범위·소요 시간은 README와 모델 문서를 기준으로 합니다. 주목받는 이유에 대한 설명은 기술적 해석입니다. 관련 기술의 공식 문서는 개념을 더 살펴볼 때 참고할 수 있습니다.