6/22/2021

ESP32 BT(Bluetooth) Host Stack 정리

1. BT의 Host Stack 구조 

BT의 Host Stack과 Profile의 전부 파악하기 힘들므로, 각각의 기능에 따라 분리하여 각 항목별로 Stack 구조파악을 하자.

ESP32 BT Stack 동작과 비교 


1.1 BT Audio기반 Stack 구조

  • Bluetooth Classic Stack
  1. Profiles: GAP, A2DP(SNK), AVRCP(CT)
  2. Protocols: L2CAP, SDP, AVDTP, AVCTP 
Bluetooth의 경우 중요한것은 Profile들이며, 대부분 Protocol들이 지원하므로, 관련부분은 참조만 하자.
더불어 Profile의 지원여부들을 확인하자.
https://www.espressif.com/sites/default/files/documentation/esp32_bluetooth_architecture_en.pdf


  • L2CAP(Logical Link Control and Adaptation Protocol)
OSI Layer 2 계층이며, Packet 재전송과 Flow Control 이외 Packet 분할과 재조립부터 다양한 기능들을 제공해주고 있으며, 상위 Protocol Multiplexing 도 제공 
  1. Basic L2CAP Mode
  2. Flow Control Mode
  3. Retransmission Mode
  4. Enhanced Retransmission Mode
  5. Streaming Mode
  6. LE Credit-Based Flow Control Mode

  • SDP(Service Discovery Protocol)
L2CAP기반에 주 역할은 상대의 Service를 찾는것이며, Server 와 Client형태로 구성이되어 Server는 각 Service들을 유지하고 있다.

  • GAP(General Access Profile) 
GAP의 경우, description의 mode와 device discoverability, connection and security 의 절차를 제공한다고 한다.
GAP의 경우 기본으로 사용되므로 사용방법을 알아두며, GATT를 사용시에도 사용되므로 중요.

  • A2DP (Advanced Audio Distribution Profile)
BT에서 Audio를 사용한다면, A2DP일 것이며, ACL Channel를 통해 제공하며, SRC -> SINK형태로 Audio를 제공 

AVRCP(Audio/Video Remote Control Profile)를 보면 대충 Remocon 기능으로 동작될 것 같으며, CT(Controller) 와 TG(Target)으로 동작되어진다고 한다.

https://www.espressif.com/sites/default/files/documentation/esp32_bluetooth_architecture_en.pdf


1.2 BT의 GAP/GATT 기반의 Stack 구조 


GAP(General Access Profile)
GATT(Generic Attribute Profile) 
ATT(Attribute Protocol)
SM(Security Manager)
L2CAP(Logical Link Control and Adaption Protocol)


https://smartits.tistory.com/18?category=693936


https://igotit.tistory.com/entry/BLE-Protocol-Stack-Bluetooth-Low-Energy



  • BLE의 GAP(General Access Profile)
BLE와 BT에서 GAP의 동작이 다르지는 않을 것이라고 생각되지만, 일단 아래의 BLE기반이라고 하므로 추후에 비교분석을 별도로 해야함

  • BLE의 GAP의 역할 
  1. Broadcaster : Advertising Packet을 보내는 역할로 Observer가 이를 찾아주길 바란다.
  2. Observer: Broadcaster의 정보를 찾고 App에게 이를 보고는하지만 연결은 못함
  3. Peripheral: connectable advertising packets 이용하여 advertise하고 연결가능하며 slave로 연결동작 
  4. Central: Peripheral과 연결가능하며, Master로 동작 

GAP의 Status이며, GATT를 연결하여 동작하면 쉽게 이해할 수 있다. 

  • Device-A 에서는 GAP 기반의 GATT Server 의 동작  
  1. BT Device-A(미밴드) Advertising Packet를 보내 다른 BT Device-B(핸드폰)들이 발견해주기를 바란다.
  2. BT Device-A는 GATT Server를 동작하고 있으며, BT Device-B가 Peripheral(Slave)연결가능하며 연결진행 
  3. 연결된 후 BT Device-A는 GATT Server로 Master(Central)로 동작 


  • GAP의 상태로 상위에서 Slave 와 Master까지 표시 

