NT98331 DVR/NVR SDK
한국어 가이드북

Novatek NT98331/NT98332 기반
DVR/NVR 시스템 개발 완전 가이드

버전: 1.0

작성일: 2024년

1. 소개

1.1 NT98331 DVR/NVR SDK 개요

NT98331 DVR/NVR SDK는 Novatek의 NT98331/NT98332 칩셋을 기반으로 하는 디지털 비디오 레코더(DVR) 및 네트워크 비디오 레코더(NVR) 시스템 개발을 위한 소프트웨어 개발 키트입니다.

이 SDK는 다음과 같은 주요 특징을 제공합니다:

Linux 기반 개발 환경
크로스 컴파일 지원 (glibc/uclibc)
HDAL (Hardware Device Abstraction Layer) API
실시간 영상 처리 및 스트리밍
다양한 코덱 지원 (H.264, H.265, JPEG)
다채널 영상 입출력

1.2 지원 플랫폼

본 SDK는 다음 칩셋을 지원합니다:

NT98331
NT98332

1.3 시스템 요구사항

1.3.1 하드웨어 요구사항

개발용 PC: Intel/AMD x64 프로세서
RAM: 최소 4GB (권장 8GB 이상)
저장 공간: 최소 20GB 이상의 여유 공간
NT98331/NT98332 개발 보드

1.3.2 소프트웨어 요구사항

운영체제: Ubuntu 18.04 LTS 이상 (권장)
기타 Linux 배포판도 지원 가능
GNU Make 4.0 이상
Git

2. 개발 환경 개요

2.1 SDK 패키지 구성

NT98331 DVR/NVR SDK는 다음과 같은 디렉터리 구조로 구성됩니다:

NT98331_DVR_NVR_SDK/
├── Hardware/              # 하드웨어 관련 문서 및 회로도
├── Document/              # 기술 문서
├── Chip/                  # 칩셋별 소스코드
├── Software/              # 소프트웨어 소스 및 도구
├── PC_Tool/               # PC용 개발 도구
└── Disclaimer/            # 라이센스 및 법적 고지사항

2.2 개발 환경 설정

효율적인 개발을 위해 다음과 같은 개발 환경을 권장합니다:

2.3.1 Linux 개발 환경

Ubuntu 18.04 LTS 이상에서 개발하는 것을 강력히 권장합니다. 다른 Linux 배포판도 사용 가능하지만, 의존성 문제나 호환성 이슈가 발생할 수 있습니다.

2.3.2 필수 패키지 설치

sudo apt update
sudo apt install build-essential git wget curl
sudo apt install libncurses5-dev libssl-dev
sudo apt install device-tree-compiler u-boot-tools

2.3 하드웨어 연결

2.3.1 개발 보드 연결

NT98331/NT98332 개발 보드를 PC에 연결하기 위해 다음 인터페이스를 사용합니다:

UART: 시리얼 콘솔 접근용
USB OTG: 펌웨어 업로드 및 디버깅용
HDMI: 비디오 출력 확인용
Ethernet: 네트워크 연결용

주의사항: 개발 보드의 점퍼 설정이 올바른지 확인하십시오. 잘못된 설정은 부팅 실패의 원인이 될 수 있습니다.

3. 환경 구축 및 설치

3.1 SDK 압축 해제

제공받은 SDK 압축 파일을 적절한 위치에 압축 해제합니다:

cd /opt
sudo tar -xzf NT98331_DVR_NVR_SDK.tar.gz
sudo chown -R $USER:$USER NT98331_DVR_NVR_SDK

3.2 크로스 컴파일러 설치

NT98331 SDK는 두 가지 툴체인을 지원합니다:

3.2.1 glibc 툴체인

표준 glibc 라이브러리를 사용하는 툴체인으로, 더 많은 기능을 제공하지만 바이너리 크기가 큽니다.

3.2.2 uclibc 툴체인

