Roccat Ryos keyboard obsolete ABI | Linux 6.18.37

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

1. 요약·해설

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

Persistent profile과 key map

sysfs-driver-hid-roccat-ryos:1-90

3-byte selector와 persistent profile을 중심으로 primary, function, macro, thumbster, extra, EasyZone key와 key mask를 profile별 binary payload로 관리합니다.

Macro와 variant별 lighting

sysfs-driver-hid-roccat-ryos:92-178

최대 480-keystroke macro, glow/pro backlight intensity와 Pro 전용 stored·custom per-key lighting, dimness-mode light macro를 정의합니다.

2. 영어 원문 전체

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

원문 전체 펼치기

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

2 Date: October 2013

3 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

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

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

6 This file is writeonly.

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

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/profile

10 Date: October 2013

11 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

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

13 press of a button. profile holds index of actual profile.

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

15 that's active when the device is powered on next time.

16 When written, the device activates the set profile immediately.

17 The data has to be 3 bytes long.

18 The device will reject invalid data.

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

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_primary

22 Date: October 2013

23 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

24 Description: When written, this file lets one set the default of all keys for

25 a specific profile. Profile index is included in written data.

26 The data has to be 125 bytes long.

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

28 which profile to read.

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

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_function

32 Date: October 2013

33 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

34 Description: When written, this file lets one set the function of the

35 function keys for a specific profile. Profile index is included

36 in written data. The data has to be 95 bytes long.

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

38 which profile to read.

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

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_macro

42 Date: October 2013

43 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

44 Description: When written, this file lets one set the function of the macro

45 keys for a specific profile. Profile index is included in

46 written data. The data has to be 35 bytes long.

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

48 which profile to read.

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

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_thumbster

52 Date: October 2013

53 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

54 Description: When written, this file lets one set the function of the

55 thumbster keys for a specific profile. Profile index is included

56 in written data. The data has to be 23 bytes long.

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

58 which profile to read.

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

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_extra

62 Date: October 2013

63 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

64 Description: When written, this file lets one set the function of the

65 capslock and function keys for a specific profile. Profile index

66 is included in written data. The data has to be 8 bytes long.

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>/ryos/roccatryos<minor>/keys_easyzone

72 Date: October 2013

73 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

74 Description: When written, this file lets one set the function of the

75 easyzone keys for a specific profile. Profile index is included

76 in written data. The data has to be 294 bytes long.

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

78 which profile to read.

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

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/key_mask

82 Date: October 2013

83 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

84 Description: When written, this file lets one deactivate certain keys like

85 windows and application keys, to prevent accidental presses.

86 Profile index for which this settings occur is included in

87 written data. The data has to be 6 bytes long.

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

89 which profile to read.

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

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/light

93 Date: October 2013

94 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

95 Description: When written, this file lets one set the backlight intensity for

96 a specific profile. Profile index is included in written data.

97 This attribute is only valid for the glow and pro variant.

98 The data has to be 16 bytes long.

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

100 which profile to read.

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

102

103

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

104 Date: October 2013

105 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

106 Description: When written, this file lets one store macros with max 480

107 keystrokes for a specific button for a specific profile.

108 Button and profile indexes are included in written data.

109 The data has to be 2002 bytes long.

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

111 which profile and key to read.

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

113

114

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

115 Date: October 2013

116 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

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

118 The data is 8 bytes long.

119 This file is readonly.

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

121

122

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/reset

123 Date: October 2013

124 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

125 Description: When written, this file lets one reset the device.

126 The data has to be 3 bytes long.

127 This file is writeonly.

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

129

130

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

131 Date: October 2013

132 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

133 Description: When written, this file lets one trigger easyshift functionality

134 from the host.

135 The data has to be 16 bytes long.

136 This file is writeonly.

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

138

139

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/light_control

140 Date: October 2013

141 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

142 Description: When written, this file lets one switch between stored and custom

143 light settings.

144 This attribute is only valid for the pro variant.

145 The data has to be 8 bytes long.

146 This file is writeonly.

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

148

149

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/stored_lights

150 Date: October 2013

151 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

152 Description: When written, this file lets one set per-key lighting for different

153 layers.

154 This attribute is only valid for the pro variant.

155 The data has to be 1382 bytes long.

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

157 which profile to read.

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

159

160

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/custom_lights

161 Date: October 2013

162 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

163 Description: When written, this file lets one set the actual per-key lighting.

164 This attribute is only valid for the pro variant.

165 The data has to be 20 bytes long.

166 This file is writeonly.

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

168

169

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/light_macro

