ESP32 - API Reference - API Conventions

참고
ESP32 사이트의 API Conventions 문서를 한글화한다.

 

API Conventions (API 규칙)

이 문서는 ESP-IDF API(Application Programming Interfaces)에 공통적인 규칙과 가정을 설명한다.

 

ESP-IDF는 여러 종류의 프로그래밍 인터페이스를 제공한다 :

• ESP-IDF 컴포넌트의 public header 파일에는 C 함수, 구조체, enum, type 정의와 전처리 매크로가 선언되어 있다. 프로그래밍 가이드의 API Reference 섹션에 있는 다양한 페이지에는 이러한 함수, 구조체, type에 대한 설명을 포함한다.
• 시스템 함수, 미리 정의된 변수와 옵션을 빌드한다. 이는 빌드 시스템 가이드에 설명되어 있다.
• Kconfig 옵션은 코드와 빌드 시스템 파일(CMakeLists.txt)에서 사용할 수 있다.
• 호스트 툴과 해당 커맨드 라인 파라미터도 ESP-IDF 인터페이스의 일부분이다.

ESP-IDF는 third-party 라이브러리뿐만 아니라 ESP-IDF를 위해 특별히 작성된 컴포넌트로 구성된다. 어떤 경우에는 ESP-IDF 관련 래퍼가 third-party 라이브러리에 추가되어, ESP-IDF의 나머지 기능과 더 간단하거나 더 잘 통합된 인터페이스를 제공한다. 다른 경우에는 third-party 라이브러리의 오리지날 API가 애플리케이션 개발자에게 제공된다.

 

아래 섹션에는 ESP-IDF API의 양상과 사용법을 일부 설명한다.

 

Error handling (오류 처리)

대부분의 ESP-IDF API는 esp_err_t type으로 정의된 오류 코드를 반환한다. 오류 처리 접근법에 대한 자세한 내용은 Error Handing 섹션을 참조한다. Error Code Reference에는 ESP-IDF 컴포넌트에서 반환되는 오류 코드 목록이 포함되어 있다.

 

Configuration structure (구성 구조체)

중요
구성 구조체의 올바른 초기화는 ESP-IDF의 향후 버전과 애플리케이션을 호환되도록 만드는 데 중요한 부분이다.

ESP-IDF에서 초기화나 구성 함수 대부분은 구성 구조체에 대한 포인터를 인수(argument)로 사용한다. 예를 들어 :

const esp_timer_create_args_t my_timer_args = {
    .callback = &my_timer_callback,
    .arg = callback_arg,
    .name = "my_timer"
};
esp_timer_handle_t my_timer;
esp_err_t err = esp_timer_create(&my_timer_args, &my_timer);

초기화 함수는 구성 구조체에 대한 포인터를 저장하지 않으므로, 스택에 구조체를 할당하는 것이 안전하다.

 

애플리케이션은 구조체의 모든 필드를 초기화해야 한다. 아래는 올바르지 않은 예이다 :

esp_timer_create_args_t my_timer_args;
my_timer_args.callback = &my_timer_callback;
/* Incorrect! Fields .arg and .name are not initialized */
esp_timer_create(&my_timer_args, &my_timer);

ESP-IDF 예제는 구조체 초기화를 위해 대부분 C99 designated initializers(지정 초기화)를 사용한다. 필드의 서브셋을 설정하고 나머지 필드를 0으로 초기화하는 간결한 방법을 제공하기 때문이다 :

const esp_timer_create_args_t my_timer_args = {
    .callback = &my_timer_callback,
    /* Correct, fields .arg and .name are zero-initialized */
};

C++ 언어는 C++20까지 designated initializers(지정 초기화) 구문을 지원하지 않지만, GCC 컴파일러는 확장으로 이를 부분적으로 지원한다. C++ 코드에서 ESP-IDF API를 사용할 때 아래 패턴 사용을 고려할 수 있다 :

esp_timer_create_args_t my_timer_args = {};
/* All the fields are zero-initialized */
my_timer_args.callback = &my_timer_callback;

 

Default initializers (기본 초기화)

일부 구성 구조체의 경우, ESP-IDF는 필드의 기본 값을 설정하기 위한 매크로를 제공한다 :

httpd_config_t config = HTTPD_DEFAULT_CONFIG();
/* HTTPD_DEFAULT_CONFIG expands to a designated initializer.
   Now all fields are set to the default values.
   Any field can still be modified: */
config.server_port = 8081;
httpd_handle_t server;
esp_err_t err = httpd_start(&server, &config);

특정 구성 구조체가 사용될 때마다 default initializers(기본 초기화) 매크로를 사용하는 것이 권장된다.

 

Private APIs (비공개 API)

ESP-IDF의 특정 헤더 파일에는 애플리케이션이 아니라, ESP-IDF 소스 코드에서만 사용하도록 의도된 API가 포함되어 있다. 이런 헤더 파일은 이름이나 경로에 private이나 esp_private를 포함하는 경우가 많다. hal과 같은 특정 컴포넌트에는 private APIs만 포함되어 있다.

 

private APIs는 마이너나 패치 릴리즈 사이에 호환되지 않는 방식으로 제거되거나 변경될 수 있다.

 

Components in example projects (예제 프로젝트 컴포넌트)

