Built-in Sensors(내장 센서)

Codi:bit 보드의 내장 센서들을 제어하는 API입니다.

Table of Contents

유틸리티 (Utils)
버튼 (Buttons)
RGB LED
버저 (Buzzer)
마이크 (Microphone)
주변광 센서 (Light Sensor)
디스플레이 (Display)
이미지 (Image)
가속도계 (Accelerometer)
Magnetometer
자이로스코프 (Gyroscope)

유틸리티 (Utils)

내장 센서와 함께 작동하는 유틸리티 함수들의 API입니다.

`get_board_temperature()`

QMI8658 IMU 센서에서 현재 보드 온도를 읽어옵니다.

반환값:

int: 현재 보드 온도 (섭씨, 정수) 센서 오류 시 25를 반환합니다

예시:

temp = get_board_temperature()
print(f"현재 보드 온도: {temp}°C")

하드웨어 정보:

센서: QMI8658 6축 IMU (온도 센서)
인터페이스: I2C
주소: 0x6B
온도 범위: -40°C ~ 85°C
해상도: 0.01°C
정확도: ±1°C
측정 유형: 보드 온도 (주변 온도 아님)

주의사항:

보드 온도: 주변 환경이 아닌 보드 자체의 온도를 측정합니다
높은 값: 부품 발열로 인해 주변 온도보다 일반적으로 높게 측정됩니다
에러 처리: 센서 통신 실패 시 25°C를 반환합니다
범위 검증: -40°C ~ 85°C 범위를 벗어나는 값은 25°C를 반환합니다
정수 반환: 메모리 효율성을 위해 정수 값을 반환합니다
조용한 실패: 하드웨어 오류 시 기본값으로 조용히 실패합니다

버튼 (Buttons)

Codi:bit 보드의 내장 버튼을 제어하는 API입니다.

전역 인스턴스

from codibit import button_a, button_b

button_a  # 버튼 A
button_b  # 버튼 B

메서드

`button.is_pressed()`

버튼이 현재 눌려있는지 확인합니다.

반환값:

bool: 버튼이 현재 눌려있으면 True, 그렇지 않으면 False

예시:

if button_a.is_pressed():
    print("버튼 A가 눌려있습니다")

`button.was_pressed()`

마지막 호출 이후 또는 장치 시작 이후 버튼이 눌렸는지 확인합니다.

반환값:

bool: 버튼이 눌렸으면 True, 그렇지 않으면 False

예시:

if button_a.was_pressed():
    print("버튼 A가 눌렸습니다")

`button.get_presses()`

마지막 호출 이후 또는 장치 시작 이후의 총 버튼 눌림 횟수를 반환하고 카운터를 0으로 리셋합니다.

반환값:

int: 버튼 눌림 횟수

예시:

presses = button_a.get_presses()
print(f"버튼 A가 {presses}번 눌렸습니다")

`button.get_press_count()`

현재까지 누적된 총 버튼 눌림 횟수를 반환합니다. 카운터는 리셋되지 않습니다.

반환값:

int: 누적된 버튼 눌림 횟수

예시:

total_presses = button_a.get_press_count()
print(f"버튼 A가 총 {total_presses}번 눌렸습니다")

메서드 비교

메서드	기능	카운터 리셋	사용 시나리오
`is_pressed()`	현재 눌림 상태 확인	-	연속적인 동작 (버튼을 계속 누르고 있을 때)
`was_pressed()`	이벤트 감지	-	단일 이벤트 (메뉴 선택)
`get_presses()`	누름 횟수 반환 후 리셋	✅	주기적인 카운팅 (5초마다 누름 횟수 확인)
`get_press_count()`	누적 누름 횟수 확인	❌	실시간 누적 카운팅 (총 누름 횟수 추적)

하드웨어 정보

타입: 택틸 푸시 버튼
풀업 저항: 10KΩ (하드웨어)
활성 상태: LOW (눌림 = 0V, 뗌 = 3.3V)
디바운스 시간: 50ms (소프트웨어)
핀 할당: 버튼 A (GPIO0), 버튼 B (GPIO2)
물리적 위치: 보드 앞면, A와 B로 라벨 표시

주의사항

디바운싱: 하드웨어 버튼 바운싱은 50ms 디바운스 시간으로 자동 처리됩니다
풀업: 내장 10KΩ 풀업 저항으로 눌리지 않았을 때 안정적인 HIGH 상태를 보장합니다
상태 추적: was_pressed(), get_presses(), get_press_count() 메서드는 버튼 이벤트를 자동으로 추적합니다
카운터 관리: get_presses()는 카운터를 리셋하지만, get_press_count()는 리셋하지 않습니다

RGB LED

내장 RGB LED 스트립(3개 LED)을 제어하는 API입니다.

전역 인스턴스

from codibit import rgb_led

rgb_led  # 내장 RGB LED 스트립

메서드

`rgb_led.set_color(strip_id, r, g, b)`

특정 LED 스트립의 색상을 설정합니다.

매개변수:

strip_id (int): LED 스트립 번호 (0, 1, 2)
r (int): 빨간색 값 (0-255)
g (int): 초록색 값 (0-255)
b (int): 파란색 값 (0-255)

예시:

# 스트립 0을 빨간색, 스트립 1을 초록색, 스트립 2를 파란색으로 설정
rgb_led.set_color(0, 255, 0, 0)    # 빨간색
rgb_led.set_color(1, 0, 255, 0)    # 초록색
rgb_led.set_color(2, 0, 0, 255)    # 파란색
rgb_led.show()

`rgb_led.get_color(strip_id)`

특정 LED 스트립의 현재 색상을 가져옵니다.

매개변수:

strip_id (int): LED 스트립 번호 (0, 1, 2)

반환값:

tuple: (r, g, b) 색상 값

예시:

# 스트립 0의 현재 색상 가져오기
current_color = rgb_led.get_color(0)
print(f"스트립 0 색상: {current_color}")  # (r, g, b) 튜플 반환

`rgb_led.set_all_color(r, g, b)`

모든 LED 스트립을 같은 색상으로 설정합니다.

매개변수:

r (int): 빨간색 값 (0-255)
g (int): 초록색 값 (0-255)
b (int): 파란색 값 (0-255)

예시:

# 모든 스트립을 흰색으로 설정
rgb_led.set_all_color(255, 255, 255)
rgb_led.show()

# 모든 스트립을 빨간색으로 설정
rgb_led.set_all_color(255, 0, 0)
rgb_led.show()

`rgb_led.set_brightness(strip_id, brightness)`

특정 LED 스트립의 밝기만 설정합니다. 현재 색상은 유지됩니다.

매개변수:

strip_id (int): LED 스트립 번호 (0, 1, 2)
brightness (float): 밝기 (0.0-1.0)

예시:

# 스트립 0을 빨간색으로 설정
rgb_led.set_color(0, 255, 0, 0)
# 밝기를 50%로 설정
rgb_led.set_brightness(0, 0.5)
rgb_led.show()

`rgb_led.set_all_brightness(brightness)`

모든 LED 스트립의 밝기를 동일하게 설정합니다. 현재 색상들은 유지됩니다.

매개변수:

brightness (float): 밝기 (0.0-1.0)

예시:

# 각 스트립을 다른 색상으로 설정
rgb_led.set_color(0, 255, 0, 0)    # 빨간색
rgb_led.set_color(1, 0, 255, 0)    # 초록색
rgb_led.set_color(2, 0, 0, 255)    # 파란색
# 모든 스트립을 50% 밝기로 설정
rgb_led.set_all_brightness(0.5)
rgb_led.show()

`rgb_led.turn_off(strip_id)`

특정 LED 스트립을 끕니다.

매개변수:

strip_id (int): LED 스트립 번호 (0, 1, 2)

예시:

# 스트립 1을 끄기
rgb_led.turn_off(1)
rgb_led.show()

`rgb_led.turn_off_all()`

모든 LED 스트립을 끕니다.

예시:

# 모든 스트립을 끄기
rgb_led.turn_off_all()
rgb_led.show()

`rgb_led.show()`

설정된 색상과 밝기를 실제 LED 하드웨어에 적용합니다.

매개변수:

없음

예시:

# 색상 설정 후 변경사항 적용
rgb_led.set_color(0, 255, 0, 0)  # 빨간색 설정
rgb_led.show()  # 변경사항 적용

# 여러 설정 후 한 번에 적용
rgb_led.set_color(0, 255, 0, 0)    # 빨간색
rgb_led.set_color(1, 0, 255, 0)    # 초록색
rgb_led.set_color(2, 0, 0, 255)    # 파란색
rgb_led.show()  # 모든 변경사항 적용

주의사항:

색상이나 밝기를 변경한 후에는 반드시 show()를 호출해야 합니다
show()를 호출하지 않으면 변경사항이 LED에 반영되지 않습니다
여러 설정을 한 후 마지막에 한 번만 show()를 호출하면 됩니다

하드웨어 정보

타입: WS2812B RGB LED 스트립
LED 개수: 3개 LED 직렬 연결
핀 할당: GPIO17
전원 공급: 3.3V
데이터 프로토콜: WS2812B 프로토콜
색상 깊이: 24-bit (색상당 8-bit)
밝기 제어: PWM 기반 밝기 제어

주의사항

색상 범위: 각 색상 구성요소(R, G, B)는 0-255 범위입니다
밝기 제어: 밝기는 모든 색상 구성요소에 비례적으로 적용됩니다
전력 효율성: 낮은 밝기는 전력 소모를 줄입니다
업데이트 필요: 색상 설정 후 show()를 호출하여 변경사항을 적용해야 합니다
스트립 번호: 스트립은 왼쪽부터 0, 1, 2로 번호가 매겨집니다
색상 혼합: RGB 값들이 혼합되어 다양한 색상을 만듭니다

버저 (Buzzer)

Codi:bit 보드의 내장 버저를 제어하는 API입니다.

전역 인스턴스

from codibit import buzzer

buzzer  # 내장 버저

음표 표기법

음표는 NOTE[octave][:duration] 형식으로 표현됩니다.

음표 형식:

'c4:4'    # C4 음을 4틱 동안
'g'        # G4 음을 기본 지속시간(4틱) 동안
'r:2'      # 2틱 동안 쉼표
'eb:8'     # E♭4 음을 8틱 동안
'f#5:1'    # F#5 음을 1틱 동안

지원하는 음표:

기본 음표: c, d, e, f, g, a, b
플랫: cb, db, eb, fb, gb, ab, bb
샵: c#, d#, e#, f#, g#, a#, b#
옥타브: 3, 4(기본), 5
쉼표: r (rest)

템포 시스템:

기본값: 4틱, 120 BPM
1틱 = 60000 / BPM / ticks_per_beat 밀리초
기본값으로 1틱 = 125ms, 1박자 = 500ms

`Sound`

실용적인 소리와 드럼 소리 타입 상수들입니다.

실용적인 소리들:

Sound.BEEP
Sound.CHIME
Sound.ALERT
Sound.NOTIFICATION
Sound.SUCCESS
Sound.ERROR
Sound.CLICK
Sound.TICK

드럼 소리들:

Sound.DRUM_KICK
Sound.DRUM_SNARE
Sound.DRUM_HIHAT
Sound.DRUM_TOM1
Sound.DRUM_TOM2
Sound.DRUM_TOM3
Sound.DRUM_FLOOR_TOM
Sound.DRUM_CRASH
Sound.DRUM_RIDE
Sound.DRUM_HIHAT_OPEN
Sound.DRUM_HIHAT_CLOSED
Sound.DRUM_CHINA
Sound.DRUM_SPLASH
Sound.DRUM_COWBELL
Sound.DRUM_CLAP
Sound.DRUM_SHAKER

`Melody`

내장 멜로디 정의들입니다.

from codibit import Melody

Melody.HAPPY_BIRTHDAY  # 생일 축하합니다
Melody.TWINKLE_TWINKLE # 반짝반짝 작은 별
Melody.MARY_HAD_A_LITTLE_LAMB  # 비행기

메서드

`buzzer.play_tone(frequency, duration_ms=1000)`

지정된 주파수로 음을 재생합니다. 지정된 시간 후 자동으로 정지됩니다.

매개변수:

frequency (int): 주파수 (Hz)
duration_ms (int): 재생 시간 (밀리초, 기본값: 1000)

예시:

buzzer.play_tone(440, 1000)      # 440Hz를 1초간 재생 (자동 정지)
buzzer.play_tone(262, 500)       # C4 음을 0.5초간 재생 (자동 정지)

`buzzer.play_melody(melody, tempo=None)`

음표 문자열을 사용하여 멜로디를 재생합니다.

매개변수:

melody (list): 음표 문자열 리스트 (예: ['c4:4', 'd4:4', 'e4:8'])
tempo (int, optional): BPM 단위의 템포, None이면 기본값 사용

내장 멜로디:

from codibit import Melody

# 사용 가능한 내장 멜로디
Melody.HAPPY_BIRTHDAY
Melody.TWINKLE_TWINKLE
Melody.MARY_HAD_A_LITTLE_LAMB

예시:

# 사용자 정의 멜로디
buzzer.play_melody(['c4:4', 'd4:4', 'e4:4', 'f4:4', 'g4:8'], tempo=120)

# 내장 멜로디
from codibit import Melody
buzzer.play_melody(Melody.HAPPY_BIRTHDAY, tempo=200)

`buzzer.play_sound(sound_type)`

미리 정의된 소리를 재생합니다.

매개변수:

sound_type (str | Sound): Sound 클래스 상수 중 하나

예시:

buzzer.play_sound(Sound.BEEP)
buzzer.play_sound(Sound.DRUM_KICK)

`buzzer.stop()`

현재 재생 중인 소리를 정지합니다.

예시:

buzzer.play_tone(440, 5000)  # 5초간 재생
buzzer.stop()  # 즉시 정지

`buzzer.set_tempo(ticks=4, bpm=120)`

템포를 설정합니다.

매개변수:

ticks (int): 박자당 틱 수 (기본값: 4)
bpm (int): 분당 박자 수 (기본값: 120)

예시:

buzzer.set_tempo(bpm=180)  # 빠른 템포로 설정
buzzer.play_melody(['c4:4', 'd4:4', 'e4:4', 'f4:4', 'g4:8'])

`buzzer.get_tempo()`

현재 템포를 반환합니다.

반환값:

tuple: (ticks, bpm)

예시:

ticks, bpm = buzzer.get_tempo()
print(f"현재 템포: {bpm} BPM, {ticks}틱")

`buzzer.set_volume(volume)`

버저 볼륨을 설정합니다.

매개변수:

volume (int): 볼륨 레벨 (0-3)
- 0: 음소거
- 1: 작게
- 2: 중간 (기본값)
- 3: 크게

예시:

buzzer.set_volume(3)  # 크게로 설정
buzzer.play_tone(440, 1000)

하드웨어 정보

타입: 압전 버저
핀 할당: GPIO16
PWM 주파수 범위: 20Hz - 20kHz
볼륨 제어: PWM 듀티 사이클 (0-900)
전원 공급: 3.3V
물리적 위치: 보드 앞면

주의사항

볼륨 제어: 볼륨은 PWM 듀티 사이클로 제어되며, 최대 듀티 사이클은 900입니다
중단 가능: 모든 멜로디와 곡 재생은 Ctrl+C로 중단할 수 있습니다
템포 제어: 템포는 BPM (분당 비트 수)로 지정됩니다
음표 표기법: 음표는 NOTE[octave][:duration] 형식을 사용하세요
소리 타입: 8가지 실용적인 소리와 16가지 드럼 소리를 사용할 수 있습니다
드럼 사운드: 16가지 다양한 드럼 소리를 제공합니다
틱 시스템: 음악의 기본 시간 단위는 틱이며, 템포에 따라 길이가 결정됩니다

마이크 (Microphone)

내장 마이크 센서를 제어하는 API입니다.

전역 인스턴스

from codibit import microphone

microphone  # 내장 마이크 센서

메서드

`microphone.read()`

마이크 센서의 원시 ADC 값을 반환합니다.

반환값:

int: 원시 ADC 값 (0-4095)

예시:

value = microphone.read()
print(f"원시 값: {value}")

`microphone.get_level()`

정규화된 소리 레벨을 반환합니다.

반환값:

int: 0부터 9까지의 소리 레벨, 여기서:
- 0: 매우 조용함
- 1-2: 조용함
- 3-4: 보통
- 5-6: 시끄러움
- 7-8: 매우 시끄러움
- 9: 극도로 시끄러움

예시:

level = microphone.get_level()
print(f"소리 레벨: {level}")

`microphone.is_sound_detected()`

소리가 감지되는지 확인합니다.

반환값:

bool: 소리가 감지되면 True, 그렇지 않으면 False

예시:

if microphone.is_sound_detected():
    print("소리가 감지되었습니다!")

`microphone.is_loud()`

소리 레벨이 큰지 확인합니다.

반환값:

bool: 소리 레벨이 7 이상이면 True, 그렇지 않으면 False

예시:

if microphone.is_loud():
    print("너무 시끄럽습니다!")

`microphone.is_quiet()`

소리 레벨이 조용한지 확인합니다.

반환값:

bool: 소리 레벨이 2 이하면 True, 그렇지 않으면 False

예시:

if microphone.is_quiet():
    print("매우 조용합니다.")

하드웨어 정보

센서: 내장 마이크 센서
측정 범위: 0-4095 (12-bit ADC)
레벨 변환: 0-4095 → 0-9 (10단계)
자동 보정: 주변 소음에 자동으로 보정
응답 시간: < 1ms

주의사항

자동 보정: 센서는 주변 환경에 자동으로 보정됩니다
소리 감지: 소리 레벨의 갑작스러운 변화에 가장 민감합니다
임계값: 시끄러운 소리는 보통 레벨 7 이상으로 기록됩니다
환경: 상대적으로 조용한 환경에서 가장 잘 작동합니다

주변광 센서 (Light Sensor)

주변광 센서(ALS-PT19)를 제어하는 API입니다.

전역 인스턴스

from codibit import light

light

메서드

`light.read()`

조도 센서의 원시 값을 읽습니다.

반환값:

int: 조도 값 (0-4095)

예시:

value = light.read()

`light.read_level()`

조도 레벨을 읽습니다.

반환값:

int: 조도 레벨 (0-9)

레벨:

0: 매우 어두움
1-2: 어두움
3-6: 보통
7-8: 밝음
9: 매우 밝음

예시:

level = light.read_level()

하드웨어 정보