임베디드 시스템에 최적화된 경량 C 라이브러리를 사용하는 툴체인입니다. 메모리가 제한된 환경에서 유리합니다.

3.3 환경 변수 설정

개발 환경을 설정하기 위해 환경 설정 스크립트를 실행합니다:

cd /opt/NT98331_DVR_NVR_SDK
source envsetup.sh

이 스크립트는 다음과 같은 환경 변수를 설정합니다:

PATH: 크로스 컴파일러 경로
CROSS_COMPILE: 크로스 컴파일러 접두사
ARCH: 타겟 아키텍처

3.4 프로젝트 선택

lunch 명령을 통해 빌드할 프로젝트와 툴체인을 선택합니다:

lunch

메뉴에서 적절한 옵션을 선택합니다:

NT98331_glibc - glibc 툴체인 사용
NT98331_uclibc - uclibc 툴체인 사용
NT98332_glibc - NT98332용 glibc 툴체인
NT98332_uclibc - NT98332용 uclibc 툴체인

4. 빌드 시스템

4.1 전체 시스템 빌드

전체 시스템을 빌드하려면 다음 명령을 사용합니다:

make all

이 명령은 다음 구성 요소를 순차적으로 빌드합니다:

U-Boot 부트로더
Linux 커널
루트 파일시스템
애플리케이션

4.2 개별 구성 요소 빌드

4.2.1 U-Boot 빌드

make uboot

4.2.2 Linux 커널 빌드

make linux

4.2.3 루트 파일시스템 빌드

make rootfs

4.2.4 애플리케이션 빌드

make app

4.3 빌드 결과물

빌드 완료 후 output 디렉터리에 다음 파일들이 생성됩니다:

파일명	설명	용도
u-boot.bin	U-Boot 부트로더	시스템 부팅
uImage	Linux 커널 이미지	운영체제 커널
rootfs.ubifs	루트 파일시스템	기본 시스템 파일
app.ubifs	애플리케이션 파일시스템	사용자 애플리케이션

4.4 펌웨어 업그레이드

빌드된 이미지를 개발 보드에 업로드하기 위해 FwUpgrade.exe 도구를 사용합니다:

개발 보드를 다운로드 모드로 부팅
USB OTG 케이블로 PC와 연결
FwUpgrade.exe 실행
파티션 파일 선택 및 업로드

주의: 펌웨어 업그레이드 중에는 전원을 끄거나 케이블을 분리하지 마십시오. 시스템이 복구 불가능한 상태가 될 수 있습니다.

5. 부팅 시퀀스

5.1 부팅 과정 개요

NT98331 시스템의 부팅 과정은 다음과 같은 단계로 진행됩니다:

ROM 코드 실행: 칩 내장 ROM에서 초기 부팅 코드 실행
Loader 실행: 첫 번째 단계 부트로더 로드
U-Boot 실행: 두 번째 단계 부트로더 실행
Linux 커널 부팅: 운영체제 커널 로드 및 실행
vg_boot.sh 실행: 시스템 초기화 스크립트 실행
module_init 실행: 하드웨어 모듈 초기화

5.2 vg_boot.sh 스크립트

vg_boot.sh 스크립트는 시스템 부팅 시 자동으로 실행되며 다음 작업을 수행합니다:

커널 모듈 동적 로드 (insmod)
시스템 로그 설정
환경 변수 설정
디바이스 노드 생성
module_init 프로그램 실행

5.2.1 주요 커널 모듈

다음과 같은 커널 모듈들이 부팅 시 로드됩니다:

nvt_ipc.ko: Inter-Process Communication
nvt_ivot.ko: Input/Output Transport
nvt_vdec.ko: Video Decoder
nvt_venc.ko: Video Encoder
nvt_audio.ko: Audio Processing

5.3 module_init 프로그램

module_init.c는 시스템 초기화의 마지막 단계에서 실행되며 다음 기능을 담당합니다:

5.3.1 메모리 풀 관리

