# 패키지 목록과 설치된 패키지 업데이트
sudo apt update
sudo apt upgrade -y

# 시간대 확인 및 설정
timedatectl
sudo timedatectl set-timezone Asia/Seoul

# 장치 이름 변경
sudo hostnamectl set-hostname aiot-robot-01

# 재부팅
sudo reboot

여러 보드를 동시에 쓰면 호스트명이 중요합니다. raspberrypi가 여러 대 있으면 SSH 접속과 로그 관리가 금방 헷갈립니다.

ls -l run_robot.sh
# -rwxr-xr-- 1 ubuntu ubuntu 320 Jun 11 10:00 run_robot.sh
#  소유자: rwx = 읽기, 쓰기, 실행
#  그룹:   r-x = 읽기, 실행
#  기타:   r-- = 읽기

• chmod 755 run_robot.sh: 소유자는 모든 권한, 그룹/기타 사용자는 읽기와 실행 권한을 갖습니다.
• chmod 644 config.yaml: 설정 파일처럼 실행할 필요 없는 파일에 적합합니다.
• sudo chown ubuntu:ubuntu data.db: 파일 소유자를 바꿉니다. root로 만든 파일 때문에 앱이 저장하지 못할 때 필요합니다.

# python 프로세스 검색
ps -ef | grep python

# 포트 8000을 쓰는 프로세스 확인
sudo lsof -i :8000

# 일반 종료 요청
kill PID

# 마지막 수단: 강제 종료
kill -9 PID

kill -9는 저장 중인 파일을 정리할 기회를 주지 않습니다. 먼저 일반 kill이나 서비스 종료 명령을 사용합니다.

# 로그에서 ERROR가 들어간 줄만 번호와 함께 보기
grep -n "ERROR" logs/app.log

# 최근 수정된 파일 10개 확인
find . -type f -printf "%T@ %p\n" | sort -nr | head -n 10

# 디스크를 많이 쓰는 폴더부터 정렬
du -sh * | sort -hr | head

# 1초마다 온도 또는 상태 명령 반복 실행
watch -n 1 vcgencmd measure_temp

# 특정 포트를 쓰는 프로세스 찾기
sudo lsof -i :8000
ss -lntp | grep 8000

파이프(|)는 앞 명령의 결과를 다음 명령으로 넘깁니다. 로그 분석, 용량 점검, 네트워크 확인처럼 결과를 좁혀 볼 때 자주 씁니다.

# 패키지 목록 갱신
sudo apt update

# 설치된 패키지 업그레이드
sudo apt upgrade -y

# 패키지 검색과 설치
apt search mosquitto
sudo apt install -y mosquitto mosquitto-clients

# 더 이상 필요 없는 패키지 정리
sudo apt autoremove -y

AIoT 프로그램은 보통 전원이 켜지면 자동으로 시작해야 합니다. systemd 유닛 파일을 만들면 재부팅 뒤에도 자동 실행되고, 실패 로그도 추적할 수 있습니다.

# /etc/systemd/system/aiot-camera.service
[Unit]
Description=AIoT Camera Inference Service
After=network-online.target
Wants=network-online.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/aiot-project
ExecStart=/home/ubuntu/aiot-project/.venv/bin/python app.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable aiot-camera
sudo systemctl start aiot-camera
systemctl status aiot-camera
journalctl -u aiot-camera -f

패키지 다운로드가 느리면 국내 미러를 쓰면 좋습니다. 다만 미러는 "무조건 빠른 서버"가 아니라 동기화 상태, 학교/집 네트워크 경로, 사용하는 Ubuntu 버전에 따라 체감이 달라집니다. 수정 전에는 반드시 원본 설정을 백업합니다.

참고 링크: KAIST FTP Mirror, Kakao Ubuntu Releases Mirror

Ubuntu 22.04 이하 또는 구형 이미지처럼 /etc/apt/sources.list를 쓰는 경우입니다.

sudo cp /etc/apt/sources.list /etc/apt/sources.list.backup
sudo sed -i 's|http://archive.ubuntu.com/ubuntu|https://ftp.kaist.ac.kr/ubuntu|g' /etc/apt/sources.list
sudo sed -i 's|http://kr.archive.ubuntu.com/ubuntu|https://ftp.kaist.ac.kr/ubuntu|g' /etc/apt/sources.list
sudo sed -i 's|http://security.ubuntu.com/ubuntu|https://ftp.kaist.ac.kr/ubuntu|g' /etc/apt/sources.list
sudo apt update

