🎛️ 버튼·프리셋과 순정 SCC

알아두기 이 문서는 carrot-wip 코드와 함께 관리하는 사용자 설명서 원본입니다. 사용자 동작이 바뀌면 관련 코드·테스트와 같은 변경에서 이 문서도 갱신합니다.

이 페이지는 carrot-wip의 실제 코드를 기준으로 버튼·프리셋 설정을 설명합니다. 설정 화면의 짧은 문구만으로 알기 어려운 짧게 누르기·길게 누르기·사용자 모드의 차이와 순정 SCC 버튼 스팸의 적용 조건을 함께 정리했습니다.

모든 값은 Carrot Web의 설정 → 주행 제어 → 버튼·프리셋에서 변경합니다.

주의 버튼 이벤트와 순정 SCC 메시지 구성은 차종마다 다릅니다. 반드시 현재 값을 기록하고, 안전하게 정차한 상태에서 버튼 인식부터 확인하세요. 주행 중에는 한 항목씩만 변경하고 예상과 다르면 즉시 일반 모드로 복원하세요.

4개 세부 구역

1. 버튼 모드
2. 속도 단위
3. 버튼 테스트·스팸
4. 속도 프리셋

먼저 알아둘 핵심

• 아래 동작은 차량 인터페이스가 해당 버튼 이벤트를 정상 전달할 때만 적용됩니다.
• 짧게 누르기와 길게 누르기는 같은 속도 단위를 쓰지 않습니다. 현재 코드에서 길게 누르기는 항상 10km/h 격자입니다.
• 사용자 모드 1~3에서는 CruiseSpeedUnitBasic보다 CruiseSpeedUnit의 영향이 커집니다.
• 크루즈가 꺼져 있거나 대기·정차·브레이크 복귀 상태이면 속도 변경보다 크루즈 재개 로직이 우선할 수 있습니다.
• mph 화면에서는 짧게 누르기 단위를 mph로 해석해 내부 km/h로 변환하지만, 길게 누르기의 고정 10은 내부 km/h 기준이므로 약 6.2mph씩 움직입니다.

초기값이 서로 다르게 보일 수 있습니다

Carrot Web의 개별 기본값 복원은 carrot_settings.json의 default를 사용하고, Params가 처음 만들어질 때는 params_keys.h의 초기값을 사용합니다. 현재 브랜치에는 다음 차이가 있습니다.

특히 버튼 테스트의 카탈로그 기본값 0은 화면 최소값보다도 작습니다. 숫자를 억지로 통일하지 말고 내 장치의 현재 값을 기준으로 백업한 뒤 조정하세요.

1. 버튼 모드

관련 설정은 CruiseButtonMode, CancelButtonMode, LfaButtonMode, PaddleMode입니다.

CruiseButtonMode

아래 표는 크루즈가 이미 활성화되고 일반 주행 중일 때의 짧게 누르기 기준입니다.

폭스바겐의 별도 SET은 현재 계기판 속도로 설정하고, RES는 브레이크 전 저장속도가 있으면 그 값을 복원하며 없으면 기존 설정속도를 유지합니다. 아직 설정속도를 초기화하지 않았다면 RES도 현재 속도를 사용하고, 최종 속도에는 기존 최저·최고 설정속도 제한이 적용됩니다.

SET·RES는 짧게 또는 길게 눌러도 놓을 때 한 번만 처리합니다. 아래 버튼 모드·속도 단위·길게 누르기 설정은 별도 +·-에 적용되며, 순정 SCC에서 속도를 가져오는 경우에는 순정 설정속도가 우선합니다.

오픈파일럿 종방향 제어의 수동 인게이지는 기존처럼 물리 SET·RES를 놓을 때 요청합니다. 단순 +·- 버튼을 인게이지 버튼으로 추가하지 않습니다.

사용자1~3의 가속 버튼은 현재 설정속도가 30km/h 미만이면 먼저 30km/h로 올리고, 그 이후에는 40km/h부터 CruiseSpeedUnit 간격으로 다음 값을 찾습니다. 사용자3은 프리셋을 모두 지난 다음에만 CruiseSpeedUnit 격자로 이어집니다.

사용자2·3의 감속 버튼은 단순히 일정 값을 빼는 모드가 아닙니다.

• 실제 차속이 설정속도보다 충분히 높으면 설정속도를 실제 차속 쪽으로 맞춥니다.
• 실제 차속이 설정속도보다 낮으면 실제 차속으로 낮출 수 있습니다.
• 더 낮출 조건이 없으면 당근 크루즈 상태로 들어갈 수 있습니다.