시스템에서 사용할 메모리 영역을 설정하고 관리합니다. 이는 비디오 처리를 위한 대용량 버퍼 할당에 중요합니다.

5.3.2 외부 장치 초기화

다음과 같은 외부 장치들을 초기화합니다:

비디오 입력 센서
비디오 출력 장치
오디오 코덱
네트워크 인터페이스

5.3.3 채널 등록 및 관리

비디오 입력 및 출력 채널을 시스템에 등록하고, 각 채널의 상태를 모니터링합니다.

6. HDAL (Hardware Device Abstraction Layer)

6.1 HDAL 개념

HDAL(Hardware Device Abstraction Layer)은 하드웨어 종속성을 제거하고 일관된 API를 제공하는 추상화 계층입니다.

6.1.1 기존 HAL 대비 장점

칩 독립성: 다양한 칩셋에서 동일한 API 사용 가능
이식성 향상: 미들웨어의 하드웨어 이식성 증대
개발 효율성: 공통 헤더 파일만으로 개발 가능
유지보수성: 하드웨어 변경 시 최소한의 코드 수정

6.2 HDAL 모듈 구조

HDAL은 크게 두 가지 종류의 모듈로 구분됩니다:

6.2.1 스트리밍 모듈

실시간 데이터 스트림 처리를 담당하는 모듈들:

HD_VIDEOCAP: 비디오 캡처
HD_VIDEOPROC: 비디오 처리 (VPE)
HD_VIDEOENC: 비디오 인코딩
HD_VIDEODEC: 비디오 디코딩
HD_VIDEOOUT: 비디오 출력
HD_AUDIOCAP: 오디오 캡처
HD_AUDIOENC: 오디오 인코딩
HD_AUDIODEC: 오디오 디코딩
HD_AUDIOOUT: 오디오 출력

6.2.2 유틸리티 모듈

보조 기능을 제공하는 모듈들:

HD_GFX: 그래픽 처리
HD_OSG: On-Screen Graphics
HD_DEBUG: 디버그 지원
HD_LOGGER: 로그 관리

6.3 공통 API 구조

모든 HDAL 모듈은 다음과 같은 공통 API 패턴을 따릅니다:

6.3.1 기본 API

함수	설명	사용 시점
hd_xxx_init()	모듈 초기화	프로그램 시작 시
hd_xxx_uninit()	모듈 해제	프로그램 종료 시
hd_xxx_open()	디바이스 열기	사용 전
hd_xxx_close()	디바이스 닫기	사용 완료 후
hd_xxx_bind()	모듈 간 연결	데이터 플로우 구성
hd_xxx_unbind()	모듈 간 연결 해제	플로우 변경 시

6.3.2 설정 API

함수	설명	용도
hd_xxx_set()	설정값 변경	런타임 설정 변경
hd_xxx_get()	설정값 조회	현재 상태 확인

6.3.3 데이터 처리 API

함수	설명	용도
hd_xxx_start()	데이터 처리 시작	스트림 시작
hd_xxx_stop()	데이터 처리 중지	스트림 중지
hd_xxx_recv()	데이터 수신	결과 데이터 획득
hd_xxx_release()	데이터 반환	메모리 해제

7. 예제 코드 및 실습

7.1 기본 인코딩 예제

비디오 캡처에서 인코딩까지의 기본적인 데이터 플로우를 구현하는 예제입니다.

7.1.1 데이터 플로우

Video Sensor → HD_VIDEOCAP → HD_VIDEOENC → Bitstream Output

7.1.2 코드 구조

#include "hd_type.h"
#include "hd_videocap.h"
#include "hd_videoenc.h"