센서: ALS-PT19 주변광 센서
측정 범위: 0-4095 (12-bit ADC)
레벨 변환: 0-4095 → 0-9 (10단계)
응답 시간: < 1ms
전력 소모: 매우 낮음

주의사항

환경 영향: 주변 조명에 따라 값이 달라질 수 있습니다
반사: 센서 주변의 반사 물체가 측정에 영향을 줄 수 있습니다
온도: 극한 온도에서는 정확도가 떨어질 수 있습니다
초기화: 센서는 보드 전원 공급 시 자동으로 초기화됩니다

디스플레이 (Display)

내장 SH1106 OLED 디스플레이(128x64 픽셀)를 제어하는 API입니다. 버퍼 기반 작동 방식으로, 그리기 명령을 버퍼에 저장한 후 show() 함수로 화면에 출력합니다.

전역 인스턴스

from codibit import display

display

기본 제어 메서드

`display.clear()`

버퍼만 지우고 출력은 하지 않습니다. 성능 최적화를 위해 여러 그리기 작업 전에 사용할 수 있습니다.

예시:

# 성능 최적화를 위한 사용법
display.clear()  # 버퍼만 지우기
display.draw_text("Hello", 0, 0)
display.draw_circle(32, 32, 10)
display.show()  # 마지막에 한 번만 출력

`display.clear_immediate()`

화면을 지우고 바로 출력에 반영합니다. 모든 픽셀을 0(꺼짐)으로 설정합니다.

예시:

display.clear_immediate()  # 즉시 화면 지우기

`display.show()`

버퍼의 내용을 화면에 출력합니다. 그리기 작업 후 반드시 호출해야 화면에 표시됩니다.

예시:

display.draw_text("Hello", 0, 0)
display.draw_circle(32, 32, 10)
display.show()  # 화면에 출력

픽셀 제어

`display.get_pixel(x, y)`

지정된 좌표의 픽셀 상태를 반환합니다.

매개변수:

x (int): X 좌표 (0-127)
y (int): Y 좌표 (0-63)

반환값:

int: 픽셀 상태 (0 또는 1)

예시:

pixel_state = display.get_pixel(10, 20)
print(f"픽셀 상태: {pixel_state}")

`display.set_pixel(x, y, val)`

지정된 좌표의 픽셀 상태를 설정합니다.

매개변수:

x (int): X 좌표 (0-127)
y (int): Y 좌표 (0-63)
val (int): 픽셀 상태 (0 또는 1)

예시:

display.set_pixel(10, 20, 1)  # 픽셀을 켬
display.show()

그리기 메서드

`display.draw_text(text, x, y)`

지정된 위치에 텍스트를 그립니다.

매개변수:

text (str): 그릴 텍스트
x (int): X 좌표
y (int): Y 좌표

예시:

display.draw_text("Hello", 0, 0)
display.draw_text("World", 0, 10)
display.show()

`display.draw_rectangle(x, y, w, h, fill=False)`

사각형을 그립니다.

매개변수:

x (int): 왼쪽 상단 모서리의 X 좌표
y (int): 왼쪽 상단 모서리의 Y 좌표
w (int): 너비
h (int): 높이
fill (bool): 채우기 여부 (기본값: False)

예시:

# 빈 사각형
display.draw_rectangle(10, 10, 20, 15)
# 채워진 사각형
display.draw_rectangle(40, 10, 20, 15, fill=True)
display.show()

`display.draw_line(x1, y1, x2, y2)`

두 점 사이에 선을 그립니다.

매개변수:

x1 (int): 시작점의 X 좌표
y1 (int): 시작점의 Y 좌표
x2 (int): 끝점의 X 좌표
y2 (int): 끝점의 Y 좌표

예시:

display.draw_line(0, 0, 50, 50)
display.draw_line(0, 50, 50, 0)
display.show()

`display.draw_circle(x, y, r, fill=False)`

원을 그립니다.

매개변수:

x (int): 중심의 X 좌표
y (int): 중심의 Y 좌표
r (int): 반지름
fill (bool): 채우기 여부 (기본값: False)

예시:

# 빈 원
display.draw_circle(32, 32, 10)
# 채워진 원
display.draw_circle(64, 32, 8, fill=True)
display.show()

`display.draw_triangle(x1, y1, x2, y2, x3, y3, fill=False)`

삼각형을 그립니다.

매개변수:

x1, y1 (int): 첫 번째 꼭지점의 좌표
x2, y2 (int): 두 번째 꼭지점의 좌표
x3, y3 (int): 세 번째 꼭지점의 좌표
fill (bool): 채우기 여부 (기본값: False)

예시:

# 빈 삼각형
display.draw_triangle(10, 10, 20, 40, 40, 40)
# 채워진 삼각형
display.draw_triangle(50, 10, 60, 40, 80, 40, fill=True)
display.show()

이미지

`display.draw_image(image, x, y, scale=1)`

지정된 위치에 이미지를 그립니다. scale 매개변수로 이미지 크기를 조정할 수 있습니다.

매개변수:

image: Image 객체
x (int): 시작 X 좌표
y (int): 시작 Y 좌표
scale (int): 스케일 크기 (1=원본 크기, 2=2배, 3=3배), 기본값: 1

예시:

from codibit import Image

# 내장 이미지 그리기 (원본 크기)
display.draw_image(Image.HEART, 0, 0)
display.draw_image(Image.HAPPY, 20, 0)

# 이미지 확대해서 그리기
display.draw_image(Image.HEART, 0, 20, scale=2)  # 2배 크기
display.draw_image(Image.HAPPY, 40, 20, scale=3)  # 3배 크기
display.show()

하드웨어 정보

디스플레이: SH1106 OLED
해상도: 128x64 픽셀
색상: 단색 (흰색/검은색)
인터페이스: I2C
주소: 0x3C
회전: 180도 (화면이 올바른 방향으로 표시)
전원 공급: 3.3V
물리적 위치: 보드 앞면

작동 방식

버퍼 기반: 모든 그리기 명령은 내부 버퍼에 저장됩니다
지연 출력: show() 함수를 호출해야 화면에 출력됩니다
성능 최적화: 여러 그리기 작업을 한 번에 처리한 후 출력 가능
메모리 효율: 버퍼 사용으로 메모리 사용량 최적화