단순한 +1/-1 또는 +10/-10 동작이 필요하면 먼저 CruiseButtonMode=0에서 확인하는 것이 좋습니다.

CancelButtonMode

캔슬 버튼을 길게 누르면 모드와 관계없이 횡제어까지 해제합니다. 짧게 눌렀는데 조향까지 꺼지는 것이 싫다면 0, 캔슬 한 번으로 모두 해제하려면 1의 동작을 확인하세요.

LfaButtonMode

1은 누르는 즉시 고정 감속을 명령하는 설정이 아닙니다. 내부의 패들 감속 대기 상태를 켜고, 이후 정지·선행차·크루즈 상태에 따라 Ready와 재활성화 흐름을 처리합니다. 현재 코드에도 수정 필요 주석이 남아 있으므로 실험 기능으로 보고 충분히 검증하세요.

LFA 버튼을 길게 누르면 LfaButtonMode와 무관하게 레인모드 적용 속도 기능을 임시로 켜거나 끕니다.

PaddleMode

알아두기 설정 카탈로그 설명에는 0: 크루즈ON이라고 적혀 있지만, 현재 실행 코드는 PaddleMode > 0일 때만 패들 분기로 들어갑니다. 따라서 현재 브랜치에서 0은 사실상 패들 기능 미사용으로 해석해야 합니다.

패들 이벤트를 전달하지 않는 차종에서는 값을 바꿔도 반응하지 않습니다. 좌·우 패들은 현재 같은 모드 동작을 사용합니다.

길게 누르기의 공통 동작

4개 세부 구역으로 돌아가기

2. 속도 단위

어떤 설정이 어디에 쓰이나요?

CruiseSpeedUnitBasic=1이면 일반 모드에서 1km/h 단위, 5이면 5km/h 격자, 10이면 10km/h 격자로 이동합니다. 현재 값이 격자 사이에 있으면 단순히 현재 값에 더하는 대신 올림·내림하여 다음 격자에 맞춥니다.

예를 들어 일반 모드, 기본 단위 5, 설정속도 83km/h라면:

• 가속 짧게: 85km/h
• 감속 짧게: 80km/h

CruiseButtonLongDelay는 초가 아니라 프레임입니다

버튼 처리는 약 100Hz 제어 주기에서 실행되므로 다음처럼 이해할 수 있습니다.

차간·LFA·캔슬은 내부적으로 설정값에 30프레임을 더합니다. 실제 버튼 메시지 주기와 차량 인터페이스에 따라 체감 시간은 조금 달라질 수 있습니다.

알아두기 CruiseSpeedUnit이나 CruiseSpeedUnitBasic을 바꿔도 길게 누르기의 10km/h 반복 단위는 바뀌지 않습니다.

추천 확인 순서

1. CruiseButtonMode=0으로 둡니다.
2. CruiseSpeedUnitBasic=1에서 짧게 누르기를 확인합니다.
3. 길게 누르기 판정만 CruiseButtonLongDelay로 맞춥니다.
4. 그 다음 사용자 모드와 CruiseSpeedUnit을 시험합니다.

4개 세부 구역으로 돌아가기

3. 버튼 테스트·스팸

CruiseButtonTest1~3은 운전자의 버튼 감도를 바꾸는 일반 설정이 아닙니다. openpilot이 현대·기아 순정 SCC의 설정속도를 목표값과 맞추기 위해 가상 RES/SET 버튼 메시지를 보낼 때 사용하는 고급 값입니다.

제어 주기가 약 0.01초이므로 CruiseButtonTest2=30은 대략 0.30초의 휴지 프레임에 해당합니다. 다만 순정 설정속도가 실제로 변한 것을 감지하면 코드는 별도의 7프레임 대기를 사용하기도 합니다.

적용 범위를 구분해야 합니다.

• 현대·기아 비롱컨 구성의 순정 SCC 속도 동기화에서 사용됩니다.

• 일반 CAN과 CAN FD 버튼 경로 모두 Test1, Test2의 영향을 받을 수 있습니다.

• Test3의 메시지 복제는 현재 CAN FD 전송 경로에서 사용됩니다.

• SpeedFromPCM=1이면 목표와 순정 설정속도의 차이를 맞추는 RES/SET 스팸 분기가 동작하지 않습니다.

• SpeedFromPCM 기본값은 2(커브·카메라 감속)입니다. 설정의 기본값 복원도 2를 사용하며, 기존에 저장된 값은 업데이트만으로 바뀌지 않습니다.

• 차종이 이 버튼 전송 경로를 쓰지 않으면 세 값을 바꿔도 효과가 없습니다.