170 Date: October 2013

171 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

172 Description: When written, this file lets one set a light macro that is looped

173 whenever the device gets in dimness mode.

174 This attribute is only valid for the pro variant.

175 The data has to be 2002 bytes long.

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

177 which profile to read.

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

179

3. 한국어 전문 번역

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

control과 persistent profile

1-19

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

$BASE/control
$BASE/profile

모든 항목의 Date는 2013년 10월, contact는 Stefan Achatz <erazor_de@users.sourceforge.net>, user는 http://roccat.sourceforge.net다.

attribute	payload	access	동작
control	3 byte	write-only	다음 read의 profile과 data 선택
profile	3 byte	read/write	현재 profile index와 다음 power-on profile 저장

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

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

Profile별 key map과 key mask

21-90

$BASE/keys_primary
$BASE/keys_function
$BASE/keys_macro
$BASE/keys_thumbster
$BASE/keys_extra
$BASE/keys_easyzone
$BASE/key_mask

attribute	payload	설정 대상
keys_primary	125 byte	특정 profile의 모든 primary key 기본 기능
keys_function	95 byte	function key 기능
keys_macro	35 byte	macro key 기능
keys_thumbster	23 byte	thumbster key 기능
keys_extra	8 byte	Caps Lock과 function key 기능
keys_easyzone	294 byte	EasyZone key 기능
key_mask	6 byte	Windows·application key 같은 특정 key 비활성화

각 key map attribute에 쓰면 payload 안의 profile index가 지정하는 profile에 해당 key 기능을 설정한다. payload 길이는 표의 고정 크기와 정확히 같아야 한다.

key_mask는 실수로 누르는 것을 막기 위해 Windows key와 application key 같은 특정 key를 비활성화한다. 적용 profile index가 6-byte data에 포함된다.

이 일곱 file을 읽기 전에는 control에 써서 읽을 profile을 선택해야 한다.

Profile light, macro와 info

92-120

$BASE/light
$BASE/macro
$BASE/info

attribute	payload	access	동작
light	16 byte	read/write	glow·pro variant의 profile별 backlight intensity
macro	2002 byte	read/write	특정 profile·button의 최대 480-keystroke macro
info	8 byte	read-only	firmware version 등 일반 device data

light는 glow와 pro variant에서만 유효하다. 16-byte data에 profile index를 포함해 backlight intensity를 설정한다. 읽기 전에는 control로 profile을 선택해야 한다.

macro에 쓰면 특정 profile의 특정 button에 최대 480 keystroke를 저장한다. 2002-byte data에 button index와 profile index가 포함된다. 읽기 전에는 control로 profile과 key를 모두 선택해야 한다.

info를 읽으면 firmware version 같은 일반 device data 8 byte를 반환한다.

Reset, Talk와 Pro per-key lighting

122-178

$BASE/reset
$BASE/talk
$BASE/light_control
$BASE/stored_lights
$BASE/custom_lights
$BASE/light_macro

attribute	payload	access	variant·동작
reset	3 byte	write-only	device reset
talk	16 byte	write-only	host에서 EasyShift trigger
light_control	8 byte	write-only	Pro: stored/custom light 설정 전환
stored_lights	1382 byte	read/write	Pro: layer별 per-key lighting 저장
custom_lights	20 byte	write-only	Pro: 현재 per-key lighting 설정
light_macro	2002 byte	read/write	Pro: dimness mode에서 반복할 light macro

reset에 3 byte를 쓰면 device를 reset하고 talk에 16 byte를 쓰면 host에서 EasyShift 기능을 trigger한다.

light_control은 Pro variant에서만 유효하며 stored light 설정과 custom light 설정 사이를 전환한다.

stored_lights는 Pro variant에서 layer별 per-key lighting을 1382-byte payload로 설정한다. 읽기 전에는 control로 profile을 선택해야 한다.

custom_lights는 Pro variant의 현재 per-key lighting을 20-byte write-only payload로 즉시 설정한다.

light_macro는 device가 dimness mode에 들어갈 때 반복 실행할 light macro를 2002 byte로 설정한다. Pro variant에서만 유효하며 읽기 전에는 control로 profile을 선택해야 한다.

Ryos Pro lighting 선택 경로

stored_lights: profile·layer별 1382 bytelight_control: stored modeper-key output

custom_lights: 현재 20 bytelight_control: custom modeper-key output

light_macro: 2002 bytedimness modelooped lighting

light_control이 persistent layer data와 즉시 적용하는 custom data 중 어느 source를 사용할지 전환한다.