http://software-dl.ti.com/lprf/simplelink_cc2640r2_sdk/1.35.00.33/exports/docs/ble5stack/ble_user_guide/html/ble-stack/gap.html


핸드폰(Client)에서 Device(Server)로 연결한 후 각 Characteristic 값들을 변경하여 반영한다.
아래는 단방향이지만, 양방향으로 가능 (Notify Server-> Client)



2.  BT의 Stack 의 동작 및 구현정보

현재 Audio 관련부분은 경험이 없으므로, 생략하며, GAP 과 GATT Service기반으로 간단히 설명하고 정리한다.


2.1 GGS(GAP GATT Service) 동작 및 확인

Device에서 GATT Server로 Service를 구현하여, 핸드폰에서 이 Device를 발견하고 연결한 후 Characteristic Value를 변경한다.

  

  • GATT(General Attribute Profile) Client

http://software-dl.ti.com/lprf/simplelink_cc2640r2_sdk/1.35.00.33/exports/docs/ble5stack/ble_user_guide/html/ble-stack/gatt.html#gap-gatt-service-ggs


  • GATT Client-> Server 연결 후 Server 값들 확인 
아래의 16bite UUID의 값은 역할이 정해져 있으므로, 각 값은 반드시 정확한 의미를 알고 사용해야한다.

    Type             UUID       Allocated for 
//GATT Service 등록시 Primary or Secondary Service 설정 
//Service 등록되면 Characteristic 설정하여 값 이름 과 값 설정 등등
GATT Declarations 0x2800   Primary Service
GATT Declarations 0x2801   Secondary Service
GATT Declarations 0x2802   Include
GATT Declarations 0x2803   Characteristic

//설명으로 옵션으로 설정
GATT Descriptor 0x2900 Characteristic Extended Properties
GATT Descriptor 0x2901 Characteristic User Description
GATT Descriptor 0x2902 Client Characteristic Configuration
GATT Descriptor 0x2903 Server Characteristic Configuration
GATT Descriptor 0x2904 Characteristic Presentation Format
GATT Descriptor 0x2905 Characteristic Aggregate Format
GATT Descriptor 0x2906 Valid Range
GATT Descriptor 0x2907 External Report Reference
GATT Descriptor 0x2908 Report Reference
GATT Descriptor 0x2909 Number of Digitals
GATT Descriptor 0x290A Value Trigger Setting

//GATT 기본서비스로 Device Name 설정 및 기타기능설정 
GATT Service 0x1800 Generic Access

//GATT 기본서비스 속성으로 Service 동작방식제어
GATT Service 0x1801 Generic Attribute

// Device Information Service로 아래에 있는 것처럼 Device 관련된 정보출력
GATT Service 0x180A Device Information

// Heart Rate Service (Notify를 이용하여 각 정보제공)
GATT Service 0x180D Heart Rate

// Battery Service 
GATT Service 0x180F Battery

BT관련정보들 


** 주의해야할 것은 Handle 과 UUID를 혼동하지말자.
http://software-dl.ti.com/lprf/simplelink_cc2640r2_sdk/1.35.00.33/exports/docs/ble5stack/ble_user_guide/html/ble-stack/gatt.html#gap-gatt-service-ggs


UUID의 경우 16bit 이외에도 128bit 생성하여 Custom UUID로 사용가능하며, 이 값도 설정가능 


  • GATT Service 구현시 
  1. ATT(Attribute Protocol):  Server or Client 설정 및 각 Type 과 권한설정 
  2. GATT(General Attribute Profile) : 아래 기능들을 설정하여 구현 
    1. Services:  Server에서 동작할 Service ( Service UUID 찾기)
    2. Characteristics: Service에서 사용되는 값 정의  및 설정 등 (Char UUID 찾기)
    3. Descriptor: 관련설명 명시 

