Touch Bridge

시각장애인을 위한 가전 터치패드 자동 입력 시스템

2026 한이음 드림업 공모전 — 3팀 멜론머스크 (박성원 · 서예솔)

왜 이 문제인가

2024년 장애인차별금지법 이행 실태조사에서 시각장애인 응답자의 **77.1%**가 편의 기능 미비·부족으로 키오스크 이용에 어려움을 겪었다고 답했습니다. (보건복지부 자료 KDI 보관본)

국내 등록 시각장애인은 약 24만 7천 명입니다 (보건복지부 2024년 등록장애인 현황). 전자레인지·세탁기·인덕션 등의 평면 터치패널은 버튼 위치를 촉각만으로 구분하기 어렵습니다.

기존 대안의 한계: LG·삼성의 점자 스티커·음성 매뉴얼은 여전히 정확한 위치를 사용자가 직접 터치해야 합니다.
스마트홈 가전 교체: 비용이 크고, 이미 집에 있는 가전은 그대로 못 씁니다.

Touch Bridge는 교체가 아닌 부착으로 기존 가전을 그대로 접근성 있게 만듭니다.
물리 터치 대행 방식은 UIST 2023 BrushLens 원 연구에서도 검토된 접근법입니다. 논문의 실험 결과는 Touch Bridge의 실기 성능을 의미하지 않으며, 본 프로젝트 수치는 별도 반복 시험으로 검증합니다.

프로젝트 개요

전자레인지·세탁기·키오스크 등 터치패널 기반 가전이 시각장애인에게 접근하기 어렵다는 문제를 해결합니다.
가전 터치패드 위에 부착하는 IoT 하드웨어 장치가 스마트폰 앱·음성 명령을 받아 물리적으로 버튼을 대신 눌러주는 시스템입니다.

논문

박성원, 서예솔, "시각장애인용 가전 입력 대행 시스템의 안내–동작 불일치 완화를 위한 소프트웨어 안전 계약", 한국정보처리학회 ACK 2026 학술발표대회, 포스터 발표, 2026.11. (게재 확정)

앱에 흩어져 있던 안전 규칙을 세 가지 계약(확인 기반 피드백, 실행 토큰 기반 정지 전파, 보수적 명령 해석)으로 정리하고, 계약이 빠져 있던 경로까지 확장했다.
같은 결함을 기준 코드와 확장 코드에 주입해 비교한 결과, 비상 정지 이후 전송된 명령은 시나리오에 따라 7~20줄에서 0줄로 줄었다. 이 값은 앱 측 가상 전송 계층의 기록이며, 실기기에서 모터 정지를 검증한 결과는 아니다.

데모 화면

홈 · 내 기기
_{큰 말하기 버튼 · 현재 기기}

제어 방식 선택
_{음성·이미지·코스·숫자패드}

비상 정지
_{즉시 중단 · 이중 확인}

접근성 · 모드
_{큰 글씨·고대비·보호자/개발자}

고대비 다크 테마 · 큰 터치 영역 · 2단계 탭(첫 탭 안내 → 둘째 탭 실행) · 하단 3탭(홈 / 비상 / 설정) 구조. (스크린샷은 데모 데이터 기준)

주요 기능

음성 명령 (STT + Gemini AI)

speech_to_text로 음성 수집 → 백엔드/Gemini로 의도 파싱
지원 명령: 기기 작동(초 단위), 비상 정지, 화면 이동(NAVIGATE), 상태 질의("얼마나 남았어?"), 재실행("아까 그거 다시" — 확인 후 실행)
기기 별명 지원: "우리집 세탁기"처럼 평소 부르는 이름으로 호출 가능 (기기 관리에서 등록)
침묵 감지 타임아웃 5~15초 — 설정에서 개인 맞춤 조절 가능
STT 연속 실패 시 에스컬레이션: 2회 실패 → "도움말" 힌트 자동 안내

TTS 음성 안내

모든 화면 진입·버튼 탭·완료 시 한국어 음성 피드백
속도·음량 설정 저장 (SharedPreferences)
TalkBack/VoiceOver 활성 시 이중 낭독 자동 억제

비상 정지

전역 비상 버튼: 모든 화면 상단 앱바에 상주 — 어떤 화면에서든 두 번 탭이면 즉시 중단
버튼 3초 홀드(1초 간격 햅틱 피드백) 또는 음성 "멈춰"/"정지"/"그만"
카운트다운 구간(5분·2분·1분·30초·10초·5초·3초) 자동 음성 안내
정지 결과는 하드웨어 ACK 확인 기반으로만 "멈췄습니다" 안내 (거짓 완료 금지)

