IOTHUB SOFTWARE · 03
Arduino 라이브러리 실무 관리
라이브러리는 설치만 하면 끝나는 것이 아닙니다. 같은 이름의 라이브러리, 예제와 버전 차이, 보드 호환성 때문에 컴파일 오류가 자주 생깁니다.
라이브러리는 "미리 만들어진 코드 뭉치"다. 센서 데이터 읽기, 화면에 글씨 그리기 같은 복잡한 작업을 우리가 직접 코딩하지 않아도 되게 해준다.
설치 방법
Arduino IDE에서 Tools → Manage Libraries (또는 왼쪽 라이브러리 아이콘). 검색창에 이름을 입력하고 Install.
시리즈 전체에서 필요한 라이브러리
| 라이브러리 | 검색어 | 어디 편에 필요 | 설치 |
|---|---|---|---|
| Adafruit SSD1306 | Adafruit SSD1306 | 2~20편 (OLED) | 필수 |
| Adafruit GFX | Adafruit GFX | 2~20편 (OLED) | 필수 |
| TFT_eSPI | TFT_eSPI | 21~22편 (TFT) | TFT 쓸 때만 |
| XPT2046_Touchscreen | XPT2046_Touchscreen | 22편 (터치) | 터치 TFT 쓸 때만 |
| DHT sensor library | DHT sensor library | 3,6,7,19편 | DHT22 쓸 때만 |
| OneWire | OneWire | 5,8편 | DS18B20 쓸 때만 |
| DallasTemperature | DallasTemperature | 5,8편 | DS18B20 쓸 때만 |
| IRremoteESP8266 | IRremoteESP8266 | 17편 | IR 제어 쓸 때만 |
| HX711 | HX711 | 18편 | 로드셀 쓸 때만 |
처음 시작한다면 Adafruit SSD1306 + Adafruit GFX 두 개만 설치해도 2편부터 진행할 수 있습니다. 나머지는 해당 편에서 필요할 때마다 추가 설치하면 됩니다.
Python 라이브러리
23~24편에서는 Python 라이브러리도 필요하다. 터미널(검은 창)에서 설치한다:
pip install flask requests| 라이브러리 | 용도 | 사용처 |
|---|---|---|
flask | 웹 서버 | 24편 (AI 브로커) |
requests | HTTP 통신 + TLS | 24편 (AI API 호출) |
안 될 때
| 증상 | 해결 |
|---|---|
| 라이브러리 검색 결과가 안 나옴 | 철자 확인. Adafruit가 Adafruit인지 Adafruit_가 맞는지 |
| 설치 중 오류 | 인터넷 연결 확인. Arduino IDE를 관리자 권한으로 실행(Windows) |
| 다른 라이브러리와 충돌 | TFT_eSPI를 쓸 때 다른 TFT 라이브러리(Adafruit_ILI9341 등)가 깔려 있으면 충돌. 필요 없는 TFT 라이브러리는 삭제 |
라이브러리는 프로젝트 자산으로 기록한다
라이브러리는 한 번 설치하면 끝나는 부품처럼 보이지만, 실제로는 프로젝트의 중요한 의존성입니다. 오늘 컴파일되던 코드가 몇 달 뒤 새 PC에서 깨지는 이유는 대부분 라이브러리 버전이 달라졌기 때문입니다. 그래서 글을 따라 만든 장치가 정상 동작한 날의 라이브러리 이름과 버전을 기록해두는 것이 좋습니다.
본문 코드보다 예제를 먼저 컴파일한다
새 라이브러리를 설치한 뒤에는 본문 코드를 바로 올리지 말고, 라이브러리가 제공하는 가장 단순한 예제를 먼저 컴파일합니다. 예제가 깨지면 본문 코드를 고쳐도 소용이 없습니다. 예제가 성공한 뒤 핀 번호와 설정 파일만 프로젝트에 맞춰 옮기는 순서가 안전합니다.
특히 디스플레이 계열은 라이브러리 설치보다 설정 파일이 더 중요합니다. TFT_eSPI는 화면 드라이버, 해상도, 핀 연결을 맞춰야 하므로, 한 번 성공한 설정 파일을 프로젝트 폴더에 따로 보관하는 편이 좋습니다.
라이브러리 오류는 코드 오류처럼 보인다
초보자는 컴파일 오류가 나오면 본인이 쓴 코드가 틀렸다고 생각하기 쉽습니다. 하지만 실제로는 라이브러리 버전이 다르거나, 같은 이름의 라이브러리가 여러 개 설치되어 엉뚱한 파일을 참조하는 경우가 많습니다. 특히 디스플레이 라이브러리는 설정 파일까지 맞아야 해서 더 자주 막힙니다.
설치 원칙
- 글에서 지정한 라이브러리 이름과 제작자를 확인합니다.
- 비슷한 이름의 라이브러리를 여러 개 설치하지 않습니다.
- 예제가 컴파일되는지 먼저 확인한 뒤 본문 코드를 올립니다.
- TFT_eSPI처럼 설정 파일이 필요한 라이브러리는 보드와 핀 설정을 기록합니다.
- 한 번 성공한 버전은 프로젝트 메모에 남깁니다.
컴파일 오류가 날 때 순서
- 오류 메시지의 첫 번째 라이브러리 이름을 확인합니다.
- Library Manager에서 해당 라이브러리가 설치되어 있는지 확인합니다.
- 예제 스케치가 컴파일되는지 확인합니다.
- 보드 종류를 바꿔 컴파일했는지 확인합니다.
- 필요하면 라이브러리 버전을 낮추거나 올려봅니다.