https://www.novelbits.io/bluetooth-gatt-services-characteristics/

  • GAP/GATT Service에서 가장 기본예제 (Heart Rate)
아래 사이트를 찾아봐도 쉽게 다양한 자료를 검색가능하며,  핸드폰으로 Device의 GATT Server로 접속하여 Hear Rate 정보를 받는다.


https://www.cypress.com/file/179851/download


  • BLE GATT(Generic Attribute Profile) 구현 및 테스트 예제 
아래의 사이트가 가장도움이 되었으며, 쉽게 Android에서 nRF Connect를 이용하여 테스트가 가능하였다.

아래사이트 반드시 참조


  • GATT의 Device Info or Battery Service 구현할 경우 예제 
각 필요한 GATT의 Profile 내부에서 사용되는 Service확인 
  1. GATT 사용될 Service의 UUID
  2. 상위 Service의 Characteristics의 UUID를 찾아 정의하고 값 설정 
  3. Description도 필요하다면 설정 

/* Device Information Service UUID */
#define GATT_DEVICE_INFO_UUID                   0x180A

/* Device Information Service's Characteristics  */
#define GATT_MANUFACTURER_NAME_UUID             0x2A29
#define GATT_MODEL_NUMBER_UUID                  0x2A24
#define GATT_SERIAL_NUMBER_UUID                 0x2A25
#define GATT_HARDWARE_REVISION_UUID             0x2A27
#define GATT_FIRMWARE_REVISION_UUID             0x2A26
/* Heart-rate configuration  Service */ 
#define GATT_HRS_UUID                           0x180D

/* Heart-rate configuration 's Characteristics  */ 
#define GATT_HRS_MEASUREMENT_UUID               0x2A37
#define GATT_HRS_BODY_SENSOR_LOC_UUID           0x2A38
/* Battery Service UUID */
#define GATT_BATTERY_SERVICE_UUID               0x180F

/*  Battery Service 's Characteristics  */ 
#define GATT_BATTERY_LEVEL_UUID                 0x2A19
//#define GATT_BATTERY_LEVEL_STATE_UUID           0x2A1B
//#define GATT_BATTERY_POWER_STATE_UUID           0x2A1A
 
구현하고자 하는 Service의 Spec을 아래에서 찾은 후 확인

3.  ESP32 OS 관련정보 

ESP32 기본개발환경은 expressif가 제공을 해주고 있으며, VSCode로 연결하여 Download도 가능하다.
기본으로 FreeRTOS를 사용하고 있으며, 많은 예제를 제공을 해주고 있다. 

  • ESP32 개발환경 문서 
  • ESP32 개발환경소스 


3.1 AWS FreeRTOS

AWS FreeRTOS는 AWS가 주관으로 FreeRTOS에서 부족한 Library와 버그들을 수정을해가면서 제공을 해주고 있다. 
만약 ESP32 혹은 다른 MCU기반으로 AWS FreeRTOS기반으로 연결하여 쉽게 테스트는 가능하지만, 현재 테스트 결과 ESP32의 경우 
Heap 관련부분에 좀 문제가 존재하지만, 추후에 이 부분은 보강이 될것이라고 생각된다.

  • AWS FreeRTOS
AWS FreeRTOS 문서

AWS FreeRTOS 소스


3.2 Zephyr

  • Zephyr
ESP32도 Zepheyr가 제공되기 시작했지만, 아직 테스트를 해보지는 못함

댓글 없음 :
Tags: , , ,

6/19/2021

ESP32 BT(Bluetooth) 기본동작 및 BT Stack 비교

1. ESP32 Bluetooth 관련정보 

  • ESP32의 HCI(Host Control Interface)
다른 Bluetooth 처럼 Serial 기반으로 연결되어 HCI가 존재하며, 별도로 VHCI가 존재하고 있음 

  • ESP32 Bluetooth Control/VHCI Layer 함수