이중 탭(2단계) 확인 패턴

하드웨어를 실제로 누르는 모든 동작은 첫 탭에서 안내 + 대기 강조, 둘째 탭에서 실행 (오작동 방지)
전 화면 일관 적용 (제어 시트·이미지 제어·간편 코스·숫자 패드·비상 정지)
대기(armed) 시간 20초 (WCAG 2.2.1 준수)

사용자 / 보호자 모드 분리

사용자 모드 (기본): 일상 조작은 홈·비상 정지·설정에 집중하되, 독립 설치가 필요한 사용자는 홈의 명시적 진입점에서 기기를 추가할 수 있음
보호자 모드: 기기 관리 탭과 연결·매핑 도구를 추가 노출 — 가족·시설 관리자의 초기 설정과 유지보수에 적합

Gemini Vision 버튼 자동 매핑

가전기기 사진 촬영 → Gemini Vision API로 버튼 위치 인식
버튼 중심 정규화 좌표를 생성하고, 네 모서리 캘리브레이션으로 실제 X/Y mm 좌표로 변환
드래그 외에도 상·하·좌·우 미세 조정 버튼으로 위치를 수정하고 한 점씩 검증 가능
기기별 독립 저장 (deviceId 기반)

설정 영속화

TTS 속도·음량, STT 타임아웃, 접근성 옵션 → 앱 재시작 후에도 유지

기술 스택

분류	패키지	버전
프레임워크	Flutter / Dart	3.x / 3.x
음성 인식	`speech_to_text`	^7.4.0
TTS	`flutter_tts`	^4.2.5
AI (NLU + Vision)	`google_generative_ai` (백엔드 프록시)	^0.2.0
BLE 통신	`flutter_blue_plus`	^1.35.5
NFC 태그	`nfc_manager`	^3.3.0
전화 연결	`url_launcher`	^6.3.1
사진 선택	`image_picker`	^1.1.2
설정 저장	`shared_preferences`	^2.3.2
환경 변수	`flutter_dotenv`	^5.1.0

플랫폼 지원

기능	Android	iOS	macOS 앱	Chrome (웹)
TTS 음성 안내	✅	✅	❌ *	✅
STT 음성 명령	✅	✅	❌ *	✅
Gemini AI	✅	✅	✅	✅
사진 매핑	✅	✅	✅ (갤러리)	✅
설정 영속화	✅	✅	✅	✅

* macOS 26 (Tahoe) beta OS 버그로 TTS/STT 비활성화. 정식 출시 후 재확인 예정.

환경 설정

앱(Flutter)

프로젝트 루트 .env:

AI_BACKEND_URL=http://127.0.0.1:8000
# 백엔드에 BACKEND_API_KEY가 설정된 경우 같은 값 지정
AI_BACKEND_API_KEY=

앱은 Gemini API 키를 직접 사용하지 않고, 백엔드 API를 통해 AI 기능을 호출합니다. (.env_ex 참고)

.env는 pubspec.yaml에 asset으로 선언돼 있어 없으면 analyze 경고와 빌드 실패가 발생합니다. gitignore 대상이므로 클론 직후 한 번 만들어 주세요:

cp .env_ex .env

백엔드(FastAPI)

backend 실행 환경 .env:

# AI 제공자 선택: google(기본, Gemini 직접 호출) | school(수원대 API Gateway)
# school 선택 시 실패해도 Google로 자동 우회하지 않습니다.
AI_PROVIDER=google

# google 제공자용
GOOGLE_API_KEY=여기에_실제_키_입력
GEMINI_MODEL=gemini-1.5-flash

# school 제공자용 (수원대학교 API Gateway, OpenAI 호환)
SCHOOL_API_KEY=
SCHOOL_API_BASE_URL=https://factchat-cloud.mindlogic.ai/v1/gateway
SCHOOL_API_MODEL=gemini-3.8-flash
# 사진 분석용 모델을 따로 쓰려면 지정 (미지정 시 SCHOOL_API_MODEL과 동일)
SCHOOL_API_VISION_MODEL=

# 배포 시 필수 — 설정하면 모든 API 요청에 X-API-Key 헤더를 요구합니다
BACKEND_API_KEY=
# MongoDB (미설정 시 localhost, 연결 실패 시 인메모리 폴백)
MONGO_URI=mongodb://localhost:27017/

(backend/.env_ex 참고)

Render 배포 (학교 API Gateway 사용 시)