ESP-IDF 예제는 ESP-IDF API의 사용법을 보여주는 다양한 프로젝트가 포함되어 있다. 예제에서 코드의 중복을 줄이기 위해서, 여러 예제에서 사용되는 컴포넌트 내부에 몇 가지 공통 헬퍼(helper)가 정의되어 있다. 여기에는 common_components 디렉토리에 있는 컴포넌트와 예제 자체에 있는 일부 컴포넌트가 포함된다. 이러한 컴포넌트는 ESP-IDF API의 일부로 간주되지 않는다.

 

이러한 컴포넌트는 ESP-IDF 버전 사이에서 크게 변경될 수 있으므로, 사용자 정의 프로젝트(EXTRA_COMPONENT_DIRS 빌드 시스템 변수를 통해)에서 직접 참조하지 않는 것이 좋다. ESP-IDF 예제를 기반으로 새로운 프로젝트를 시작할 때, 프로젝트와 해당 프로젝트가 의존하는 공통 컴포넌트를 ESP-IDF 외부에서 복사하고 공통 컴포넌트를 프로젝트의 일부로 취급한다. 공통 컴포넌트는 예제를 염두에 두고 작성되었으며, 제품용 애플리케이션에 필요한 모든 오류 처리가 포함되지 않을 수 있다. 시간을 내어 코드를 분석하고 사용할 사례에 응용 가능한지 판단해야 한다.

 

API Stability (API 안전성)

ESP-IDF는 버전 페이지에 설명된 대로 Semantic Versioning을 사용한다.

 

ESP-IDF의 마이너와 버그 수정(bugfix) 릴리즈는 이전 릴리즈와 호환성을 보장한다. 아래 섹션에서는 호환성에 대한 다양한 관점과 제한 사항을 설명한다.

 

Source level compatibility

ESP-IDF 컴포넌트의 공개 헤더 파일에 선언된 C 함수, 구조체, 열거형(enum), type 정의와 전처리기 매크로의 소스 레벨 호환성을 ESP-IDF는 보장한다. 소스 레벨 호환성은 애플리케이션이 수정 없이 최신 버전의 ESP-IDF로 다시 컴파일될 수 있음을 의미한다.

 

마이너 버전 사이에 아래 변경이 하용되며, 소스 레벨 호환성을 손상시키지 않는다 :

• 더 이상 사용되지 않는 함수(deprecated 속성을 사용)와 헤더 파일(전처리기 #warning을 사용). ESP-IDF 릴리즈 노트에 더 이상 사용되지 않는 함수와 헤더 파일이 나열되어 있다. 이를 대체하는 새로운 함수나 파일을 사용하도록 소스 코드를 업데이트하는 것이 좋지만 필수 사항은 아니다. 사용되지 않는 함수와 파일은 ESP-IDF 메이저 버전에서 제거할 수 있다.
• 컴포넌트 이름 변경, 컴포넌트 사이에 소스와 헤더 파일 이동 - 빌드 시스템에서 올바른 파일을 여전히 찾을 수 있도록 보장한다.
• Kconfig 옵션 이름 변경. Kconfig 시스템 이름 변경 메커니즘은 오리지널 Kconfig 옵션 이름이 sdkconfig 파일, CMake 파일과 소스 코드에서 애플리케이션에 의해 여전히 사용될 수 있도록 한다.

 

Lack of binary compatibility

ESP-IDF는 릴리즈 사이에 바이너리 호환성을 보장하지 않는다. 즉, 미리 컴파일된 라이브러리가 하나의 ESP-IDF 버전으로 빌드된 경우, 다음 마이너나 버그 수정(bugfix) 릴리즈에서 동일한 방식으로 작동하지 않을 수 있다. 아래는 소스 레벨 호환성은 유지하지만 바이너리 호환성은 유지하지 않는 가능한 수정 사항이다 :

• C enum 멤버의 숫자 값 변경.
• 구조체에 새로운 멤버를 추가하거나 멤버의 순서를 변경.  호환성을 보장하는 데 도움이 되는 팁은 구조체 구성을 참조한다.
• extern 함수를 동일한 signature를 가진 static inline 함수로 교체하거나 그 반대의 경우도 마찬가지이다.
• 함수형 매크로를 C 함수로 교체.

 

Other exceptions from compatibility

새로운 ESP-IDF 버전으로 쉽게 업그레이드할 수 있도록 노력하고 있지만, 일부 ESP-IDF가 마이너 버전 사이에 호환되지 않는 방식으로 변경될 수 있다. 아래 범주에 속하지 않는 의도하지 않은 주요 변경 사항에 대한 이슈 리포트를 우리는 고맙게 생각한다.

• Private APIs
• 예제 프로젝트의 컴포넌트
• "beta", "preview"나 "experimental"로 명확하게 표시된 기능
• 보안 문제를 완화하거나 안전하지 않은 기본 동작을 안전한 동작으로 대체하기 위한 변경 사항
• 결코 작동하지 않는 기능. 예를 들어, 특정 함수나 열거형 값을 사용할 수 없는 경우에 (수정의 일부로) 이름이 변경되거나 제거될 수 있다. 여기에는 함수가 아닌 하드웨어 칩 기능에 의존하는 소프트웨어 기능이 포함된다.
• 명시적으로 문서화되지 않은 예기치 않거나 정의되지 않은 동작(예: 인수 범위의 유효성 검사 누락으로 인해)은 수정/변경될 수 있다.
• menuconfig에서 Kconfig 옵션의 위치
• 예제 프로젝트의 위치와 이름

 

NEXT : Application Protocols