Roccat Konepure mouse obsolete ABI | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

Profile selector와 settings payload

sysfs-driver-hid-roccat-konepure:1-69

5개 persistent profile을 3-byte selector로 관리하고 59-byte button layout, 31-byte resolution·sensitivity·light settings와 2082-byte macro를 전송합니다.

Sensor와 TCU calibration

sysfs-driver-hid-roccat-konepure:71-105

tracking·distance unit, lift-off distance, Easy 기능과 TCU calibration을 제어하고 calibration 중 30×30 surface image를 읽습니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/actual_profile

2 Date: December 2012

3 Contact: Stefan Achatz <[email protected]>

4 Description: The mouse can store 5 profiles which can be switched by the

5 press of a button. actual_profile holds number of actual profile.

6 This value is persistent, so its value determines the profile

7 that's active when the mouse is powered on next time.

8 When written, the mouse activates the set profile immediately.

9 The data has to be 3 bytes long.

10 The mouse will reject invalid data.

11 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/control

14 Date: December 2012

15 Contact: Stefan Achatz <[email protected]>

16 Description: When written, this file lets one select which data from which

17 profile will be read next. The data has to be 3 bytes long.

18 This file is writeonly.

19 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/info

22 Date: December 2012

23 Contact: Stefan Achatz <[email protected]>

24 Description: When read, this file returns general data like firmware version.

25 When written, the device can be reset.

26 The data is 6 bytes long.

27 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/macro

30 Date: December 2012

31 Contact: Stefan Achatz <[email protected]>

32 Description: The mouse can store a macro with max 500 key/button strokes

33 internally.

34 When written, this file lets one set the sequence for a specific

35 button for a specific profile. Button and profile numbers are

36 included in written data. The data has to be 2082 bytes long.

37 This file is writeonly.

38 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/profile_buttons

41 Date: December 2012

42 Contact: Stefan Achatz <[email protected]>

43 Description: The mouse can store 5 profiles which can be switched by the

44 press of a button. A profile is split in settings and buttons.

45 profile_buttons holds information about button layout.

46 When written, this file lets one write the respective profile

47 buttons back to the mouse. The data has to be 59 bytes long.

48 The mouse will reject invalid data.

49 Which profile to write is determined by the profile number

50 contained in the data.

51 Before reading this file, control has to be written to select

52 which profile to read.

53 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/profile_settings

56 Date: December 2012

57 Contact: Stefan Achatz <[email protected]>

58 Description: The mouse can store 5 profiles which can be switched by the

59 press of a button. A profile is split in settings and buttons.

60 profile_settings holds information like resolution, sensitivity

61 and light effects.

62 When written, this file lets one write the respective profile

63 settings back to the mouse. The data has to be 31 bytes long.

64 The mouse will reject invalid data.

65 Which profile to write is determined by the profile number

66 contained in the data.

67 Before reading this file, control has to be written to select

68 which profile to read.

69 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/sensor

72 Date: December 2012

73 Contact: Stefan Achatz <[email protected]>

74 Description: The mouse has a tracking- and a distance-control-unit. These

75 can be activated/deactivated and the lift-off distance can be

76 set. The data has to be 6 bytes long.

77 This file is writeonly.

78 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/talk

81 Date: December 2012

82 Contact: Stefan Achatz <[email protected]>

83 Description: Used to active some easy* functions of the mouse from outside.

84 The data has to be 16 bytes long.

85 This file is writeonly.

86 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/tcu

89 Date: December 2012

90 Contact: Stefan Achatz <[email protected]>

91 Description: When written a calibration process for the tracking control unit

92 can be initiated/cancelled. Also lets one read/write sensor

93 registers.

94 The data has to be 4 bytes long.

95 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/tcu_image

98 Date: December 2012

99 Contact: Stefan Achatz <[email protected]>

100 Description: When read the mouse returns a 30x30 pixel image of the