주의 값을 크게 올리면 버튼 메시지가 과도하게 전송되거나 순정 SCC가 입력을 놓치고, 반대로 너무 작으면 목표 속도 동기화가 늦거나 실패할 수 있습니다. 문제가 없다면 Params 최초값 8 / 30 / 1을 유지하세요.

증상별 확인

4개 세부 구역으로 돌아가기

토요타·렉서스의 순정 설정속도

SpeedFromPCM=3에서는 순정 SET/RES 설정속도를 카롯의 기본 목표속도로 사용합니다. 1도 순정 설정속도를 사용하며, 0과 2는 기존 카롯 속도 선택을 유지합니다. 이 설정은 순정 ACC와 openpilot 가감속 사이를 전환하거나 레이더를 켜고 끄지 않습니다. openpilot 가감속 사용 시 앞차·커브·카메라 감속은 이 기본 목표보다 낮게 적용될 수 있습니다.

0의 예외로, TOYOTA_RAV4_TSS2_2022에서 PCM과 openpilot 직접 가감속을 함께 사용할 때는 유효한 CAN으로 관측한 순정 설정속도 변경과 크루즈 비활성→활성 전이를 기본 목표에 반영합니다. 처음부터 활성인 표본은 기준만 저장하며, 같은 주기의 로컬 버튼·블루투스 속도 변경이 우선합니다. 낮은 앞차·커브·지도 감속 목표는 계속 적용되고, RES/SET CAN 송신을 추가하지 않습니다.

4. 속도 프리셋

CruiseSpeed1~CruiseSpeed5는 CruiseButtonMode=3에서 가속 버튼을 짧게 눌렀을 때 사용하는 순서형 속도 테이블입니다.

이 역할 이름은 이해를 돕기 위한 예시이며 법정 제한속도나 권장 주행속도를 뜻하지 않습니다. 실제 값은 지역·도로·차량 조건에 맞춰야 합니다.

선택 방식

코드는 1번부터 5번까지 차례로 읽고 현재 설정속도보다 큰 첫 값을 선택합니다. 프리셋을 모두 지났으면 CruiseSpeedUnit의 다음 격자로 이동합니다.

예를 들어 30 / 50 / 80 / 110 / 130, 현재 76km/h이면 짧은 가속 한 번으로 80km/h가 됩니다. 다시 누르면 110km/h가 됩니다.

프리셋은 자동 정렬하지 않으므로 반드시 작은 값부터 큰 값 순서로 저장하세요. 중복되거나 역순이면 일부 단계가 건너뛰어질 수 있습니다.

CruiseSpeed1=0의 특별 동작

1번만 0을 허용하며, 이때 고정 0km/h가 아니라 현재 도로 제한속도를 이용해 동적으로 만듭니다.

• AutoRoadSpeedLimitOffset >= 0: 도로 제한속도 + 오프셋
• AutoRoadSpeedLimitOffset < 0: 도로 제한속도 × AutoNaviSpeedSafetyFactor

예를 들어 제한속도 60km/h, 오프셋 5이면 65km/h가 되고, 오프셋 -1과 안전비율 105%이면 63km/h가 됩니다. 유효한 도로 제한속도 정보가 들어오지 않으면 기대한 프리셋이 만들어지지 않습니다.

안전하게 구성하기

1. 먼저 30 / 50 / 80 / 110 / 130처럼 확실한 오름차순으로 시험합니다.
2. 마지막 프리셋 다음 동작을 결정하는 CruiseSpeedUnit도 함께 기록합니다.
3. CruiseSpeed1=0은 도로 제한속도와 오프셋이 정상 수신·적용되는 것을 확인한 뒤 사용합니다.
4. 사용자3의 감속 버튼은 프리셋을 역순으로 내려가지 않는다는 점을 기억하세요.

문제 해결 빠른 표

코드 기준

• 일반 버튼·프리셋 상태기계: openpilot/selfdrive/car/cruise.py
• 현대·기아 순정 SCC 버튼 전송: opendbc_repo/opendbc/car/hyundai/carcontroller.py
• 설정 범위와 카탈로그 기본값: openpilot/selfdrive/carrot_settings.json
• Params 최초값: openpilot/common/params_keys.h

이 문서는 carrot-wip의 현재 구현을 설명합니다. 코드가 변경되면 화면 설명과 실제 동작이 다시 달라질 수 있습니다.

설정 이해하기로 돌아가기

---

문서 기준

2026-10-30 확인 · carrot-wip · 10bf0a56.

docs/user/ko/buttons-presets.md · openpilot/selfdrive/car/cruise.py · opendbc_repo/opendbc/car/hyundai/carcontroller.py