HCI(Host Control Interface) 대신 ESP32 Control 기반에 VHCI(Virtual Host Control Interface) 구현됨 
  1. ESP32 Bluetooth Control 함수 
  2. VHCI(Virtual Host Control Interface) Layer 

Bluetooth의 기본동작원리 


1.1  ESP32 Bluetooth 의 Host 구조 및 설정 


ESP32의 경우 BT(Bluetooth) Controller 연결상태에 따라 VHCI or HCI로 연결되어 동작된다.

  • ESP32의 Bluetooth Controller 와 VHCI/HCI 구조 
ESP32 Bluetooth Controller 기반으로 VHCI로 연결하여 Bluedroid를 사용하고 있으며, 외부로 UART로 확장가능 (UART로할 경우 HCI로 동작)
ESP32는 VHCI기반으로 동작되어지고 있으며, Nimble도 동일하며, HCI와 동일하다고 생각하면됨 


https://www.espressif.com/sites/default/files/documentation/esp32_bluetooth_architecture_en.pdf


HCI 관련정보

  • Bluetooth의 HCI의 ACL과 SCO Link 비교
  1. SCO(Synchronous Connection-Oriented) Link 
  2. ACL(Asynchronous Connection-Less)  Link
세부적인 내용은 아래내용참조


  • BT(Bluetooth) 의 HCI Packet 종류
https://www.koreascience.or.kr/article/JAKO200170709939787.pdf


  • ESP32 BT Classic(BR/EDR) 와 BT LE Controller 구조 
  1. SCO(Synchronous Connection-Oriented) Packet: HCI기반으로 동작 (Data)
  2. ACL(Asynchronous Connection-Less) Packet:  HCI기반으로 동작 (Data)
  3. C/E : (Command/Event) Packet : HCI 기반으로 동작 (Control) 

BT BR/EDR 과 BT LE 의 구조  
BT의 HCI는 아래와 같이 SCO 와 ACL Link가 존재하며, 이는 데이타를 전달(검정색)
Command/Event의 경우 Command와 Event 로 제어담당 (회색)

  https://www.espressif.com/sites/default/files/documentation/esp32_bluetooth_architecture_en.pdf

ESP32 BT Controller 와 VHCI(Virtual HCI)

H4/HCI Protocol

Bluetooth Controller / Host Stack 

  • 일반적인 BT Controller 와 Stack 전체구조 
HCI(Host Control Interface) 기준으로 일반적인 Host Controller 와 상위 Stack을 보도록하자.

** L2CAP를 걸쳐 RFCOMM 기반으로 PPP기반으로 통신도 가능

https://www.koreascience.or.kr/article/JAKO200170709939787.pdf


  • Bluetooth Version의 변화 (Dual Mode 와 BLE) 
  1. Bluetooth BR/EDR (2.x 기반)
  2. Bluetooth BLE (4.x 기반)
  3. Dual Mode (BR/EDR 와 BLE 모두사용)

BR/EDR 와 BLE 와 Dual Mode 차이와 비교
현재는 아래의 사이트로만으로 충분한 이해는 되지 않고 추후 관련부분을 더 조사

Dual Mode의 장점

BT의 Version 별 기능 


  • ESP32 CONFIG_BT_HOST 설정 
  1. Bluedroid (BT Dual Mode)
  2. Nimble (BLE Only)
  3. 상위외 다른 Stack을 사용하고자한다면 이용

ESP32 관련설정 BTDM (Dual Mode)

  • Bluetooth Classic (BR/EDR 2.x기반)
  1. BR : Basic Rate
  2. EDR : Enhanced  Data Rate



1.2 ESP32의 Bluetooth Core 사용 

  • ESP32의 Bluetooth Core 사용
주의해야할것은 ESP32는 Dual Core이지만, 기본적으로 1개의 Core만 사용하면서 동작되므로, Dual Core는 별도로 설정 및 Task로 분할해서 사용하도록하자.  
  1. PRO_CPU
  2. APP_CPU