Render 서비스의 Environment에 다음 변수를 설정:
- AI_PROVIDER=school
- SCHOOL_API_KEY=<학교 발급 키> (Git/예제 파일에 절대 넣지 말 것)
- SCHOOL_API_BASE_URL=https://factchat-cloud.mindlogic.ai/v1/gateway
- SCHOOL_API_MODEL=gemini-3.8-flash
- (선택) SCHOOL_API_VISION_MODEL=<사진 분석용 모델 ID>
- BACKEND_API_KEY=<앱과 공유할 서버 인증 키>
코드 변경을 push하면 Render가 자동 재배포합니다 (수동이면 Manual Deploy → Deploy latest commit).
배포 확인 순서:
- GET / 응답의 ai_provider가 school인지 확인 (설정 확인용일 뿐, AI 연결 성공의 증거는 아님 — /healthz 200도 마찬가지)
- /parse-command에 규칙에 없는 문장(예: "안녕하세요")을 보내고, Render 로그에서 ai.call provider=school model_req=... model_resp=... status=ok 라인으로 실제 학교 API 사용을 확인
사진 분석(/vision-mapping)도 gemini-3.8-flash로 동작 확인됨(2026-09-07). 다른 모델로 바꾸려면 SCHOOL_API_VISION_MODEL을 설정하세요 — 게이트웨이는 제공자 네이티브 전체 API를 지원하지 않으므로, 모델을 바꿀 때는 사진 1장으로 재확인하는 것이 안전합니다.

Branch 주의: Render Settings → Build & Deploy → Branch가 main인지 확인하세요. 다른 브랜치로 설정돼 있으면 main에 푸시해도 배포되지 않고 구버전이 계속 서비스됩니다(2026-09-07에 실제로 겪은 문제). 새 코드 반영 여부는 GET / 응답의 ai_provider 필드 유무로 즉시 판별됩니다.

백엔드에는 IP당 분당 60회(비전 10회) 레이트리밋, 업로드 5MB 상한, AI 응답 스키마 검증(버튼 ID 화이트리스트 등)이 적용되어 있습니다.

실행 방법

# 의존성 설치
flutter pub get

# Chrome에서 실행 (개발·테스트 권장)
flutter run -d chrome

# Android
flutter run -d android

# iOS
flutter run -d ios

Chrome 첫 실행 시 마이크 권한 팝업이 뜹니다. 허용해야 음성 명령이 동작합니다.
TTS는 첫 사용자 탭 이후부터 작동합니다 (Chrome 자동재생 정책).

플랫폼별 권한 설정

Android (`android/app/src/main/AndroidManifest.xml`)

<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>

iOS (`ios/Runner/Info.plist`)

<key>NSMicrophoneUsageDescription</key>
<string>음성 명령을 듣기 위해 마이크 접근이 필요합니다.</string>
<key>NSSpeechRecognitionUsageDescription</key>
<string>음성 명령을 텍스트로 인식하기 위해 권한이 필요합니다.</string>
<key>NSCameraUsageDescription</key>
<string>가전기기 버튼을 AI로 인식하기 위해 카메라 접근이 필요합니다.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>기기 사진을 선택하여 버튼을 매핑하기 위해 사진 라이브러리 접근이 필요합니다.</string>

macOS (`macos/Runner/Info.plist` + entitlements)

Info.plist: NSMicrophoneUsageDescription, NSSpeechRecognitionUsageDescription, NSCameraUsageDescription, NSPhotoLibraryUsageDescription
Entitlements: audio-input, speech-recognition, photos-library, camera, network.client

프로젝트 구조

lib/
├── main.dart                              # 앱 진입점, dotenv·설정 로드
├── screens/
│   ├── main_navigation_screen.dart        # 사용자/보호자 모드별 하단 내비게이션
│   ├── home/home_screen.dart              # 기기 카드 스와이프 (PageView)
│   ├── control/remote_control_screen.dart # 타이머 제어 키패드
│   ├── voice/voice_listening_screen.dart  # STT + Gemini AI 음성 명령
│   ├── safety/
│   │   ├── emergency_stop_screen.dart     # 비상 정지 (3초 홀드 / 음성)
│   │   └── stop_done_screen.dart          # 정지 완료 확인
│   ├── settings/
│   │   ├── settings_screen.dart           # 접근성·연락처·보호자/개발자 설정
│   │   ├── device_management_screen.dart  # 보호자용 기기 관리
│   │   └── developer_console_screen.dart  # 개발자용 ESP/G-code/XYZ 테스트
│   ├── connection/
│   │   ├── device_connect_screen.dart     # 기기 연결 (QR/BLE/NFC)
│   │   └── qr_scan_screen.dart            # QR 스캔
│   └── mapping/photo_mapping_screen.dart  # Gemini Vision 버튼 매핑
├── services/
│   ├── tts_service.dart                   # TTS Singleton
│   ├── accessibility_settings.dart        # 설정 Singleton + SharedPreferences
│   ├── device_mapping_service.dart        # 기기별 매핑/XYZ 모션 프로필 저장
│   ├── mapping_execution_service.dart     # BT-xx → X/Y/Z G-code 실행 변환
│   ├── ble_service.dart                   # BLE 스캔/연결/raw 명령 전송
│   └── timer_service.dart                 # 카운트다운 타이머
├── theme/                                 # 고대비 다크 테마
└── widgets/                               # 재사용 위젯