Ubuntu 24.04 계열처럼 Deb822 형식의 ubuntu.sources를 쓰는 경우입니다.

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.backup
sudo sed -i 's|http://archive.ubuntu.com/ubuntu|https://ftp.kaist.ac.kr/ubuntu|g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's|http://kr.archive.ubuntu.com/ubuntu|https://ftp.kaist.ac.kr/ubuntu|g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's|http://security.ubuntu.com/ubuntu|https://ftp.kaist.ac.kr/ubuntu|g' /etc/apt/sources.list.d/ubuntu.sources
sudo apt update

문제가 생기면 백업 파일을 되돌립니다.

sudo cp /etc/apt/sources.list.backup /etc/apt/sources.list
sudo apt update

Ubuntu 22.04 이하 또는 구형 이미지처럼 /etc/apt/sources.list를 쓰는 경우입니다.

sudo cp /etc/apt/sources.list /etc/apt/sources.list.backup
sudo sed -i 's|http://archive.ubuntu.com/ubuntu|https://mirror.kakao.com/ubuntu|g' /etc/apt/sources.list
sudo sed -i 's|http://kr.archive.ubuntu.com/ubuntu|https://mirror.kakao.com/ubuntu|g' /etc/apt/sources.list
sudo sed -i 's|http://security.ubuntu.com/ubuntu|https://mirror.kakao.com/ubuntu|g' /etc/apt/sources.list
sudo apt update

Ubuntu 24.04 계열처럼 Deb822 형식의 ubuntu.sources를 쓰는 경우입니다.

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.backup
sudo sed -i 's|http://archive.ubuntu.com/ubuntu|https://mirror.kakao.com/ubuntu|g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's|http://kr.archive.ubuntu.com/ubuntu|https://mirror.kakao.com/ubuntu|g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's|http://security.ubuntu.com/ubuntu|https://mirror.kakao.com/ubuntu|g' /etc/apt/sources.list.d/ubuntu.sources
sudo apt update

현재 어떤 저장소를 쓰는지 확인하려면 다음 명령을 사용합니다.