사용 패턴

# 1. 화면 지우기
display.clear()

# 2. 여러 그리기 작업 수행
display.draw_text("Hello", 0, 0)
display.draw_circle(32, 32, 10)
display.draw_rectangle(10, 10, 20, 15)

# 3. 화면에 출력
display.show()

주의사항

픽셀 좌표: 원점 (0,0)은 왼쪽 상단 모서리입니다
픽셀 값: 0(꺼짐) 또는 1(켜짐)만 지원합니다
버퍼 출력: 그리기 작업 후 반드시 show()를 호출해야 화면에 표시됩니다
내장 이미지: 64가지 다양한 이미지를 사용할 수 있습니다 (Image 섹션 참조)
스케일링: 이미지는 더 나은 가시성을 위해 표시할 때 확대할 수 있습니다
성능: 여러 그리기 작업을 한 번에 처리한 후 show()를 호출하는 것이 효율적입니다
버퍼 제어: clear()는 버퍼만 지우지만, clear_immediate()는 즉시 출력하여 성능 최적화에 유용합니다

이미지 (Image)

디스플레이용 이미지를 생성하고 조작하는 API입니다.

사용법

from codibit import Image

이미지 생성

`Image(width, height)`

지정된 크기의 빈 이미지를 생성합니다.

매개변수:

width (int): 이미지 너비
height (int): 이미지 높이

예시:

img = Image(5, 5)  # 5x5 빈 이미지 생성

`Image(string)`

문자열 표현에서 이미지를 생성합니다.

매개변수:

string (str): "행1:행2:행3:..." 형식의 이미지 문자열

예시:

heart = Image('01010:11111:11111:01110:00100:')

메서드

`image.set_pixel(x, y, value)`

이미지의 픽셀 상태를 설정합니다.

매개변수:

x (int): X 좌표
y (int): Y 좌표
value (int): 픽셀 상태 (0 또는 1)

예시:

img = Image(5, 5)
img.set_pixel(2, 2, 1)  # 중앙 픽셀을 켬

`image.get_pixel(x, y)`

이미지의 픽셀 상태를 반환합니다.

매개변수:

x (int): X 좌표
y (int): Y 좌표

반환값:

int: 픽셀 상태 (0 또는 1)

예시:

pixel_state = img.get_pixel(2, 2)

`image.width()`

이미지의 너비를 반환합니다.

반환값:

int: 이미지 너비

예시:

width = img.width()

`image.height()`

이미지의 높이를 반환합니다.

반환값:

int: 이미지 높이

예시:

height = img.height()

`image.shift_left(n)`

이미지를 왼쪽으로 n픽셀 이동시킵니다.

매개변수:

n (int): 이동할 픽셀 수

반환값:

Image: 새로 이동된 이미지

예시:

shifted = img.shift_left(1)

`image.shift_right(n)`

이미지를 오른쪽으로 n픽셀 이동시킵니다.

매개변수:

n (int): 이동할 픽셀 수

반환값:

Image: 새로 이동된 이미지

예시:

shifted = img.shift_right(1)

`image.shift_up(n)`

이미지를 위로 n픽셀 이동시킵니다.

매개변수:

n (int): 이동할 픽셀 수

반환값:

Image: 새로 이동된 이미지

예시:

shifted = img.shift_up(1)

`image.shift_down(n)`

이미지를 아래로 n픽셀 이동시킵니다.

매개변수:

n (int): 이동할 픽셀 수

반환값:

Image: 새로 이동된 이미지

예시:

shifted = img.shift_down(1)

내장 이미지

Image 클래스는 디스플레이에서 사용할 수 있는 64개의 내장 이미지를 제공합니다. 시각적 미리보기가 포함된 완전한 참조는 내장 이미지을 참조하세요.

예시 이미지

이미지	미리보기	이미지	미리보기	이미지	미리보기
`Image.HEART`		`Image.HAPPY`		`Image.STAR`
`Image.SAD`		`Image.DIAMOND`		`Image.RABBIT`

이미지 카테고리

기본 이미지: HEART, HAPPY, SAD, STAR, CONFUSED, ANGRY, SURPRISED 등
기하학적 도형: TRIANGLE, DIAMOND, SQUARE, CHESSBOARD 등
동물 및 캐릭터: RABBIT, COW, DUCK, GHOST, GIRAFFE 등
도구 및 물건: SWORD, UMBRELLA, HOUSE, TARGET 등
음악: MUSIC_CROTCHET, MUSIC_QUAVER, PITCHFORK 등
시계 얼굴: 시간 애니메이션을 위한 CLOCK1부터 CLOCK12까지
화살표: 8방향 화살표 (N, NE, E, SE, S, SW, W, NW)

📖 모든 64개 이미지와 시각적 미리보기가 포함된 완전한 참조는 내장 이미지을 참조하세요.

디스플레이와 함께 사용

이미지는 디스플레이와 원활하게 작동하도록 설계되었습니다:

예시:

from codibit import display, Image

# 내장 이미지 그리기
display.draw_image(Image.HEART, 0, 0)
display.draw_image(Image.HAPPY, 20, 0)
display.show()

# 사용자 정의 이미지 생성 및 그리기
custom = Image('10001:01010:00100:01010:10001:')
display.draw_image(custom, 0, 20)
display.show()

# 이미지 스케일링
display.draw_image(Image.HEART, 0, 0, scale=2)
display.draw_image(Image.HAPPY, 40, 0, scale=3)
display.show()

이미지 리스트

Image 클래스는 애니메이션과 반복 작업을 위한 편리한 이미지 리스트를 제공합니다:

`Image.ALL_CLOCKS`

시계 애니메이션을 위한 12개의 시계 이미지 리스트입니다.

예시:

# 시계 바늘 회전 애니메이션
for clock in Image.ALL_CLOCKS:
    display.clear()
    display.draw_image(clock, 0, 0)
    display.show()
    time.sleep(0.1)

`Image.ALL_ARROWS`

8방향 화살표 이미지 리스트입니다. 회전하는 화살표 애니메이션에 유용합니다.

예시:

# 회전하는 화살표 애니메이션
for arrow in Image.ALL_ARROWS:
    display.clear()
    display.draw_image(arrow, 0, 0)
    display.show()
    time.sleep(0.2)