2. Bluetooth Stack 종류 와 구조 

  • ESP32에서 제공하는 Bluetooth Stack Library
  1. BlueDroid/Fluoride
  2. Nimble(Apache Mynewt NimBLE)

현재 ESP32의 Bluetooth는 BlueDroid기반과 Nimble기반으로 구현이되어 두가지 방식으로 구현가능하다. 

ESP32의 경우 각 Stack마다 동작되는 BT의 기능이 다르므로 주의하도록하자.
Nimble은 BLE Only

  • ESP32의 BT Stack 기본비교 
  1. Bludroid: Android 기반의 BT/BLE로 크고 다양한 기능을 제공하며 Size가 큼 
  2. nimble : BLE만 지원가능하며 작은 Size로 제공가능하며, 아파치 라이센스
Bluedroid/Nibme 비교 

내 개인생각으로느 ESP32가 MCU이기때문에 거의 Nimble로 선택되어 구성될 것으로 생각되며, Bludroid는 다양한 기능을 구현할때 사용하면 될 꺼 같다.


2.1 ESP32 BlueDroid 기반구조(Dual Mode, BT/BLE) 

BlueDroid는 상위 wiki 설명을 보면, Broadcom에서 만들어졌으며, Android에서 처음 Linux에서 사용하던 Bluez를 사용하다가 
BlueDroid로 변경되었다고 하며, 현재 Fluoride라고 이름이 변경되어졌다고 한다.
세부사항은 상위 Wiki 참조 

  • ESP32 BlueDroid 의 구조
  1. BTC Task (Bluetooth Control layer) : BTA_API 와 ESP_API 통신하며, SDP/GAP/GATT 외 BLE/BT Profile Control 
  2. BTU Task :  BLE & BT Stack 정보를 BTA_API 에게 전달  

- GAP(General Access Profile)
- GATT(General Attribute Profile)
- SM(Security Manager)
- ATT(Attribute Protocol)
- L2CAP(Logical Link Control and Adaption Protocol)
- SDP(Service Discovery Protocol)




  https://www.espressif.com/sites/default/files/documentation/esp32_bluetooth_architecture_en.pdf


  • Android Bluetooth 구조 
Android에서 BlueDroid가 사용되어진다고하니, 관련부분들을 링크


ESP32의 BlueDroid는 아래와 같이 Common/BLE/Classic로 구분되어지는 것 같으며, 각각의 부분을 알아야 할 것 같다.

  • ESP32 BlueDroid - BT Common
BlueDroid 기본 Control 부분


  • ESP32 BlueDroid - BLE
GAP/GATT/BLUFI



2.2 ESP32 Nimble 기반구조 (BLE Only)

ESP-Controller는 공유하지만, Nimble 전용 VHCI 가 별도로 존재하며, Nimble Host가 최종적으로 동작되어 Nimble전체를 동작시키는 구조




  • Host 관련부분 설정 
ESP32 Host 관련부분설정 


  • ESP32 Nimble API
세부기본 사용법은 아래의 Link를 참조 

  • Nimble BLE Host 와 Controller 구성
상위 BlueDroid와 동일하게 Host와 Controller 기본구성 (아래링크참조)

  • Nimble 의 reset/sync 함수 
nimble은 host 와 controller가 sync가 맞지않는동안 동작되지 않는다고 한다.
그래서 주기적으로 sync callback를 호출하여 sync를 맞추므로 중요
controller가 reset이 되면서 host역시 이를 reset를 해야하므로 중요


  • Nimble Host API
Nimble의 ATT(Attribute Protocol)함수 GAP 등 

  • ESP32 Bluetooth 구조 및 전체설명문서
ESP32의 Bluetooth에 관련된 내용에 대해 자세히 나오므로 필독



3. Bluetooth 관련 TEST App 

BT TEST를 위해 관련된 TEST Application의 자료수집이며, 현재 Android에서 nRF Connect로 쉽게 GAP/GATT를 테스트 및 디버그가 가능하다.

  • Window 11/10