Gemini AI 명령 형식

{
  "action": "MICROWAVE_CONTROL | EMERGENCY_STOP | NAVIGATE | NONE",
  "device": "전자레인지",
  "seconds": 30,
  "commands": ["BT-02", "BT-05"],
  "target": "connection | mapping | settings",
  "message": "알겠어요. 전자레인지 30초 돌릴게요."
}

하드웨어 연동

현재 하드웨어는 소형화를 위해 FIT0482 엔코더 DC 기어모터 2개(X/Y, CoreXY) + ESP32 폐루프 PID + 솔레노이드 누름부로 구성합니다. 펌웨어(v3)는 hardware/touchbridge_corexy/에 있고, 배선과 첫 구동 순서는 그 폴더의 README를 따릅니다. 설계 배경은 docs/XY_SWITCHBOT_SOFTWARE_PLAN.md이며, 그 계획의 누름부(스위치봇)는 이후 솔레노이드로 바뀌었습니다.

현재 구성:

X/Y: FIT0482 6V 310RPM 50:1 엔코더 DC 기어모터 2개, CoreXY 구동
드라이버: JMOD-MOTOR-1 (TB6612FNG)
제어: ESP32가 엔코더 피드백을 받아 위치 PID 수행 (1kHz)
원점: 벽 감지(스톨) 원점 복귀가 기본, 리밋 스위치는 선택; 홈 완료 전 이동 금지
누름: 별도 Z축 대신 5V 솔레노이드 (SparkFun ROB-11015)
통신: 앱 → BLE → ESP32 (USB 시리얼은 디버깅용)
전원: 모터 전원과 MCU 전원 분리, 공통 GND 유지

권장 실행 흐름:

AI는 물리 좌표를 만들지 않고 논리 버튼 ID(BT-xx)만 반환합니다.
사진 분석은 버튼 중심의 정규화 좌표와 신뢰도만 만들고, 보호자 캘리브레이션을 거쳐 X/Y mm로 확정합니다.
앱은 BT-xx → buttonMachinePositions → X/Y 목표 mm를 전달합니다.
ESP32는 목표 위치 오차가 허용 범위 안에 들어온 뒤에만 솔레노이드를 작동시키고 완료 상태를 회신합니다.
펌웨어 v3는 앱 v2 JSON과 함께 GRBL 호환 G-code(Z축 명령을 솔레노이드로 해석)·BTN_n·SET_GRID도 받으므로, 음성 경로의 G-code 전송도 그대로 동작합니다.

v2 명령 흐름 (이동과 누름은 두 단계):

이동만 — 도착하면 POSITIONED와 1회용 positionToken을 돌려줍니다.

{
  "version": 2,
  "commandId": "c-001",
  "action": "move_only",
  "deviceId": "microwave_1",
  "target": {"xMm": 42.5, "yMm": 18.25},
  "toleranceMm": 1.0
}

받은 토큰으로 누름 — 토큰은 한 번만 쓸 수 있고, 그 사이 위치가 밀렸으면 거부됩니다(ERROR_INVALID_TOKEN).

{
  "version": 2,
  "commandId": "c-002",
  "action": "press",
  "deviceId": "microwave_1",
  "positionToken": "9f3a1c...",
  "pressActuator": "switchbot"
}

pressActuator는 앱이 예전 표기대로 보내는 값이며 펌웨어는 읽지 않습니다. 명세: docs/ESP32_MOTION_PROTOCOL_V2.md

개발 현황

작업 로그

자세한 변경 이력은 docs/WORK_LOG.md를 참고하세요.

심사용 문서

테스트

flutter analyze
flutter test

