아두이노 우노 Q SSD1309 OLED 디스플레이 (2.42 인치)
이 튜토리얼은 Arduino UNO Q에서 2.42인치 SSD1309 OLED 128x64 디스플레이를 사용하는 방법을 보여줍니다 — 기본 텍스트 및 그래픽부터 Telegram을 통한 원격 제어까지.
- Arduino UNO Q에 SSD1309 OLED 128x64를 연결하는 방법
- DIYables_OLED_SSD1309 라이브러리를 사용하여 텍스트 및 숫자를 표시하는 방법
- OLED에 도형(선, 직사각형, 원, 삼각형)을 그리는 방법
- 여러 방향에서 하드웨어 스크롤을 사용하는 방법
- OLED에 비트맵 이미지를 표시하는 방법
- 밝기 및 명암 제어하는 방법
- 사용자 정의 외부 글꼴을 사용하는 방법
- Bridge 프로그래밍을 통해 Telegram에서 OLED를 원격으로 제어하는 방법

필요한 하드웨어
| 1 | × | Arduino UNO Q | 아마존 | |
| 1 | × | USB Cable for Arduino Uno Q | 아마존 | |
| 1 | × | SSD1309 I2C OLED Display 128x64 (2.42 inch) | 아마존 | |
| 1 | × | 점퍼케이블 | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 스크루 터미널 블록 쉴드 | 쿠팡 | 아마존 | |
| 1 | × | (추천) Sensors/Servo Expansion Shield for Arduino Uno | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 브레드보드 쉴드 | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 케이스 | 쿠팡 | 아마존 | |
| 1 | × | (추천) 아두이노 우노용 프로토타이핑 베이스 플레이트 & 브레드보드 키트 | 아마존 |
SSD1309 2.42인치 OLED 디스플레이 정보
SSD1309는 2.42인치(때로는 2.4인치로 표시) I2C OLED 모듈에서 일반적으로 찾을 수 있는 128×64 OLED 드라이버 IC입니다. SSD1306과 레지스터 호환되지만 외부 VCC 레일을 사용합니다(breakout 보드의 온보드 부스트 컨버터로 투명하게 처리됨). 주요 특징:
- 해상도: 128 × 64 픽셀
- 인터페이스: I2C (필요한 와이어는 4개뿐)
- 디스플레이 색상: OLED 물질에 따라 흰색, 파란색 또는 노란색 — 소프트웨어로 제어 불가
- 시야각: 넓음, 자체 발광 픽셀 — 진한 검은색, 백라이트 불필요
- 라이브러리: DIYables_OLED_SSD1309 사용 (Adafruit GFX 확장)
SSD1309 OLED 핀아웃
- GND — GND에 연결
- VCC — 5V에 연결
- SCL — I2C 클록 신호
- SDA — I2C 데이터 신호

※ 주의:
제조사에 따라 핀 순서가 다를 수 있습니다. 항상 OLED 모듈에 인쇄된 레이블을 사용하세요.
배선 다이어그램

이 이미지는 Fritzing을 사용하여 만들어졌습니다. 이미지를 확대하려면 클릭하세요.
| OLED 핀 | Arduino UNO Q 핀 |
|---|---|
| GND | GND |
| VCC | 5V |
| SCL | SCL |
| SDA | SDA |
SSD1309 OLED를 프로그래밍하는 방법
- 라이브러리 포함:
- 디스플레이 객체 생성:
- setup()에서 초기화:
- 텍스트 표시:
※ 주의:
항상 display.display()를 호출하여 그리기 명령 후 버퍼를 물리적 화면으로 밀어냅니다.
Arduino UNO Q 코드 — SSD1309 OLED의 Hello World
Arduino UNO Q는 두 개의 프로세서를 가지고 있습니다: STM32 MCU(실시간 하드웨어 제어 처리) 및 Qualcomm MPU(Debian Linux 실행). 이 섹션에서는 STM32 MCU만 프로그래밍됩니다 — Linux 쪽은 유휴 상태입니다. 나중 섹션에서는 두 프로세서가 함께 작동하는 방법을 보여줍니다.
아래 스케치는 두 개의 다른 크기로 OLED에 텍스트를 표시합니다.
빠른 단계
- Arduino UNO Q 처음 사용? 진행하기 전에 아두이노 우노 Q 시작하기 튜토리얼을 따라 개발 환경을 준비하세요.
- OLED 배선: GND→GND, VCC→5V, SCL→SCL, SDA→SDA를 연결합니다.
- 연결: Arduino UNO Q를 USB-C 케이블로 컴퓨터에 연결합니다.
- Arduino App Lab 열기: Arduino App Lab을 시작하고 Arduino UNO Q를 감지할 때까지 기다립니다.
- 새 App 만들기: Create New App 버튼을 클릭합니다.