int main(void)
{
    HD_RESULT ret;
    HD_PATH_ID videocap_path, videoenc_path;
    HD_VIDEOCAP_DEV_CONFIG videocap_config;
    HD_VIDEOENC_DEV_CONFIG videoenc_config;
    
    // 1. 모듈 초기화
    ret = hd_videocap_init();
    if (ret != HD_OK) {
        printf("videocap init failed\n");
        return -1;
    }
    
    ret = hd_videoenc_init();
    if (ret != HD_OK) {
        printf("videoenc init failed\n");
        return -1;
    }
    
    // 2. 디바이스 열기
    ret = hd_videocap_open(0, HD_VIDEOCAP_0_OUT, &videocap_path);
    if (ret != HD_OK) {
        printf("videocap open failed\n");
        return -1;
    }
    
    ret = hd_videoenc_open(0, HD_VIDEOENC_0_OUT, &videoenc_path);
    if (ret != HD_OK) {
        printf("videoenc open failed\n");
        return -1;
    }
    
    // 3. 디바이스 설정
    videocap_config.sensor_id = 0;
    videocap_config.width = 1920;
    videocap_config.height = 1080;
    videocap_config.frame_rate = 30;
    ret = hd_videocap_set(videocap_path, HD_VIDEOCAP_PARAM_DEV_CONFIG, &videocap_config);
    
    videoenc_config.codec = HD_CODEC_TYPE_H264;
    videoenc_config.bitrate = 4000000; // 4Mbps
    ret = hd_videoenc_set(videoenc_path, HD_VIDEOENC_PARAM_DEV_CONFIG, &videoenc_config);
    
    // 4. 모듈 간 연결 (바인딩)
    ret = hd_videocap_bind(HD_VIDEOCAP_0_OUT, videoenc_path);
    if (ret != HD_OK) {
        printf("bind failed\n");
        return -1;
    }
    
    // 5. 스트리밍 시작
    ret = hd_videocap_start(videocap_path);
    ret = hd_videoenc_start(videoenc_path);
    
    // 6. 인코딩된 데이터 수신 루프
    while (running) {
        HD_VIDEO_FRAME frame;
        ret = hd_videoenc_recv(videoenc_path, &frame, 1000); // 1초 타임아웃
        if (ret == HD_OK) {
            // 인코딩된 프레임 처리
            process_encoded_frame(&frame);
            
            // 프레임 반환
            hd_videoenc_release(videoenc_path, &frame);
        }
    }
    
    // 7. 정리 작업
    hd_videocap_stop(videocap_path);
    hd_videoenc_stop(videoenc_path);
    hd_videocap_unbind(HD_VIDEOCAP_0_OUT);
    hd_videocap_close(videocap_path);
    hd_videoenc_close(videoenc_path);
    hd_videocap_uninit();
    hd_videoenc_uninit();
    
    return 0;
}

7.2 라이브뷰 예제

캡처한 비디오를 실시간으로 화면에 출력하는 라이브뷰 기능을 구현합니다.

7.2.1 데이터 플로우

Video Sensor → HD_VIDEOCAP → HD_VIDEOPROC → HD_VIDEOOUT → Display
                                  ↓
                              HD_OSG (OSD 오버레이)

7.2.2 주요 기능

1분할/4분할 화면 지원
OSD (On-Screen Display) 오버레이
실시간 화면 크기 조정
다중 채널 동시 표시

7.3 재생 예제

녹화된 비디오 파일을 디코딩하여 재생하는 기능을 구현합니다.

7.3.1 데이터 플로우

Video File → HD_DATAIN → HD_VIDEODEC → HD_VIDEOPROC → HD_VIDEOOUT → Display

7.3.2 지원 기능

H.264/H.265 비디오 디코딩
재생 속도 조절 (1x, 2x, 4x 등)
프레임별 재생 (Step)
구간 반복 재생
JPEG 스냅샷 기능

7.4 고급 기능 예제

7.4.1 노이즈 제거 (Noise Reduction)

비디오 품질 향상을 위한 노이즈 제거 기능:

// 노이즈 제거 설정
HD_VIDEOPROC_NR nr_config;
nr_config.enable = TRUE;
nr_config.strength = 50; // 0-100 범위
hd_videoproc_set(videoproc_path, HD_VIDEOPROC_PARAM_NR, &nr_config);