자동 테스트 446개 통과 (Flutter 391 + 백엔드 55, 2026-10-10) — GitHub Actions가 푸시마다 flutter analyze --fatal-infos·flutter test·백엔드 테스트를 실행합니다. Flutter 테스트 범위: 명령 규칙, 시간 계산, 실제 mm 좌표·4점 보정, ESP32 모션 v2 상태 머신, 안전 검증 기록, BLE 재연결·명령 큐, 보안 세션(HMAC), Z축 복구, 셀 충돌 검출, TTS 억제 계약, 화면읽기 내비게이션, 촬영 안내, 보호자 자유 배치·조이스틱 위치 맞추기, 드래그 대체 조그, 색상 대비(WCAG), STT 타임아웃
9월 5일 안전 회귀 10건: 보정 무효화 실행 차단·영속화, 정지 후 대기 작업/지연 응답 폐기, 대기 중 재연결, 원점 기기 구분, 타임아웃 안내, 화면 종료 처리.
위젯 테스트: 홈 화면 스모크, BLE 연결 흐름, 하단 내비게이션 모드 전환

접근성 실험 지표

설정 화면의 접근성 실험 지표 섹션에서 다음 항목을 누적 확인할 수 있습니다.

총 작업 수 / 완료 / 중단 / 완료율 / 평균 완료 시간
음성·수동 모드별 분리 집계 (작업 수, 완료 수, 평균 완료 시간 — 당사자 검증의 핵심 비교 지표)
비상 정지 횟수 / 이중탭 타임아웃 횟수

지표 내보내기로 CSV를 클립보드에 복사해 시트에 붙여 넣을 수 있고, 지표 초기화(확인 다이얼로그)로 실험 배치를 리셋할 수 있습니다.

하드웨어 작업 및 안전 (요약)

하드웨어는 프로토타입 수준에서 동작하지만, 설치·운영 전 반드시 물리적 안전 조치를 수행해야 합니다. 자세한 체크리스트와 회로 권장 사항은 docs/HARDWARE_TASKS.md를 먼저 확인하세요.

간단히 확인해야 할 항목:

FIT0482 X/Y 모터 2개의 실측 정지전류를 기준으로 H-브리지와 전류 제한을 선정
6V 모터 전원과 ESP32 로직 전원을 분리하고 공통 GND 연결
엔코더 A/B상 방향·카운트 확인, 벽 감지 원점 복귀와 추종 오차(걸림) 감지 동작 확인 (리밋 스위치를 달 경우 fail-safe 동작도 확인)
홈 완료 전 이동 금지, 허용 오차 밖에서는 솔레노이드 누름 금지 확인
솔레노이드 구동부의 플라이백 다이오드 확인
적정 퓨즈 장착
하드웨어 비상정지(E‑STOP) 회로 구성(필수)

보안 관련 권장사항은 docs/SECURITY.md에 정리되어 있습니다. 프로덕션 전환 전 BLE LE Secure Connections 및 OTA 서명 도입을 권장합니다.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
android		android
assets/sounds		assets/sounds
backend		backend
docs		docs
hardware/touchbridge_corexy		hardware/touchbridge_corexy
ios		ios
lib		lib
linux		linux
macos		macos
test		test
web		web
windows		windows
.env_ex		.env_ex
.gitignore		.gitignore
.metadata		.metadata
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
analysis_options.yaml		analysis_options.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

Latest commit

History

Folders and files

Repository files navigation

Touch Bridge

왜 이 문제인가

프로젝트 개요

논문

데모 화면

주요 기능

음성 명령 (STT + Gemini AI)

TTS 음성 안내

비상 정지

이중 탭(2단계) 확인 패턴

사용자 / 보호자 모드 분리

Gemini Vision 버튼 자동 매핑

설정 영속화

기술 스택

플랫폼 지원

환경 설정

앱(Flutter)

백엔드(FastAPI)

Render 배포 (학교 API Gateway 사용 시)

실행 방법

플랫폼별 권한 설정

Android (android/app/src/main/AndroidManifest.xml)

iOS (ios/Runner/Info.plist)

macOS (macos/Runner/Info.plist + entitlements)

프로젝트 구조

Gemini AI 명령 형식

하드웨어 연동

개발 현황

작업 로그

심사용 문서

테스트

접근성 실험 지표

하드웨어 작업 및 안전 (요약)

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Android (`android/app/src/main/AndroidManifest.xml`)

iOS (`ios/Runner/Info.plist`)

macOS (`macos/Runner/Info.plist` + entitlements)