- App에 이름을 지정합니다(예: DIYables_SSD1309)
- Create를 클릭하여 확인합니다.
- 새 App 내에 생성된 폴더 및 파일 세트가 표시됩니다.

- sketch/sketch.ino 파일을 찾습니다 — 이곳이 MCU 스케치를 붙여넣을 위치입니다.
- Install the library: Click the Add sketch library button (the open book icon with a + sign) in the left sidebar.

- Search for Arduino_RouterBridge created by Arduino and click the Install button.
- Search for DIYables_OLED_SSD1309 created by DIYables and click the Install button.
- 업로드: Arduino App Lab의 Run 버튼을 클릭하여 STM32로 컴파일 및 업로드합니다.

OLED를 보면 "Hello, World!", "DIYables", "SSD1309 OLED 128x64"가 표시됩니다!
Arduino UNO Q 코드 — SSD1309 OLED에 텍스트 표시
이 예는 다양한 텍스트 크기와 정수, 부동소수점 및 16진수를 OLED에 표시하는 방법을 보여줍니다.
빠른 단계
- 위의 코드를 복사하여 sketch/sketch.ino에 붙여넣습니다.
- Arduino App Lab의 Run 버튼을 클릭합니다.

OLED는 텍스트 크기 데모를 순환한 다음 정수, 부동소수점 및 16진수를 표시합니다.
유용한 디스플레이 함수 참고 자료
일반적으로 사용되는 SSD1309 OLED 함수의 빠른 참고 자료:
- display.clearDisplay() — 프레임 버퍼 지우기 (모든 픽셀 꺼짐)
- display.display() — 버퍼를 화면으로 밀어냅니다 — 모든 그리기 호출 후 필수
- display.drawPixel(x, y, color) — 단일 픽셀 설정 또는 해제
- display.setTextSize(n) — 글꼴을 배수 *n*만큼 확대 (1 = 6×8 px, 2 = 12×16 px, …)
- display.setCursor(x, y) — 텍스트 커서를 픽셀 좌표 *(x, y)*로 이동
- display.setTextColor(SSD1309_PIXEL_ON) — 텍스트 전경만 (투명 배경)
- display.setTextColor(SSD1309_PIXEL_OFF, SSD1309_PIXEL_ON) — 명시적 배경이 있는 텍스트
- display.println("message") — 문자열을 인쇄하고 다음 줄로 이동
- display.println(number) — 정수를 10진수로 인쇄
- display.println(number, HEX) — 정수를 16진수로 인쇄
- display.startscrollright(start, stop) — 페이지 간 하드웨어 오른쪽 스크롤
- display.startscrollleft(start, stop) — 하드웨어 왼쪽 스크롤
- display.startscrolldiagright(start, stop) — 대각선 오른쪽 스크롤
- display.startscrolldiagleft(start, stop) — 대각선 왼쪽 스크롤
- display.stopscroll() — 활성 하드웨어 스크롤 중지
- display.setContrast(value) — 밝기 조정 (0–255)
- display.dim(true/false) — 빠른 어둡게 토글
- display.invertDisplay(true/false) — 하드웨어 수준 색상 반전
Arduino UNO Q 코드 — SSD1309 OLED에 도형 그리기
DIYables_OLED_SSD1309 라이브러리는 Adafruit_GFX에서 상속되어 픽셀, 선, 직사각형, 채워진 직사각형, 원, 채워진 원, 삼각형, 채워진 삼각형 및 둥근 직사각형을 제공합니다. 아래 스케치는 모두 순환합니다.
빠른 단계
- 위의 코드를 복사하여 sketch/sketch.ino에 붙여넣습니다.
- Arduino App Lab의 Run 버튼을 클릭합니다.