nRF Connect for Desktop

  • Android BT/BLE 관련 Tool (Nordic Semiconductor)
nRF Connect for Mobile
가장 많이 사용되어지는 Program 

nRF Toolbox for BLE
Android BT GATT 부분 Debug 분석 

Android BT Tool 

댓글 없음 :
Tags: , , ,

6/04/2021

ReadTheDoc 의 Doc Host (Mkdoc/Sphinx)

1. RST 파일 과 Markdown

기술문서작성 흐름이 RST or Markdown 기반으로 손쉽게 작성가능하도록 변경되어져 가며,
이를 지원하는 Python Package들이 존재하는 것을 그동안 알지 못했다. 
ESP-IDF 개발환경에 관련된 문서를 분석하면서 많은 부분을 알게되었는데, 쉽게 문서작업하는 방법과 
Python 기반의 Doxygen 연결부분을 알게되었지만, 
ESP-IDF의 경우, Espressif에서 독자적으로 많이 고쳐가면서 구현한걸로 보인다. 

ESP32/ESP-IDF Sphinx 의 구성 

점점 아래의 Markup Language기반으로 기술문서가 변화되어져가며, 이는 호환성과 문서의 간결성이 중요해질 것 같다. 
다양한 보조도구들이 등장하는데, 이들도 쉬운작성법과 호환성 및 Open Source를 기반으로 하기 때문에 많이 사용되어지는 것 같다.
 
RST 파일 (Sphinx 사용)

Markdown 


1.1 Python 기반의 기술문서작성(Sphinx 와 Mkdocs) 

현재 Python 기반으로 구성된 Program은 Sphinx 와 Mkdocs기반으로 크게 두 갈래로 방향이 나뉘어 작성되어지며 가는 것으로 보인다. 
대체적 보면, Sphinx 기반으로 많이 선택해서 사용하는 것으로 보이는데, 다양한 기능 과 확장성 때문이라고 생각되어진다.

RST 과 Markdown 지원으로 문서작성가능하지만, 기반이 RST기반으로 사용한다. 
둘다 Markup Language이므로 쉽게 도표 및 테이블이 쉽게작성 가능하며, 다양한 확장패키지들을 제공하고 있어, 기능확장되어
점점 더 많은 패키지들을 제공하고 있으므로, 아래의 링크로 확인가능 

Sphinx기반으로 문서작성법
재미있는 것은 Sphinx의 Theme도 ReadTheDoc에서 제공해주고 있는데, 이 기반으로 사용하면 좋은 것 같다. 
ESP32의 경우도 이 Theme을 기반으로 별도 수정해서 사용하고 있지만, 변경해서 사용하고 있다. 


Sphinx Extension

Sphinx Extension 중 유용할 것 같은것들 

반드시 다른 ReadTheDoc Github 내부사이트의 Python requirements.txt 확인 


Markdown 기반으로 문서작성 가능하며, 다루기는 이게 더 편할걸로 생각되어진다. 
하지만, 아직 확장패키지까지 다 설치를 해보지 못하여 완벽한 비교는 못하겠지만, Sphinx 만큼의 확장패키지를 제공못하는 걸로 생각되어진다. 

Mkdocs 기반으로 문서작성법 
Python 설치해보고 기본테스트만 해봄 

만약 Sphinx와 Mkdocs를 설치해서 테스트하고자 하면, virtualenv(venv)를 사용하거나 conda를 이용하여 하도록하자.

  • Sphinx 와 Mkdocs 비교 
솔직히 RST과 Markdown의 큰 차이성은 아직 잘 모르겠으나, RST가 좀 더 많은 기능을 가진것으로 보인다.  
예를들면 RST 파일의 toctree 구성이 될 것 같다. 
두개 다 비슷한 문법으로 사용되어진다고 생각되어지지만, 다르다고 하니, 
차차 문서를 직접 작성할 경우에, 다른점들을 비교해가면서 알아보도록하자. 