개발 브랜치는 계속 변경됩니다. 내 장치의 브랜치·커밋·현재 설정을 함께 확인하세요.

파라미터	설정 카탈로그 기본값	Params 최초값
PaddleMode	1	0
CruiseSpeedUnitBasic	10	1
CruiseButtonTest1 / 2 / 3	0 / 0 / 0	8 / 30 / 1
CruiseSpeed1~5	10 / 10 / 10 / 10 / 10	30 / 50 / 80 / 110 / 130

값	가속(RES/+) 짧게	감속(SET/-) 짧게
0 일반	CruiseSpeedUnitBasic의 다음 격자	CruiseSpeedUnitBasic의 이전 격자
1 사용자1	30km/h 미만이면 30, 이후 CruiseSpeedUnit 간격의 다음 속도	CruiseSpeedUnit의 이전 격자
2 사용자2	사용자1과 같음	현재 차속으로 맞추거나 조건에 따라 당근 크루즈 진입
3 사용자3	CruiseSpeed1~5 중 현재 설정속도보다 큰 첫 값	사용자2와 같음

값	캔슬 버튼 짧게
0	크루즈 캔슬 상태로 전환하고 횡제어는 유지
1	크루즈 캔슬과 함께 횡제어도 해제

값	LFA 버튼 짧게
0 일반	횡제어 켜기·끄기
1 감속정지 & Ready	자동 감속·Ready 흐름 활성화
2 당근 크루즈	당근 크루즈 활성화

값	패들 입력의 현재 코드 동작
0	별도 패들 동작을 처리하지 않음
1	크루즈 OFF 후 Ready
2	크루즈 OFF 후 Ready + 자동 감속 상태
3	당근 크루즈 활성화

버튼	길게 누를 때
가속·감속	설정속도를 다음·이전 10km/h 격자로 변경하고 누르는 동안 반복
차간	MyDrivingMode를 연비 → 안전 → 일반 → 고속 순서로 전환
LFA	레인모드 속도 적용을 임시 켜기·끄기
캔슬	크루즈 캔슬과 횡제어 해제

설정	범위	실제 역할
CruiseSpeedUnitBasic	1~100	일반 모드에서 짧게 누르는 가속·감속의 기본 격자
CruiseSpeedUnit	1~100	사용자1~3의 확장 속도 격자, 감속 단위, 프리셋 이후 가속 단위
CruiseButtonLongDelay	30~100	가속·감속 버튼을 길게 눌렀다고 판단할 때까지의 제어 프레임 수

저장값	가속·감속 길게 판정	차간·LFA·캔슬 길게 판정
30	약 0.30초	약 0.60초
40	약 0.40초	약 0.70초
60	약 0.60초	약 0.90초

설정	Params 최초값	역할
CruiseButtonTest1	8	한 번의 묶음에서 허용할 연속 전송 횟수
CruiseButtonTest2	30	묶음 전송 후 또는 운전자 버튼 입력 후 쉬는 프레임 수
CruiseButtonTest3	1	CAN FD 경로에서 허용된 한 번의 전송을 몇 개 메시지로 복제할지

증상	먼저 확인할 항목
순정 설정속도가 목표까지 가기 전에 자주 멈춤	Test1, 차량의 버튼 수신 여부
묶음 사이의 반응이 지나치게 느림	Test2와 실제 SCC 속도 갱신 시간
CAN FD에서 버튼 입력이 누락됨	Test3을 한 단계씩 확인
운전자 버튼을 누른 직후 자동 메시지가 겹침	Test2를 먼저 원래 값으로 복원
아무 변화도 없음	비롱컨 여부, SpeedFromPCM, 차량 버튼 경로 확인

설정	Params 최초값	권장 역할 예시
CruiseSpeed1	30	저속·생활도로
CruiseSpeed2	50	일반 시내도로
CruiseSpeed3	80	자동차전용도로
CruiseSpeed4	110	고속도로
CruiseSpeed5	130	마지막 사용자 단계

증상	먼저 볼 설정·조건
짧게 눌렀는데 1km/h가 아닌 큰 폭으로 변함	CruiseButtonMode, CruiseSpeedUnitBasic, CruiseSpeedUnit
길게 누르기 단위가 설정과 다름	현재 코드는 고정 10km/h 격자
사용자3에서 단계를 건너뜀	CruiseSpeed1~5의 오름차순·중복 여부
감속 버튼이 당근 크루즈로 바뀜	사용자2·3의 정상 분기인지 확인
LFA·패들이 반응하지 않음	차량이 해당 버튼 이벤트를 제공하는지 확인
초기화 후 값이 예상과 다름	JSON 기본값과 Params 최초값 차이 확인