OLED는 모든 도형 — 픽셀, 선, 직사각형, 원, 둥근 직사각형 및 삼각형을 순환합니다!
Arduino UNO Q 코드 — SSD1309 OLED에서 하드웨어 스크롤
SSD1309는 CPU 작업 없이 콘텐츠를 이동하는 내장 하드웨어 스크롤 엔진을 가지고 있습니다. 라이브러리는 4가지 스크롤 방향을 제공합니다: 오른쪽, 왼쪽, 대각선 오른쪽 및 대각선 왼쪽.
※ 주의:
항상 스크롤을 시작하기 전에 display.display()를 호출하여 콘텐츠를 OLED로 전송합니다. 새 콘텐츠를 그리기 전에 stopscroll()를 호출합니다.
빠른 단계
- 위의 코드를 복사하여 sketch/sketch.ino에 붙여넣습니다.
- Arduino App Lab의 Run 버튼을 클릭합니다.

OLED는 "DIYables"를 오른쪽, 왼쪽, 대각선 오른쪽 및 대각선 왼쪽으로 스크롤하여 계속 반복합니다.
Arduino UNO Q 코드 — SSD1309 OLED에 비트맵 이미지 표시
SSD1309 OLED에 비트맵을 표시하려면 먼저 이미지를 C 바이트 배열로 변환해야 합니다. 무료 이미지를 비트맵으로 변환 도구를 사용합니다:
- 이미지 파일 (PNG, JPG, BMP 등)을 업로드합니다.
- 캔버스 크기를 128×64(또는 더 작게)로 설정합니다.
- Arduino code를 출력 형식으로 선택합니다.
- 생성된 배열을 스케치에 복사합니다.

아래 스케치는 16×16 하트 아이콘을 표시한 다음 전체 128×64 DIYables 로고로 전환합니다 — 둘 다 코드에 바이트 배열로 저장됩니다:
빠른 단계
- 위의 코드를 복사하여 sketch/sketch.ino에 붙여넣습니다.
- Arduino App Lab의 Run 버튼을 클릭합니다.

OLED는 3초 동안 하트 아이콘을 표시한 다음 DIYables 로고로 전환합니다.
※ 주의:
비트맵 크기는 화면 해상도 (128×64)를 초과할 수 없습니다.
Arduino UNO Q 코드 — SSD1309 OLED의 명암 및 어둡게
SSD1309는 256개의 명암 레벨(0–255)을 지원합니다. 미세 제어를 위해 setContrast()를 사용하고 빠른 밝기 토글을 위해 dim()을 사용합니다.
빠른 단계
- 위의 코드를 복사하여 sketch/sketch.ino에 붙여넣습니다.
- Arduino App Lab의 Run 버튼을 클릭합니다.

OLED 밝기가 위로 올라간 다음 내려가고, 어둡게 켜기/끄기 순환이 뒤따릅니다.
Arduino UNO Q 코드 — SSD1309 OLED의 사용자 정의 외부 글꼴
Adafruit GFX 라이브러리에는 많은 FreeFont 서체(Serif, Sans, Mono — 다양한 크기)가 포함되어 있습니다. 글꼴 헤더를 포함하고 setFont()를 호출하여 사용합니다.
※ 주의:
외부 글꼴이 활성화되면 커서 Y 좌표는 왼쪽 위 모서리가 아닌 텍스트 기준선을 의미합니다. 이는 내장된 5×7 글꼴과 다릅니다.
빠른 단계
- 위의 코드를 복사하여 sketch/sketch.ino에 붙여넣습니다.
- Arduino App Lab의 Run 버튼을 클릭합니다.