7.4.2 프라이버시 마스크

특정 영역을 마스킹하여 프라이버시를 보호하는 기능:

// 프라이버시 마스크 설정
HD_VIDEOPROC_MASK mask_config;
mask_config.enable = TRUE;
mask_config.x = 100;
mask_config.y = 100;
mask_config.width = 200;
mask_config.height = 150;
mask_config.color = 0x000000; // 검은색
hd_videoproc_set(videoproc_path, HD_VIDEOPROC_PARAM_MASK, &mask_config);

7.4.3 움직임 감지

영상에서 움직임을 감지하는 기능:

// 움직임 감지 설정
HD_VIDEOCAP_MD md_config;
md_config.enable = TRUE;
md_config.sensitivity = 80; // 민감도
md_config.threshold = 10;   // 임계값
hd_videocap_set(videocap_path, HD_VIDEOCAP_PARAM_MD, &md_config);

8. 트러블슈팅

8.1 빌드 관련 문제

8.1.1 크로스 컴파일러 경로 문제

증상: "cross compiler not found" 오류 발생

해결방법:

envsetup.sh 스크립트가 정상 실행되었는지 확인
PATH 환경변수에 크로스 컴파일러 경로가 포함되어 있는지 확인
lunch 명령으로 적절한 타겟을 선택했는지 확인

8.1.2 의존성 패키지 누락

증상: 빌드 중 헤더 파일 또는 라이브러리를 찾을 수 없음

해결방법:

# Ubuntu/Debian에서 필수 패키지 설치
sudo apt install build-essential libncurses5-dev
sudo apt install device-tree-compiler u-boot-tools

8.2 부팅 관련 문제

8.2.1 부팅 실패

증상: 시스템이 정상적으로 부팅되지 않음

확인사항:

하드웨어 점퍼 설정이 올바른지 확인
전원 공급이 안정적인지 확인
부트로더가 정상적으로 플래시되었는지 확인
시리얼 콘솔을 통해 부팅 로그 확인

8.2.2 커널 패닉

증상: 커널 로딩 중 패닉 발생

해결방법:

메모리 설정을 확인 (nvt-mem-tbl.dtsi)
디바이스 트리 설정을 점검
커널 설정을 재검토

8.3 HDAL API 관련 문제

8.3.1 모듈 초기화 실패

증상: hd_xxx_init() 함수에서 오류 반환

해결방법:

커널 모듈이 정상적으로 로드되었는지 확인
디바이스 노드가 생성되었는지 확인
권한 설정이 올바른지 확인

8.3.2 바인딩 오류

증상: hd_xxx_bind() 함수에서 실패

해결방법:

연결할 모듈들이 모두 열려있는지 확인
호환되는 데이터 형식인지 확인
이미 연결된 경로가 아닌지 확인

8.4 성능 최적화

8.4.1 메모리 부족

증상: 메모리 할당 실패 또는 성능 저하

해결방법:

메모리 풀 크기 조정
불필요한 기능 비활성화
버퍼 크기 최적화

8.4.2 프레임 드롭

증상: 영상이 끊어지거나 프레임이 누락됨

해결방법:

처리 속도와 입력 속도 균형 맞추기
버퍼링 정책 조정
CPU 부하 분산

8.5 디버깅 도구

8.5.1 로그 분석

시스템 로그를 통해 문제를 진단합니다:

# 시스템 로그 확인
dmesg | tail -50

# 특정 모듈 로그 확인
cat /proc/nvt_logs/videocap

8.5.2 성능 모니터링

# CPU 사용률 확인
top

# 메모리 사용량 확인
free -m

# 프로세스별 리소스 사용량
ps aux | grep hd_

9. 참고자료

9.1 관련 문서

NT98331 Hardware Reference Manual
HDAL API Reference Guide
Video Processing Engine User Guide
Audio Codec Programming Guide

9.2 예제 코드 위치

SDK에 포함된 예제 코드들은 다음 경로에서 확인할 수 있습니다:

NT98331_DVR_NVR_SDK/Software/samples/
├── encode/
│   ├── encode_with_nr.c
│   ├── encode_with_osg.c
│   └── encode_with_mask.c
├── liveview/
│   └── liveview_1div_to_4div.c
├── playback/
│   └── playback_1div_to_4div.c
└── display/
    └── display_to_encode.c

9.3 개발 도구

FwUpgrade.exe: 펌웨어 업그레이드 도구
SerialConsole: 시리얼 콘솔 접속 도구
NetworkConfig: 네트워크 설정 도구

9.4 지원 채널

기술 지원: support@novatek.com
개발자 포럼: forum.novatek.com
문서 업데이트: docs.novatek.com

면책조항: 본 문서는 NT98331 DVR/NVR SDK의 이해를 돕기 위한 가이드로, 실제 개발 시에는 공식 문서와 API 참조서를 함께 참고하시기 바랍니다.

- 문서 끝 -

NT98331 DVR/NVR SDK한국어 가이드북

목차

1. 소개

1.1 NT98331 DVR/NVR SDK 개요

1.2 지원 플랫폼

1.3 시스템 요구사항

1.3.1 하드웨어 요구사항

1.3.2 소프트웨어 요구사항

2. 개발 환경 개요

2.1 SDK 패키지 구성

2.2 개발 환경 설정

2.3.1 Linux 개발 환경

2.3.2 필수 패키지 설치

2.3 하드웨어 연결

2.3.1 개발 보드 연결

3. 환경 구축 및 설치

3.1 SDK 압축 해제

3.2 크로스 컴파일러 설치

3.2.1 glibc 툴체인

3.2.2 uclibc 툴체인

3.3 환경 변수 설정

3.4 프로젝트 선택

4. 빌드 시스템

4.1 전체 시스템 빌드

4.2 개별 구성 요소 빌드

4.2.1 U-Boot 빌드

4.2.2 Linux 커널 빌드

4.2.3 루트 파일시스템 빌드

4.2.4 애플리케이션 빌드

4.3 빌드 결과물

4.4 펌웨어 업그레이드

5. 부팅 시퀀스

5.1 부팅 과정 개요

5.2 vg_boot.sh 스크립트

5.2.1 주요 커널 모듈

5.3 module_init 프로그램

5.3.1 메모리 풀 관리

5.3.2 외부 장치 초기화

5.3.3 채널 등록 및 관리

6. HDAL (Hardware Device Abstraction Layer)

6.1 HDAL 개념

6.1.1 기존 HAL 대비 장점

6.2 HDAL 모듈 구조

6.2.1 스트리밍 모듈

6.2.2 유틸리티 모듈

6.3 공통 API 구조

6.3.1 기본 API

6.3.2 설정 API

6.3.3 데이터 처리 API

7. 예제 코드 및 실습

7.1 기본 인코딩 예제

7.1.1 데이터 플로우

7.1.2 코드 구조

7.2 라이브뷰 예제

7.2.1 데이터 플로우

7.2.2 주요 기능

7.3 재생 예제

7.3.1 데이터 플로우

7.3.2 지원 기능

7.4 고급 기능 예제

7.4.1 노이즈 제거 (Noise Reduction)

7.4.2 프라이버시 마스크

7.4.3 움직임 감지

8. 트러블슈팅

8.1 빌드 관련 문제

8.1.1 크로스 컴파일러 경로 문제

8.1.2 의존성 패키지 누락

8.2 부팅 관련 문제

8.2.1 부팅 실패

8.2.2 커널 패닉

8.3 HDAL API 관련 문제

8.3.1 모듈 초기화 실패

8.3.2 바인딩 오류

8.4 성능 최적화

8.4.1 메모리 부족

8.4.2 프레임 드롭

8.5 디버깅 도구

8.5.1 로그 분석

8.5.2 성능 모니터링

9. 참고자료

NT98331 DVR/NVR SDK
한국어 가이드북