# 랜덤 화살표 선택
import random
random_arrow = random.choice(Image.ALL_ARROWS)
display.draw_image(random_arrow, 0, 0, scale=2)

주의사항

문자열 형식: 이미지는 ':'로 행을 구분하는 문자열에서 생성할 수 있습니다
픽셀 상태: 0-1 스케일 (0=꺼짐, 1=켜짐)
내장 이미지: 즉시 사용할 수 있는 64가지 다양한 이미지
호환성: API는 Image 인터페이스와 호환됩니다
디스플레이 통합: 이미지는 draw_image() 메서드로 디스플레이에 그릴 수 있습니다
스케일링: 이미지는 draw_image() 메서드로 더 나은 가시성을 위해 확대할 수 있습니다
버퍼 기반: 이미지 그리기도 버퍼 기반으로 작동하므로 show() 호출이 필요합니다

가속도계 (Accelerometer)

내장 QMI8658 가속도계 센서를 제어하는 API입니다.

전역 인스턴스

from codibit import accelerometer

accelerometer

메서드

`accelerometer.get_x()`

X축 가속도 값을 반환합니다.

반환값:

int: X축 가속도 값

예시:

x_value = accelerometer.get_x()
print(f"X축 가속도: {x_value}")

`accelerometer.get_y()`

Y축 가속도 값을 반환합니다.

반환값:

int: Y축 가속도 값

예시:

y_value = accelerometer.get_y()
print(f"Y축 가속도: {y_value}")

`accelerometer.get_z()`

Z축 가속도 값을 반환합니다.

반환값:

int: Z축 가속도 값

예시:

z_value = accelerometer.get_z()
print(f"Z축 가속도: {z_value}")

`accelerometer.get_values()`

세 축의 가속도 값 튜플을 반환합니다.

반환값:

tuple: (x, y, z) 가속도 값들

예시:

x, y, z = accelerometer.get_values()
print(f"가속도: X={x}, Y={y}, Z={z}")

`accelerometer.get_strength()`

가속도의 크기(총 가속도 강도)를 반환합니다.

반환값:

int: 가속도 크기

예시:

strength = accelerometer.get_strength()
print(f"가속도 강도: {strength}")

`accelerometer.get_gesture()`

보드의 현재 제스처 상태를 반환합니다.

반환값:

str: 현재 제스처 상태
- "FREE_FALL": 보드가 자유낙하 중
- "SHAKE": 보드가 흔들리고 있음
- "FACE_UP": 보드가 평평하고 화면이 위쪽
- "FACE_DOWN": 보드가 평평하고 화면이 아래쪽
- "UP": 보드가 세워져 있고 화면이 앞쪽
- "DOWN": 보드가 세워져 있고 화면이 뒤쪽
- "LEFT": 보드가 왼쪽으로 기울어짐
- "RIGHT": 보드가 오른쪽으로 기울어짐

Face Up and Face Down

CodiBit Gesture: Face Up and Face Down

Up, Down, Left, Right

CodiBit Gesture: Up, Down, Left, Right

예시:

gesture = accelerometer.get_gesture()
print(f"현재 제스처: {gesture}")

`accelerometer.is_gesture(name)`

지정된 제스처가 현재 활성화되어 있는지 확인합니다.

매개변수:

name (str): 확인할 제스처 이름

반환값:

bool: 제스처가 현재 활성화되어 있으면 True, 아니면 False

예시:

if accelerometer.is_gesture("FACE_UP"):
    print("보드가 위쪽을 향하고 있습니다")

`accelerometer.was_gesture(name)`

마지막 호출 이후 지정된 제스처가 활성화되었는지 확인합니다.

매개변수:

name (str): 확인할 제스처 이름

반환값:

bool: 마지막 호출 이후 제스처가 활성화되었으면 True, 아니면 False

예시:

if accelerometer.was_gesture("SHAKE"):
    print("흔들림 감지됨!")

하드웨어 정보

센서: QMI8658 6축 IMU
인터페이스: I2C
주소: 0x6B
측정 범위: ±2g, ±4g, ±8g, ±16g
해상도: 16-bit
업데이트 속도: 최대 200Hz
전원 공급: 3.3V
물리적 위치: 보드에 통합

좌표계

Codi:bit 보드의 가속도계는 보드의 실제 물리적 방향을 기준으로 동작합니다:

축 방향

X축: 앞뒤 기울기 (Tilt forward and backward)
- 앞으로 기울일 때 양수, 뒤로 기울일 때 음수
Y축: 좌우 기울기 (Tilt left and right)
- 왼쪽으로 기울일 때 양수, 오른쪽으로 기울일 때 음수
Z축: 상하 뒤집기 (Flip up and down)
- 평평한 상태에서 약 -1.0, 뒤집으면 약 +1.0

중력 기준

보드가 평평하게 놓여있을 때 중력은 -Z 방향으로 작용
정지 상태에서 Z축은 약 -1.0 (중력과 반대 방향)
보드를 뒤집으면 Z축은 약 +1.0 (중력과 같은 방향)

측정값 범위

일반 범위: -2.0 ~ +2.0 (중력의 약 2배까지 측정)
정지 상태: -1.0 ~ +1.0 (중력만 작용)
기울기 감지: 각 축은 해당 방향의 기울기에 따라 중력 성분이 분해되어 측정

주의사항

보정: 센서는 중력에 자동으로 보정됩니다
중력: 정지 상태에서는 Z축이 보통 ~1g(중력)를 보여줍니다
움직임 감지: 전체적인 움직임을 감지하려면 get_strength()를 사용하세요
축 값: 개별 축 값은 양수 또는 음수일 수 있습니다
샘플링: 값은 센서의 설정된 속도로 업데이트됩니다
노이즈: 센서 노이즈로 인한 작은 변화는 정상입니다
제스처 감지: 고급 제스처 인식을 위해 get_gesture(), is_gesture(), was_gesture()를 사용하세요
제스처 우선순위: SHAKE가 최고 우선순위, 그 다음 FREE_FALL, 마지막으로 방향 제스처 순입니다

Magnetometer

Codi:bit의 자기장 센서를 제어하는 API입니다. MMC5603 자기장 센서를 사용하여 3축 자기장을 측정하고 나침반 기능을 제공합니다.

전역 인스턴스

from codibit import magnetometer