101 sampled underground. This works only in the course of a

102 calibration process initiated with tcu.

103 The returned data is 1028 bytes in size.

104 This file is readonly.

105 Users: http://roccat.sourceforge.net

106

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Profile, control, info와 macro

1-38

BASE=/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>

$BASE/actual_profile
$BASE/control
$BASE/info
$BASE/macro

모든 항목의 Date는 2012년 12월, contact는 Stefan Achatz <[email protected]>, user는 http://roccat.sourceforge.net다.

attribute	payload	access	의미
actual_profile	3 byte	read/write	현재·다음 power-on profile을 저장하고 즉시 활성화
control	3 byte	write-only	다음 read의 profile과 data 종류 선택
info	6 byte	read/write	firmware 등 일반 data 조회와 device reset
macro	2082 byte	write-only	특정 profile·button의 최대 500-stroke macro

mouse는 button으로 전환할 수 있는 profile 다섯 개를 저장한다. actual_profile은 현재 profile 번호를 담으며 persistent하므로 다음 power-on 때 활성화될 profile도 정한다. 3-byte data를 쓰면 profile이 즉시 활성화되고 invalid data는 mouse가 거부한다.

control에 3 byte를 쓰면 다음 read에서 어느 profile의 어떤 data를 가져올지 선택한다.

info를 읽으면 firmware version 같은 일반 data 6 byte를 반환한다. 같은 길이의 data를 쓰면 device를 reset할 수 있다.

mouse는 내부에 최대 500번의 key 또는 button stroke로 이루어진 macro를 저장한다. macro의 2082-byte write data에는 profile 번호와 button 번호가 포함되며 지정한 sequence를 해당 위치에 기록한다.

Profile button과 settings

40-69

$BASE/profile_buttons
$BASE/profile_settings

attribute	payload	내용
profile_buttons	59 byte	profile별 button layout
profile_settings	31 byte	resolution, sensitivity, light effect

각 profile은 settings와 buttons 두 부분으로 나뉜다. profile_buttons에 59 byte를 쓰면 payload 안의 profile 번호가 지정하는 button layout을 mouse에 기록한다. invalid data는 거부된다.

profile_settings에 31 byte를 쓰면 payload 안의 profile 번호가 지정하는 resolution, sensitivity, light effect 설정을 기록한다. 이 경우도 invalid data는 mouse가 거부한다.

두 file을 읽기 전에는 control에 먼저 써서 읽을 profile을 선택해야 한다.

Sensor, Talk와 TCU

71-105

$BASE/sensor
$BASE/talk
$BASE/tcu
$BASE/tcu_image

attribute	payload	access	동작
sensor	6 byte	write-only	tracking·distance unit와 lift-off distance 설정
talk	16 byte	write-only	외부 host에서 easy* 기능 활성화
tcu	4 byte	read/write	calibration 시작·취소와 sensor register 접근
tcu_image	1028 byte	read-only	calibration 중 표면의 30×30 pixel sample

sensor에 6 byte를 쓰면 mouse의 tracking control unit와 distance control unit를 활성화하거나 비활성화하고 lift-off distance를 설정한다.

talk에 16 byte를 쓰면 mouse의 일부 easy* 기능을 외부에서 활성화한다.

tcu에 4 byte를 쓰면 tracking control unit calibration을 시작하거나 취소한다. 같은 attribute로 sensor register를 읽고 쓸 수 있다.

tcu_image는 tcu로 시작한 calibration 과정 중에만 읽을 수 있다. mouse가 sample한 아래 표면의 30×30 pixel image를 1028-byte data로 반환한다.

Konepure TCU calibration 순서

tcu에 4-byte start commandsurface sampling과 sensor calibrationtcu_image read30×30 pixel / 1028-byte 반환tcu에 finish 또는 cancel command

surface image는 일반 상태가 아니라 tcu calibration context 안에서만 유효하다.