1.2 Sphinx 와 Doxygen 기능확장 

Doxygen기반으로 구축하며 문서작성을 한다면,  소스에 각 함수의 설명들을 쉽게 문서화가 가능하므로 
Sphinx와 Doxygen을 연결하여 사용가능하다. 
현재 대부분 이런형식으로 기술문서들이 구성되어 사용되어지는 것 같으며, Sphinx에서 Doxygen을 이용한다면,  
Breathe를 반드시 설치한 후 사용해야하며,  이 Breathe 역할은 Doxygen 부분을 연결해주는 것이라고 한다.  
아래의 링크처럼 최종적으로 모든것이 Cmake에서 관리되도록 구성하여 최종관리를 한다. 
 
  • Sphinx/Breathe/Doxygen/Cmake 기반의 문서구성 
Cmake기반으로 가장잘 설명된 좋은 예제 인것 같으며, Doxygen도 사용할 경우 괜찮을 것 같다. 


  • Sphinx 기반의 ESP32 Doxygen 분석 
처음에 Github의 Page에서 *rst를 인식해서 Web Host 하는 줄 알았다. 
ReadTheDoc 기반으로 구성되어진다는 것을 알게되었으며, 모든 것이 쉽게 풀리게되었다. 
앞으로 가급적 ReadTheDoc를 이용하도록 하겠다. 


물론 Doxygen까지 필요 없다면, 쉽게 Mkdocs구성도 괜찮을 걸로 생각되어진다. 


2. ReadTheDocs 의 Host 사용법

이 사이트는 이전에 Sphinx 기반으로 문서작성법을 알아보다가 알게된 사이트이며, 상위 Sphinx와 Mkdocs를 둘다 지원한다. 
Git사이트의 Web host 전문사이트라고 생각하면 되겠으며, Github에서 Page를 HTML기반으로 설정하면 되겠지만, 너무 불편하다.
그리고, Github의 Page Web Host는 한계가 있는것 같다. 

  • ReadTheDocs의 Doc Host 기능 
  1. Git(Github/Gitlab) 사이트에서 작성된 Sphinx or Mkdocs 기반으로 문서작성 
  2. Git 사이트에서 작성된 문서를 ReadTheDoc로 Import  
  3. .readthedocs.yml 설정기반으로 기본 Python 환경설정
  4. Git사이트의 Python의 requirements.txt 부분 확인 (ReadTheDoc는 가상환경에 설치)
  5. Sphinx or Mkdocs 기반으로 빌드하여, HTML로 환경구축
  6. Build에 문제없다면, 이를 Web Host 진행완료 

  • ReadTheDoc의 기본사용법과 특징 

  • ReadTheDocs (Sphinx/Mkdocs)
Sphinx 와 Mkdocs 둘자 지원가능 

  • .readthedoc.yml 
Git 사이트내에 반드시 존재해야하며, 이 설정값 기반으로 Python 환경구축하므로 반드시필요 

  • Github 의 Page 사용법 
만약 ReadtheDocs를 사용하지 않고 Github에서 host하고자 하면, HTML로 만들어서 이곳에서 설정 이부분 이전에 설명 



2.1 ReadTheDocs 의 사이트종류 

ReadTheDocs 사이트는 두개로 나뉘어지며, Community 와 Business Version으로 나뉘어지며, 사이트도 다르다 

  • Community ReadTheDocs 
무료로 사용가능하며 Custom Domain 지원가능도 가능하며, 오픈소스들위해서 무료로 제공해주고 있다
다만 광고를 봐야하며, 광고를 삭제하고자 하면 돈을 지불해야함 

  • Business ReadTheDocs
Business 용으로 유료버전으로 기능을 제공을하는데, 현재 사용해보지는 못해서 아래 지원기능만 링크 

Business ReadTheDocs 특징과 설명 
Google의 G Suit와 도 연결해서 사용가능한것 같다 

  • ReadTheDocs의 Custom domain 설정 
