school-attendance/tools/stream_deck_teacher_status/README.md

교무실 Stream Deck 선생님 위치 표시기

교무실 출입구에 놓인 Stream Deck으로 선생님이 본인 이름 버튼만 누르면 백품타 앱의 "선생님 호출" 위치가 바뀝니다. 이미 배포돼 있는 서버 API (POST /api/teacher-call/location)를 그대로 호출하기 때문에, 서버나 앱은 전혀 건드릴 필요 없이 이 스크립트 하나만 라즈베리파이 같은 작은 컴퓨터에서 계속 띄워두면 됩니다.

준비물

• Stream Deck 오리지널/MK.2 (15키, 5x3) — USB로 라즈베리파이에 연결
• 라즈베리파이(또는 인터넷 되는 리눅스 미니PC) 1대
• 교무실 회원가입(교사 회원가입)을 마친 선생님만 목록에 뜹니다 — 아직 가입 안 한 선생님은 버튼이 안 보이니, 먼저 앱에서 "교사 회원가입"부터 해달라고 안내해주세요.

설치

# 1) 한글 폰트 설치 (버튼에 이름이 네모(□)로 안 뜨게)
sudo apt update
sudo apt install -y fonts-nanum

# 2) Stream Deck을 일반 사용자 권한으로 인식하게 하는 udev 규칙
#    (이거 안 하면 sudo로만 인식되거나 아예 인식이 안 될 수 있어요)
sudo tee /etc/udev/rules.d/50-streamdeck.rules > /dev/null << 'UDEV'
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", MODE="0666"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0fd9", MODE="0666"
UDEV
sudo udevadm control --reload-rules
sudo udevadm trigger

# 3) 파이썬 패키지 설치
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 4) 실행
python3 stream_deck_teacher_status.py

USB 케이블을 뽑았다 다시 꽂아야 udev 규칙이 적용되는 경우가 있어요.

사용법

• 선생님 이름 버튼을 그냥 누르면 → "수업 중"으로 표시됩니다.
• 과학실/도서관/출장 등 다른 위치로 표시하고 싶으면 → 화면 오른쪽 아래 "⚙ 설정" 버튼을 누르고, 뜨는 위치 목록에서 하나를 고른 뒤(예: "출장"), 이어서 그 선생님 이름 버튼을 누르면 됩니다. 한 번 적용하면 자동으로 다시 기본 모드("수업 중")로 돌아갑니다.
• 선생님이 18명을 넘어가면 자동으로 페이지가 나뉘고, "다음 ▶" 버튼으로 넘길 수 있습니다.
• 새로 교사 회원가입을 한 선생님은 최대 1분 안에 자동으로 목록에 나타납니다 (재시작 필요 없음).

부팅할 때 자동 실행하게 하기 (선택)

라즈베리파이를 켤 때마다 자동으로 이 스크립트가 실행되게 하려면 systemd 서비스로 등록하세요:

sudo tee /etc/systemd/system/streamdeck-teacher.service > /dev/null << 'UNIT'
[Unit]
Description=교무실 Stream Deck 선생님 위치 표시기
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/home/pi/stream_deck_teacher_status/venv/bin/python3 /home/pi/stream_deck_teacher_status/stream_deck_teacher_status.py
Restart=on-failure
RestartSec=5
User=pi

[Install]
WantedBy=multi-user.target
UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now streamdeck-teacher.service

경로(/home/pi/...)는 실제로 이 폴더를 둔 위치에 맞게 바꿔주세요. 로그 확인은 journalctl -u streamdeck-teacher -f.

참고

• 이 스크립트는 이 저장소(school-backend)와는 별개로, 이미 배포된 api.backsanhi.shop의 기존 API만 호출합니다. 서버/앱 배포와는 무관하게 라즈베리파이에서 이 파일만 갖고 있으면 바로 동작합니다.
• python-elgato-streamdeck 라이브러리 버전에 따라 내부 헬퍼 함수 이름이 달라서(create_key_image/create_image 등) 코드에 호환 처리를 넣어뒀지만, 혹시 실행 중 AttributeError가 나면 캡처해서 알려주세요.