magnetometer  # 내장 자기장 센서

기본 사용법

from codibit import *

# 자기장 센서 보정 (사용 전 필수)
print("자기장 센서 보정을 시작합니다...")
print("보드를 공중에 들고 천천히 8자를 여러 번 그려주세요")
print("약 20초 동안 보정이 진행됩니다...")
magnetometer.calibrate()
print("보정 완료!")

# 자기장 값 읽기
x = magnetometer.get_x()
y = magnetometer.get_y()
z = magnetometer.get_z()

# 나침반 방향 읽기
heading = magnetometer.get_heading()

메서드

`magnetometer.calibrate()`

자기장 센서를 보정합니다. 정확한 측정을 위해 보드를 공중에 들고 천천히 8자를 여러 번 그리는 방법으로 20초 정도 보정을 수행합니다.

예시:

print("자기장 센서 보정을 시작합니다...")
print("보드를 공중에 들고 천천히 8자를 여러 번 그려주세요")
print("약 20초 동안 보정이 진행됩니다...")
magnetometer.calibrate()
print("보정 완료!")

`magnetometer.calibrate()`

자기장 센서를 보정합니다. 정확한 측정을 위해 보드를 공중에 들고 천천히 8자를 여러 번 그리는 방법으로 20초 정도 보정을 수행합니다.

예시:

print("자기장 센서 보정을 시작합니다...")
print("보드를 공중에 들고 천천히 8자를 여러 번 그려주세요")
print("약 20초 동안 보정이 진행됩니다...")
magnetometer.calibrate()
print("보정 완료!")

`magnetometer.get_x()`

X축 자기장 값을 반환합니다.

반환값:

float: X축 자기장 값

예시:

x_value = magnetometer.get_x()
print(f"X축 자기장: {x_value}")

`magnetometer.get_y()`

Y축 자기장 값을 반환합니다.

반환값:

float: Y축 자기장 값

예시:

y_value = magnetometer.get_y()
print(f"Y축 자기장: {y_value}")

`magnetometer.get_z()`

Z축 자기장 값을 반환합니다.

반환값:

float: Z축 자기장 값

예시:

z_value = magnetometer.get_z()
print(f"Z축 자기장: {z_value}")

`magnetometer.get_values()`

세 축의 자기장 값 튜플을 반환합니다.

반환값:

tuple: (x, y, z) 자기장 값들

예시:

x, y, z = magnetometer.get_values()
print(f"자기장: X={x}, Y={y}, Z={z}")

`magnetometer.get_strength()`

자기장의 강도를 반환합니다.

반환값:

float: 자기장 강도

예시:

strength = magnetometer.get_strength()
print(f"자기장 강도: {strength}")

`magnetometer.get_heading()`

나침반 방향을 반환합니다. 보드가 수평 상태일 때 가장 정확한 방향을 제공합니다.

반환값:

float: 나침반 방향 (0-360도)

예시:

heading = magnetometer.get_heading()
print(f"나침반 방향: {heading}도")

하드웨어 정보

센서: MMC5603 자기장 센서
인터페이스: I2C
주소: 0x30
측정 범위: ±8 Gauss
해상도: 16-bit
업데이트 속도: 최대 100Hz
전원 공급: 3.3V
물리적 위치: 보드에 통합

좌표계

Codi:bit 보드의 자기장 센서는 보드의 실제 물리적 방향을 기준으로 동작합니다:

축 방향

X축: 좌우 방향 (Left and right)
- 왼쪽 방향이 양수, 오른쪽 방향이 음수
Y축: 앞뒤 방향 (Forward and backward)
- 앞쪽 방향이 양수, 뒤쪽 방향이 음수
Z축: 상하 방향 (Up and down)
- 위쪽 방향이 양수, 아래쪽 방향이 음수

나침반 방향

0°: 북쪽 (North)
90°: 동쪽 (East)
180°: 남쪽 (South)
270°: 서쪽 (West)

측정값 범위

자기장 값: -8.0 ~ +8.0 Gauss
나침반 방향: 0.0 ~ 360.0도
자기장 강도: 0.0 ~ +무한대

주의사항

보정: 정확한 측정을 위해 측정 전에 calibrate() 호출
금속 물체: 주변의 금속 물체가 측정에 영향을 줄 수 있음
전자기장: 전자기장이 있는 환경에서는 정확도가 떨어질 수 있음
수평 상태: 나침반 기능은 보드가 수평 상태일 때 가장 정확함
환경 영향: 주변 환경에 따라 자기장 값이 크게 변화할 수 있음
보정 필요: 처음 사용 시나 환경이 바뀔 때 보정 권장

자이로스코프 (Gyroscope)

내장 QMI8658 자이로스코프 센서를 제어하는 API입니다.

전역 인스턴스

from codibit import gyroscope

gyroscope

메서드

`gyroscope.get_x()`

X축 각속도 값을 반환합니다.

반환값:

int: X축 각속도 값

예시:

x_value = gyroscope.get_x()
print(f"X축 각속도: {x_value}")

`gyroscope.get_y()`

Y축 각속도 값을 반환합니다.

반환값:

int: Y축 각속도 값

예시:

y_value = gyroscope.get_y()
print(f"Y축 각속도: {y_value}")

`gyroscope.get_z()`

Z축 각속도 값을 반환합니다.

반환값:

int: Z축 각속도 값

예시:

z_value = gyroscope.get_z()
print(f"Z축 각속도: {z_value}")

`gyroscope.get_values()`

세 축의 각속도 값 튜플을 반환합니다.

반환값:

tuple: (x, y, z) 각속도 값들

예시:

x, y, z = gyroscope.get_values()
print(f"각속도: X={x}, Y={y}, Z={z}")

`gyroscope.get_strength()`

각속도의 크기(총 회전 강도)를 반환합니다.

반환값:

int: 각속도 크기

예시:

strength = gyroscope.get_strength()
print(f"각속도 강도: {strength}")

하드웨어 정보

센서: QMI8658 6축 IMU
인터페이스: I2C
주소: 0x6B
측정 범위: ±16, ±32, ±64, ±128, ±256, ±512, ±1024, ±2048 dps
해상도: 16-bit
업데이트 속도: 최대 200Hz
전원 공급: 3.3V
물리적 위치: 보드에 통합

좌표계