OLED는 내장된 글꼴, FreeSerif 9pt, FreeSansBold 12pt 및 FreeMono 9pt를 순환합니다.
Linux + MCU Bridge 프로그래밍
Arduino UNO Q는 함께 작동하는 두 개의 프로세서를 가지고 있습니다: MPU (Qualcomm, Debian Linux 실행) 및 MCU (STM32, Arduino 스케치를 실행하는 Zephyr OS). 그들은 Arduino_RouterBridge 라이브러리를 사용하여 RPC를 통해 통신합니다 — 절대 원본 직렬 포트를 통하지 않습니다.
- SSD1309 OLED는 MCU (STM32)에 연결됩니다 — I2C (SCL/SDA)를 통해. MCU만 직접 구동할 수 있습니다.
- MPU는 OLED를 직접 제어할 수 없습니다 — Bridge.call("display_text", "text")를 호출하여 디스플레이를 업데이트하고 결과를 Monitor로 인쇄합니다.
- MPU에는 Wi-Fi가 있습니다 — MPU가 Wi-Fi를 포함한 완전한 Debian Linux를 실행하기 때문에 Telegram 명령을 수신하고 OLED에 모든 메시지를 표시할 수 있습니다.
- 통신: Linux 쪽의 Bridge.call()은 MCU 쪽의 Bridge.provide_safe() 함수를 호출합니다(OLED 쓰기가 하드웨어 API 호출이므로).
- ⚠️ 예약됨: /dev/ttyHS1 (Linux) 및 Serial1 (MCU)은 Arduino Router에서 사용됩니다 — 직접 열면 안 됩니다.
MCU 스케치 — Bridge 및 Monitor 출력이 있는 SSD1309 OLED:
Python 스크립트 (Arduino App Lab) — Linux에서 SSD1309 OLED에 텍스트 표시:
빠른 단계
- 새 App 만들기: Arduino App Lab을 열고 Create New App을 클릭하고 DIYables_SSD1309_Bridge라는 이름을 지정하고 Create를 클릭합니다.
- MCU 스케치 붙여넣기: 위의 Bridge MCU 코드를 복사하여 sketch/sketch.ino에 붙여넣습니다.
- Python 스크립트 붙여넣기: 위의 Python 코드를 복사하여 App의 Python 파일에 붙여넣습니다.
- App 실행: Run 버튼을 클릭합니다 — Python 쪽은 OLED의 메시지를 순환합니다.
App Lab 콘솔 출력
Telegram 통합
어디서든 Telegram을 통해 SSD1309 OLED에 텍스트를 표시합니다.
Telegram 봇이 없으면 진행하기 전에 아두이노 우노 Q - 텔레그램 봇을 참조하여 봇 토큰을 받으세요.
MCU 스케치: 이전 Bridge 섹션의 동일한 MCU 스케치를 유지합니다 — 변경 사항 없음. STM32에서 이미 업로드되고 실행 중인지 확인하세요.
Python 스크립트 (Arduino App Lab) — SSD1309 OLED용 Telegram 봇:
- 참고: YOUR_BOT_TOKEN을 Telegram의 @BotFather에서 받은 토큰으로 바꾸세요.
- /display Hello 보내기 — OLED에 나타납니다.
- /clear — OLED를 지웁니다.
- /status — 봇이 현재 텍스트로 응답합니다.
App Lab 콘솔 출력
ArduinoBot
OpenClaw 통합
이 튜토리얼을 OpenClaw에 적용할 수 있습니다 아두이노 우노 Q - OpenClaw 튜토리얼의 지침을 참조합니다.
응용 프로그램/프로젝트 아이디어
- 큰 텍스트 알림 표시: 텍스트 크기 3 또는 4를 사용하여 전체 2.42인치 화면에 단일 중요 값(온도, 전압) 표시
- 원격 정보 보드: Telegram 그룹에서 OLED에 메시지를 푸시하여 팀 공지를 표시
- 데이터 로거 상태: MPU가 CSV 파일에 쓸 때 OLED에 마지막 레코드 타임스탬프 및 행 개수 표시
- Wi-Fi 신호 강도 계: 큰 2.42인치 화면에 MPU Wi-Fi SSID 및 RSSI 강도 표시
- 사용자 정의 아이콘 렌더링: drawBitmap()를 사용하여 MCU 스케치에 바이트 배열로 저장된 로고 또는 경고 아이콘 표시
자신을 도전해보세요
- 쉬움: 제목/본문 레이아웃을 만들기 위해 첫 번째 줄에 setTextSize(2)를 사용하고 후속 줄에 setTextSize(1)을 사용하도록 스케치를 수정합니다.
- 중간: Telegram 명령 /contrast <0-255>를 추가하여 display.ssd1309_command(SSD1309_SETCONTRAST) 호출 후 값을 추가하여 화면 밝기를 조정합니다.
- 고급: fillRect()를 사용하여 OLED에 실시간 막대 차트를 표시하고 Bridge를 통해 MPU에서 전송된 센서 데이터에서 업데이트합니다.