아래와 같이 쉽게 ReadTheDoc Community 에서 쉽게 Host가 가능하며, Community도 Custom Domain을 지원한다.


2.2 ReadTheDocs 와 Github 연결방법

나의 경우, Github 와 ReadTheDocs Comminity로 연결하여 아래와 같이 구성하였다. 

사용법은 어렵지 않으며, 우선 가입후 Github/Gitlab등 Git사이트와 연결을 하도록하자. 
이부분은 WebHook부분을 보면될 것이며, Github기반으로 가입하면 별도의 설정은 필요없다. 

  • ReadTheDocs 사이트
본인설정확인 
 
  • Github의 Setting Webhook 확인 



Integrations 부분은 설정만 확인했지만, Github에서 Automation 기능은 아직 설정해보지 못함
(Github application을 별도로 설치진행해야 할 것 같음)

ReadTheDocs Host 관련문서 및 Github와 연결방법  



2.3 ReadTheDocs의 Build 방법  

  • ReadTheDoc의 Build Example 
Build를 진행하면 시간이 상당히 많이 걸리며, 아래와 같이 쉽게 Build 과정을 볼수 있다.



Build가 Fail이 되면 관련부분 을 분석해서 보도록하며, 상위 설정파일(.readthedoc.yml) 같이 봐야하며, 
ReadTheDoc Server에서도 VirtualEnv기반으로 구성하며, 관련설치부분을 자세히 보도록하자.


Build가 된후 ViewDoc를 보면 되며, 관련링크로 Host가 진행됨 



사용후 가장 좋은 점 바로 수정 Github에서 수정가능하며, 이를 Github에서 확인이 가능하다. 


3. ReadTheDocs의 나의 Host예제   

상위와 같이 쉽게 빌드하여, 나도 아래와 같이 쉽게 ReadTheDocs를 이용하고 있으며, 
아래와 같이 간단하게 Examples들을 링크한다. 

  • Github 기반의 ReadTheDoc Host TEST Example 1
ReadTheDocs에서 제공해주는 Github Template을 가져와서 이를 Build후 Web Host 진행

ReadTheDoc의 WebHost Ex.1

ReadTheDoc의 Github 

  • Github 기반의 ReadTheDoc Host TEST Exampe 2 
현재 ReadTheDocs 관련문서도 Github기반으로 작성되어있으므로, 이를 Github에서 Fork를 하고 가져와서 
이를 ReadTheDocs로 가져온 후 Build 후 Web Host 진행 

ReadTheDoc의 WebHost Ex.2 

ReadTheDoc의 Github 


3.1 ReadTheDoc를 이용한 다른사이트의 예 

여러 사이트를 보면, Doxygen은 옵션으로 많이 사용하며, Doxygen 필요성도 크게 의문도 들기도한다. 
함수의 API의 설명과 관계도를 자세히 보고자 한다면 필요하겠다 (특히 , C++, Java)

나의 개인생각으로는 Doxygen까지 필요 없다면, Mkdocs를 이용해도 괜찮을 것 같다. 
다만, 다른 사이트들을 보면 거의 Sphinx 위주로 구성되어 작성되어지는 것을 볼 수 있다. 
개인생각으로는 확장성때문일 걸로 생각되어진다. 


ReadTheDoc Hosting 설정(Sphinx) 

  • Godot Docs (Github 연결)
추후 사용할 시 반드시 참고해야하며, 메뉴와 설정이 다양하게 구성되었으며, Sphinx 이용 

  • ESP-IDF (Github 연결)
ESP-IDF로 자세히 Manual을 사용하며, Sphinx 기반으로 작성 

  • Verilog-To-Routing (Github 연결)
오직 문서 구성과 방식 보며, 간단하며, 역시 Sphinx 기반으로 작성 


기타 
댓글 없음 :
Tags: , ,
피드 구독하기: 글 ( Atom )