Codi:bit 보드의 자이로스코프는 보드의 실제 물리적 방향을 기준으로 동작합니다:

축 방향

X축: 롤 (좌우 회전)
- 왼쪽으로 회전할 때 양수, 오른쪽으로 회전할 때 음수
Y축: 피치 (앞뒤 회전)
- 앞으로 회전할 때 양수, 뒤로 회전할 때 음수
Z축: 요 (시계방향-반시계방향 회전)
- 시계방향으로 회전할 때 양수, 반시계방향으로 회전할 때 음수

측정값 범위

각속도 값: 설정된 범위에 따라 다름 (±16에서 ±2048 dps)
회전 감지: 각 축 주위의 회전 속도를 측정
정지 상태: 회전하지 않을 때는 0에 가까운 값

주의사항

보정: 센서는 정지 상태에서 자동으로 0으로 보정됩니다
회전 감지: 전체적인 회전을 감지하려면 get_strength()를 사용하세요
축 값: 개별 축 값은 양수 또는 음수일 수 있습니다
샘플링: 값은 센서의 설정된 속도로 업데이트됩니다
노이즈: 센서 노이즈로 인한 작은 변화는 정상입니다
범위 선택: 센서는 적절한 측정 범위를 자동으로 선택합니다

유틸리티 (Utils)
- get_board_temperature()
버튼 (Buttons)
RGB LED
버저 (Buzzer)
마이크 (Microphone)
주변광 센서 (Light Sensor)
디스플레이 (Display)
이미지 (Image)
가속도계 (Accelerometer)
Magnetometer
자이로스코프 (Gyroscope)

유틸리티 (Utils)​

get_board_temperature()​

버튼 (Buttons)​

전역 인스턴스​

메서드​

button.is_pressed()​

button.was_pressed()​

button.get_presses()​

button.get_press_count()​

메서드 비교​

하드웨어 정보​

주의사항​

RGB LED​

전역 인스턴스​

메서드​

rgb_led.set_color(strip_id, r, g, b)​

rgb_led.get_color(strip_id)​

rgb_led.set_all_color(r, g, b)​

rgb_led.set_brightness(strip_id, brightness)​

rgb_led.set_all_brightness(brightness)​

rgb_led.turn_off(strip_id)​

rgb_led.turn_off_all()​

rgb_led.show()​

하드웨어 정보​

주의사항​

버저 (Buzzer)​

전역 인스턴스​

음표 표기법​

Sound​

Melody​

메서드​

buzzer.play_tone(frequency, duration_ms=1000)​

buzzer.play_melody(melody, tempo=None)​

buzzer.play_sound(sound_type)​

buzzer.stop()​

buzzer.set_tempo(ticks=4, bpm=120)​

buzzer.get_tempo()​

buzzer.set_volume(volume)​

하드웨어 정보​

주의사항​

마이크 (Microphone)​

전역 인스턴스​

메서드​

microphone.read()​

microphone.get_level()​

microphone.is_sound_detected()​

microphone.is_loud()​

microphone.is_quiet()​

하드웨어 정보​

주의사항​

주변광 센서 (Light Sensor)​

전역 인스턴스​

메서드​

light.read()​

light.read_level()​

하드웨어 정보​

주의사항​

디스플레이 (Display)​

전역 인스턴스​

기본 제어 메서드​

display.clear()​

display.clear_immediate()​

display.show()​

픽셀 제어​

display.get_pixel(x, y)​

display.set_pixel(x, y, val)​

그리기 메서드​

display.draw_text(text, x, y)​

display.draw_rectangle(x, y, w, h, fill=False)​

display.draw_line(x1, y1, x2, y2)​

display.draw_circle(x, y, r, fill=False)​

display.draw_triangle(x1, y1, x2, y2, x3, y3, fill=False)​

이미지​

display.draw_image(image, x, y, scale=1)​

하드웨어 정보​

작동 방식​

사용 패턴​

주의사항​

이미지 (Image)​

사용법​

유틸리티 (Utils)

`get_board_temperature()`

버튼 (Buttons)

전역 인스턴스

메서드

`button.is_pressed()`

`button.was_pressed()`

`button.get_presses()`

`button.get_press_count()`

메서드 비교

하드웨어 정보

주의사항

RGB LED

전역 인스턴스

메서드

`rgb_led.set_color(strip_id, r, g, b)`

`rgb_led.get_color(strip_id)`

`rgb_led.set_all_color(r, g, b)`

`rgb_led.set_brightness(strip_id, brightness)`

`rgb_led.set_all_brightness(brightness)`

`rgb_led.turn_off(strip_id)`

`rgb_led.turn_off_all()`

`rgb_led.show()`

하드웨어 정보

주의사항

버저 (Buzzer)

전역 인스턴스

음표 표기법

`Sound`

`Melody`

메서드

`buzzer.play_tone(frequency, duration_ms=1000)`

`buzzer.play_melody(melody, tempo=None)`

`buzzer.play_sound(sound_type)`

`buzzer.stop()`

`buzzer.set_tempo(ticks=4, bpm=120)`

`buzzer.get_tempo()`

`buzzer.set_volume(volume)`

하드웨어 정보

주의사항

마이크 (Microphone)

전역 인스턴스

메서드

`microphone.read()`

`microphone.get_level()`

`microphone.is_sound_detected()`

`microphone.is_loud()`

`microphone.is_quiet()`

하드웨어 정보

주의사항

주변광 센서 (Light Sensor)

전역 인스턴스

메서드

`light.read()`

`light.read_level()`

하드웨어 정보

주의사항

디스플레이 (Display)

전역 인스턴스

기본 제어 메서드

`display.clear()`

`display.clear_immediate()`

`display.show()`

픽셀 제어

`display.get_pixel(x, y)`

`display.set_pixel(x, y, val)`

그리기 메서드

`display.draw_text(text, x, y)`

`display.draw_rectangle(x, y, w, h, fill=False)`

`display.draw_line(x1, y1, x2, y2)`

`display.draw_circle(x, y, r, fill=False)`

`display.draw_triangle(x1, y1, x2, y2, x3, y3, fill=False)`

이미지

`display.draw_image(image, x, y, scale=1)`

하드웨어 정보

작동 방식

사용 패턴

주의사항

이미지 (Image)

사용법