grep -R "URIs\\|deb " /etc/apt/sources.list /etc/apt/sources.list.d/*.sources 2>/dev/null

# 내 컴퓨터에서 키 생성
ssh-keygen -t ed25519

# 공개키를 보드에 복사
ssh-copy-id ubuntu@192.168.0.24

# 이후 비밀번호 없이 접속
ssh ubuntu@192.168.0.24

공개된 네트워크에서 비밀번호 SSH만 켜두는 것은 위험합니다. 키 기반 접속을 쓰고, 가능하면 공유기 포트포워딩 대신 VPN을 씁니다.

학교, 집, LTE 환경은 사설 IP와 방화벽 때문에 직접 접속이 어렵습니다. 개인 VPN을 쓰면 각 장치가 같은 가상 네트워크에 있는 것처럼 보이므로 포트포워딩 없이 SSH, VNC, 웹 대시보드에 접근하기 쉽습니다.

cd ~/aiot-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install opencv-python paho-mqtt numpy
pip freeze > requirements.txt

.venv는 프로젝트별 Python 패키지 상자입니다. 다른 프로젝트의 라이브러리 버전과 섞이지 않게 해 줍니다.

venv는 Python 패키지만 잘 분리합니다. 하지만 OpenCV 시스템 라이브러리, CUDA/NPU 런타임, Node.js, ffmpeg처럼 OS 패키지까지 포함하려면 Docker가 유리합니다.

# 간단한 Dockerfile 예시
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

CMD ["python", "app.py"]

docker build -t aiot-app .
docker run --rm --name aiot-app aiot-app

# I2C 도구 설치
sudo apt install -y i2c-tools

# I2C 버스에서 장치 주소 스캔
sudo i2cdetect -y 1

# USB 시리얼 장치 확인
ls /dev/ttyUSB*
ls /dev/ttyACM*

# 커널 메시지에서 새 장치 확인
dmesg | tail -50

• libgpiod 최신 리눅스 커널에서 권장되는 GPIO 제어 방식입니다. gpiodetect, gpioinfo, gpioset 같은 도구를 제공합니다.
• 보드 전용 라이브러리 Raspberry Pi의 gpiozero, 일부 SBC의 Wiring 계열 라이브러리는 교육용으로 편합니다.
• sysfs GPIO 오래된 방식입니다. 새 프로젝트에서는 가능하면 피합니다.

sudo apt install -y gpiod
gpiodetect
gpioinfo

# 비디오 장치 확인
ls /dev/video*

# USB 장치 목록
lsusb

# 카메라가 인식되는지 커널 로그 확인
dmesg | grep -i video

USB 카메라는 보통 /dev/video0로 보입니다. CSI 카메라는 보드별 설정 도구와 드라이버가 필요할 수 있습니다.

1. PC에서 모델이 원하는 입력과 출력을 내는지 먼저 확인합니다.
2. 입력 크기, 프레임률, 전처리 방식을 줄여 실시간 목표를 정합니다.
3. ONNX, TFLite, RKNN, RKLLM 등 보드가 지원하는 형식으로 변환합니다.
4. 보드에서 샘플 이미지 10장 이상으로 결과가 같은지 비교합니다.
5. 추론 시간, CPU 사용률, 메모리, 온도, 전력 소모를 기록합니다.
6. 실패 시 안전 모드로 내려가는 로직을 넣습니다.

Orange Pi 5/5 Plus/5 Pro, Radxa 계열 등 RK3588/RK3576 보드는 내장 NPU를 활용할 수 있습니다. 여기서 중요한 점은 일반 PyTorch 모델을 그대로 NPU에 올리는 것이 아니라, Rockchip 런타임이 이해하는 형식으로 변환하고 전용 서버/런타임으로 실행한다는 것입니다.

설치 흐름 예시는 아래처럼 잡으면 됩니다. 실제 명령은 보드 이미지, 커널, NPU 드라이버, rkllama 릴리스에 따라 달라질 수 있으므로 프로젝트 README와 보드 제조사 문서를 함께 확인합니다.

# 1. 보드 정보와 커널 확인
uname -a
cat /etc/os-release

# 2. NPU/드라이버 장치가 보이는지 확인
ls /dev | grep -Ei 'rknpu|npu'
dmesg | grep -Ei 'rknpu|rkllm|npu'

# 3. 기본 개발 도구 설치
sudo apt update
sudo apt install -y git cmake build-essential python3 python3-venv python3-pip

# 4. rkllama는 릴리스/README 기준으로 설치
git clone https://github.com/NotPunchnox/rkllama.git
cd rkllama
# 이후 과정은 저장소의 README에 맞춰 빌드 또는 릴리스 바이너리 설치

운영 단계에서는 rkllama를 직접 터미널에서 실행해 본 뒤, 안정적으로 동작하면 systemd 서비스로 등록합니다. 앱은 이 서버를 HTTP API로 호출하게 만들면 모델 서버와 로봇 제어 코드를 분리할 수 있습니다.

# 예시: 포트가 열렸는지 확인
ss -lntp | grep -E '8080|11434|8000'

# 예시: 서비스 로그 추적
journalctl -u rkllama -f

참고 링크: rkllama GitHub, Rockchip RKNN Toolkit2, Radxa RKLLM Installation

소형 보드에서 대형 언어 모델을 돌릴 때는 모델 크기보다 RAM, 양자화 형식, 초당 토큰 수, 발열 지속성이 중요합니다. 실습에서는 작은 모델로 명령 분류, 요약, 장치 상태 설명처럼 범위를 좁히는 편이 좋습니다.

• 대화형 챗봇보다 "센서 이상 상태를 자연어로 설명" 같은 좁은 작업이 성공률이 높습니다.
• 모델 파일은 SD카드보다 eMMC/NVMe에 두면 로딩이 안정적입니다.
• 모델 서버를 systemd로 등록하고, 앱은 HTTP API로 호출하면 교체와 재시작이 쉽습니다.

RK3588 계열은 6 TOPS급 NPU를 갖고 있어 객체 탐지, 이미지 분류, 일부 LLM 추론 실험에 적합합니다. 예전 문서에서 강조했던 것처럼, Qwen 계열 소형 모델이나 Llama 계열 경량 모델을 RKLLM 형식으로 변환한 뒤 rkllama 같은 서버로 구동하는 흐름이 핵심입니다.

• 비전 모델: PyTorch/ONNX 모델 → rknn-toolkit2 → .rknn → 보드의 RKNN Runtime에서 추론.
• LLM 모델: Hugging Face 모델 → rkllm-toolkit → .rkllm → 보드의 RKLLM Runtime 또는 rkllama에서 추론.
• 앱 연동: 로봇 제어 앱이 직접 모델을 로드하지 말고, 로컬 모델 서버에 요청을 보내는 구조가 유지보수에 좋습니다.
• 성능 판단: "실행된다"보다 초당 토큰 수, 첫 토큰 지연, 메모리 사용량, 10분 이상 연속 실행 시 온도가 중요합니다.

Radxa Cubie A7Z는 Allwinner A733 SoC와 Vivante VIP9000 계열 3 TOPS@INT8 NPU를 쓰는 보드입니다. 따라서 Rockchip 보드처럼 .rknn, .rkllm, rkllama를 쓰는 흐름이 아니라, Radxa Cubie NPU 문서의 ACUITY Toolkit → NBG(Network Binary Graph) → VIPLite/vpm_run 흐름으로 이해해야 합니다.

1. X86 Linux PC에 Docker를 설치하고 A733용 ACUITY Docker 이미지(ubuntu-npu:v2.0.10.1)를 불러옵니다.
2. 컨테이너 안에서 ai-sdk를 내려받고, A733용 환경인 source env.sh v3를 적용합니다.
3. ONNX/TFLite/Keras 같은 모델과 보정 데이터를 준비한 뒤 parse, inference, quantization 단계를 거칩니다.
4. 정확도가 낮으면 uint8만 고집하지 말고 pcq나 int16으로 다시 비교합니다.
5. pegasus_export_ovx.sh 모델폴더 양자화방식으로 내보내고, 생성된 *_nbg_unify/network_binary.nb를 확보합니다.
6. nbinfo로 입력 크기, 출력 개수, 메모리 요구량을 확인한 뒤 A7Z 보드로 .nb 파일과 입력 텐서를 복사합니다.
7. 보드에서 vpm_run을 A733 옵션으로 빌드하고, VIPLite 라이브러리 경로를 잡은 뒤 sample.txt로 추론을 실행합니다.

X86 Linux PC에서 변환 환경을 만드는 예시

# A733용 ACUITY Docker 이미지 준비
unzip docker_images_v2.0.x.zip
cd docker_images_v2.0.x
unzip ubuntu-npu_v2.0.10.1.tar.zip
sudo docker load -i ubuntu-npu_v2.0.10.1.tar

# 작업 폴더를 컨테이너 /workspace로 연결
mkdir docker_data
cd docker_data
sudo docker run --ipc=host -itd -v ${PWD}:/workspace --name allwinner_v2.0.10.1 ubuntu-npu:v2.0.10.1 /bin/bash
sudo docker exec -it allwinner_v2.0.10.1 /bin/bash

# 컨테이너 안: A733은 v3 환경 사용
git clone https://github.com/ZIFENG278/ai-sdk.git
cd ai-sdk/models
source env.sh v3
cp ../scripts/* .

# 모델별 parse/quantization 후 NBG 내보내기
pegasus_inference.sh MobileNetV2_Imagenet/ pcq
pegasus_export_ovx.sh MobileNetV2_Imagenet pcq

A7Z 보드에서 NBG를 시험하는 예시

git clone https://github.com/ZIFENG278/ai-sdk.git
cd ai-sdk/examples/vpm_run
make AI_SDK_PLATFORM=a733
make install AI_SDK_PLATFORM=a733 INSTALL_PREFIX=./

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/rock/ai-sdk/viplite-tina/lib/aarch64-none-linux-gnu/v2.0
cd ./etc/npu/vpm_run

# sample.txt에는 network_binary.nb와 입력 tensor/dat 파일 경로를 적습니다.
./vpm_run -s sample.txt -l 10 -d 1

공식 문서 출처: Radxa Cubie A7Z, Vivante NPU SDK guide, ACUITY environment, ACUITY usage, vpm_run, NBinfo, Model Zoo