500 lines
14 KiB
JSON
500 lines
14 KiB
JSON
{
|
|
"schema": "kk-control-vocabulary/2",
|
|
"_what_this_is": [
|
|
"Everything a pad or a keyboard can say, and nothing about what any of it",
|
|
"means.",
|
|
"",
|
|
"That split is this package's own rule -- it reports that the left stick is at",
|
|
"(0.4, -0.9), that A is down and that keypad_8 is down, and deciding that any",
|
|
"of that is 0.2 m/s forward belongs to whoever is driving. So the words live",
|
|
"here and the meanings live with the consumer: `[[fsm.button]]` in a deploy",
|
|
"manifest, `controls.yaml` in a task.",
|
|
"",
|
|
"Read by three programs and written by none of them:",
|
|
" controller/vocabulary.py python -m controller --vocabulary",
|
|
" deploy/fsm/src/vocabulary.rs include_str!, so a board carries no file",
|
|
" tasks/.../mdp/controls.py validating a task's controls.yaml",
|
|
"",
|
|
"It had a copy in each of those for a day. Adding a word meant remembering two",
|
|
"other files, and forgetting one leaves a name that reads as supported and is",
|
|
"refused on build -- or, worse, the other way round.",
|
|
"",
|
|
"Was `kk-gamepad-vocabulary/1`, when the pad was the only thing it described.",
|
|
"The keys below were a closed list too and were not written down anywhere a",
|
|
"consumer could check, so `[[fsm.button]] key = ...` took any string at all: a",
|
|
"typo loaded, bound nothing, and looked exactly like a rule that had not fired."
|
|
],
|
|
"_source": {
|
|
"service": "control-pod-svc",
|
|
"repo": "robot/embedded-software/soc/apps/control-pod-svc",
|
|
"read_from": [
|
|
"include/gamepad/gamepad_state.hpp",
|
|
"src/gamepad/gamepad_dds_message.cpp"
|
|
],
|
|
"topic": "RobotControlRaw_ControlRaw",
|
|
"note": "It normalises three different pads onto these names, so they mean the same thing on a bench and on the robot. Its own docs put the count at 18: 10 buttons + 2 dpad axes + 6 axes."
|
|
},
|
|
"buttons": [
|
|
{
|
|
"name": "A"
|
|
},
|
|
{
|
|
"name": "B"
|
|
},
|
|
{
|
|
"name": "X",
|
|
"unresolved": "controller/xbox.py reads evdev 307 as `y` and 308 as `x`; the service's table reads 307 as X and 308 as Y. One is wrong about which physical button it is and pressing it is the only way to find out which."
|
|
},
|
|
{
|
|
"name": "Y",
|
|
"unresolved": "see X"
|
|
},
|
|
{
|
|
"name": "LB"
|
|
},
|
|
{
|
|
"name": "RB"
|
|
},
|
|
{
|
|
"name": "menu"
|
|
},
|
|
{
|
|
"name": "home",
|
|
"note": "`xbox` in controller/xbox.py. Same button, two names."
|
|
},
|
|
{
|
|
"name": "L3"
|
|
},
|
|
{
|
|
"name": "R3"
|
|
}
|
|
],
|
|
"dpad": [
|
|
{
|
|
"name": "dpad_up"
|
|
},
|
|
{
|
|
"name": "dpad_down"
|
|
},
|
|
{
|
|
"name": "dpad_left"
|
|
},
|
|
{
|
|
"name": "dpad_right"
|
|
}
|
|
],
|
|
"_dpad_note": "The wire carries dpad_x / dpad_y as -1 / 0 / +1, which no gesture can read, so they are offered as four booleans. The service negates dpad_y so +1 is up; it does not negate Ly, two lines away in the same function.",
|
|
"axes": [
|
|
{
|
|
"name": "Lx",
|
|
"range": [
|
|
-1,
|
|
1
|
|
]
|
|
},
|
|
{
|
|
"name": "Ly",
|
|
"range": [
|
|
-1,
|
|
1
|
|
],
|
|
"note": "Not negated by the service. Forward is the negative end, by evdev's convention -- stated in controller/xbox.py and never measured against this service."
|
|
},
|
|
{
|
|
"name": "Rx",
|
|
"range": [
|
|
-1,
|
|
1
|
|
]
|
|
},
|
|
{
|
|
"name": "Ry",
|
|
"range": [
|
|
-1,
|
|
1
|
|
]
|
|
},
|
|
{
|
|
"name": "LT",
|
|
"range": [
|
|
0,
|
|
1
|
|
],
|
|
"note": "Unipolar: a trigger never reports negative."
|
|
},
|
|
{
|
|
"name": "RT",
|
|
"range": [
|
|
0,
|
|
1
|
|
]
|
|
}
|
|
],
|
|
"_axes_note": "Sticks carry a 0.15 deadband that is already applied **and rescaled**, so full deflection still reaches ±1. A consumer that applies its own on top narrows what a person can ask for and cannot see that it has.",
|
|
"keys": [
|
|
{
|
|
"name": "keypad_0",
|
|
"glfw": 320,
|
|
"browser": "Numpad0"
|
|
},
|
|
{
|
|
"name": "keypad_1",
|
|
"glfw": 321,
|
|
"browser": "Numpad1"
|
|
},
|
|
{
|
|
"name": "keypad_2",
|
|
"glfw": 322,
|
|
"browser": "Numpad2"
|
|
},
|
|
{
|
|
"name": "keypad_3",
|
|
"glfw": 323,
|
|
"browser": "Numpad3"
|
|
},
|
|
{
|
|
"name": "keypad_4",
|
|
"glfw": 324,
|
|
"browser": "Numpad4"
|
|
},
|
|
{
|
|
"name": "keypad_5",
|
|
"glfw": 325,
|
|
"browser": "Numpad5"
|
|
},
|
|
{
|
|
"name": "keypad_6",
|
|
"glfw": 326,
|
|
"browser": "Numpad6"
|
|
},
|
|
{
|
|
"name": "keypad_7",
|
|
"glfw": 327,
|
|
"browser": "Numpad7"
|
|
},
|
|
{
|
|
"name": "keypad_8",
|
|
"glfw": 328,
|
|
"browser": "Numpad8"
|
|
},
|
|
{
|
|
"name": "keypad_9",
|
|
"glfw": 329,
|
|
"browser": "Numpad9"
|
|
},
|
|
{
|
|
"name": "keypad_.",
|
|
"glfw": 330,
|
|
"browser": "NumpadDecimal"
|
|
},
|
|
{
|
|
"name": "keypad_/",
|
|
"glfw": 331,
|
|
"browser": "NumpadDivide"
|
|
},
|
|
{
|
|
"name": "keypad_*",
|
|
"glfw": 332,
|
|
"browser": "NumpadMultiply"
|
|
},
|
|
{
|
|
"name": "keypad_-",
|
|
"glfw": 333,
|
|
"browser": "NumpadSubtract"
|
|
},
|
|
{
|
|
"name": "keypad_+",
|
|
"glfw": 334,
|
|
"browser": "NumpadAdd"
|
|
},
|
|
{
|
|
"name": "keypad_enter",
|
|
"glfw": 335,
|
|
"browser": "NumpadEnter"
|
|
},
|
|
{
|
|
"name": "key_w",
|
|
"glfw": 87,
|
|
"browser": "KeyW"
|
|
},
|
|
{
|
|
"name": "key_s",
|
|
"glfw": 83,
|
|
"browser": "KeyS"
|
|
},
|
|
{
|
|
"name": "key_a",
|
|
"glfw": 65,
|
|
"browser": "KeyA"
|
|
},
|
|
{
|
|
"name": "key_d",
|
|
"glfw": 68,
|
|
"browser": "KeyD"
|
|
},
|
|
{
|
|
"name": "key_j",
|
|
"glfw": 74,
|
|
"browser": "KeyJ"
|
|
},
|
|
{
|
|
"name": "key_l",
|
|
"glfw": 76,
|
|
"browser": "KeyL"
|
|
},
|
|
{
|
|
"name": "key_i",
|
|
"glfw": 73,
|
|
"browser": "KeyI"
|
|
},
|
|
{
|
|
"name": "key_k",
|
|
"glfw": 75,
|
|
"browser": "KeyK"
|
|
},
|
|
{
|
|
"name": "key_m",
|
|
"glfw": 77,
|
|
"browser": "KeyM"
|
|
},
|
|
{
|
|
"name": "key_o",
|
|
"glfw": 79,
|
|
"browser": "KeyO"
|
|
},
|
|
{
|
|
"name": "key_q",
|
|
"glfw": 81,
|
|
"browser": "KeyQ"
|
|
},
|
|
{
|
|
"name": "key_h",
|
|
"glfw": 72,
|
|
"browser": "KeyH"
|
|
},
|
|
{
|
|
"name": "key_b",
|
|
"glfw": 66,
|
|
"browser": "KeyB"
|
|
},
|
|
{
|
|
"name": "key_g",
|
|
"glfw": 71,
|
|
"browser": "KeyG"
|
|
},
|
|
{
|
|
"name": "key_space",
|
|
"glfw": 32,
|
|
"browser": "Space"
|
|
},
|
|
{
|
|
"name": "key_right",
|
|
"glfw": 262,
|
|
"browser": "ArrowRight"
|
|
},
|
|
{
|
|
"name": "key_left",
|
|
"glfw": 263,
|
|
"browser": "ArrowLeft"
|
|
},
|
|
{
|
|
"name": "key_down",
|
|
"glfw": 264,
|
|
"browser": "ArrowDown"
|
|
},
|
|
{
|
|
"name": "key_up",
|
|
"glfw": 265,
|
|
"browser": "ArrowUp"
|
|
},
|
|
{
|
|
"name": "key_left_ctrl",
|
|
"glfw": 341,
|
|
"browser": "ControlLeft"
|
|
},
|
|
{
|
|
"name": "key_right_ctrl",
|
|
"glfw": 345,
|
|
"browser": "ControlRight"
|
|
},
|
|
{
|
|
"name": "key_1",
|
|
"glfw": 49,
|
|
"browser": "Digit1"
|
|
},
|
|
{
|
|
"name": "key_2",
|
|
"glfw": 50,
|
|
"browser": "Digit2"
|
|
},
|
|
{
|
|
"name": "key_3",
|
|
"glfw": 51,
|
|
"browser": "Digit3"
|
|
},
|
|
{
|
|
"name": "key_4",
|
|
"glfw": 52,
|
|
"browser": "Digit4"
|
|
},
|
|
{
|
|
"name": "key_n",
|
|
"glfw": 78,
|
|
"browser": "KeyN"
|
|
},
|
|
{
|
|
"name": "key_u",
|
|
"glfw": 85,
|
|
"browser": "KeyU"
|
|
},
|
|
{
|
|
"name": "key_v",
|
|
"glfw": 86,
|
|
"browser": "KeyV"
|
|
},
|
|
{
|
|
"name": "key_semicolon",
|
|
"glfw": 59,
|
|
"browser": "Semicolon"
|
|
},
|
|
{
|
|
"name": "key_escape",
|
|
"glfw": 256,
|
|
"browser": "Escape"
|
|
},
|
|
{
|
|
"name": "key_left_shift",
|
|
"glfw": 340,
|
|
"browser": "ShiftLeft"
|
|
},
|
|
{
|
|
"name": "key_right_shift",
|
|
"glfw": 344,
|
|
"browser": "ShiftRight"
|
|
},
|
|
{
|
|
"name": "key_left_alt",
|
|
"glfw": 342,
|
|
"browser": "AltLeft"
|
|
},
|
|
{
|
|
"name": "key_right_alt",
|
|
"glfw": 346,
|
|
"browser": "AltRight"
|
|
}
|
|
],
|
|
"modifiers": [
|
|
{
|
|
"name": "ctrl",
|
|
"keys": ["key_left_ctrl", "key_right_ctrl"]
|
|
},
|
|
{
|
|
"name": "shift",
|
|
"keys": ["key_left_shift", "key_right_shift"]
|
|
},
|
|
{
|
|
"name": "alt",
|
|
"keys": ["key_left_alt", "key_right_alt"]
|
|
}
|
|
],
|
|
"_modifiers_note": [
|
|
"A modifier is either of its two keys: `ctrl` is down while the left Ctrl or the",
|
|
"right one is. A keyboard binding may name one on its own -- `ctrl`, a key like",
|
|
"any other -- or in front of a key, `shift+key_j`, which is J while Shift is",
|
|
"held. A key bound both ways answers the modified binding while its modifier is",
|
|
"down and the plain one otherwise, so J and Shift + J are two things and never",
|
|
"both. A mode switch names one as `with`, as a pad switch names `menu`.",
|
|
"",
|
|
"Alt costs a browser something: pressed and let go on its own, Windows moves",
|
|
"focus to the browser's menu, and the keys after it go there rather than to the",
|
|
"page, which has to `preventDefault` it. MuJoCo's viewer uses all three with the",
|
|
"mouse and does nothing with any of them alone."
|
|
],
|
|
"_keys_note": [
|
|
"The numeric keypad, and letters as a task asks for them -- each one knowing",
|
|
"what it costs.",
|
|
"",
|
|
"The keypad is the set MuJoCo's viewer does not bind. Everything else on the",
|
|
"main keyboard is bound: `Simulate` handles its shortcuts in C++ and calls the",
|
|
"user callback **as well as**, never instead, so a letter fires both actions",
|
|
"and there is no way to intercept the second.",
|
|
"",
|
|
"MEASURED against this repository's mujoco, by reading `mjVISSTRING` and",
|
|
"`mjRNDSTRING` -- **all twenty-six letters are taken**, one render flag each:",
|
|
"",
|
|
" A auto-connect B perturb force C contact point D static body",
|
|
" E equality F contact force G fog H convex hull",
|
|
" I inertia J joint K skybox L additive",
|
|
" M centre of mass N island O perturb object P contact split",
|
|
" Q camera R reflection S shadow T transparent",
|
|
" U actuator V tendon W wireframe X texture",
|
|
" Y range finder Z light and ' , / ; \\\\ ` as well",
|
|
"",
|
|
"The generated locomotion bindings use W A S D and the arrows for planar",
|
|
"motion, J L to turn, and Esc to release. These keys still reach the viewer.",
|
|
"For example, W also toggles wireframe and the left and right arrows step a",
|
|
"paused simulation.",
|
|
"",
|
|
"Main-row digits 1 to 4 toggle the corresponding geom groups. Keypad digits",
|
|
"leave the viewer flags unchanged and can be bound independently. Space",
|
|
"pauses the viewer. Legacy FSM mode keys are specified by the bundle.",
|
|
"",
|
|
"**MuJoCo's viewer reports a key's press and nothing else.** The callback is",
|
|
"handed a keycode and no action (`KeyCallbackType = Callable[[int], None]`), on",
|
|
"a press only: MuJoCo's GLFW adapter drops the auto-repeat and the release.",
|
|
"`mjrl.viewer.keys` puts a GLFW key callback of its own in front of the",
|
|
"viewer's and hands every reader both edges, so a key is held from its press to",
|
|
"its release, as in a browser, which reports both itself. Until 2026-09-29 the",
|
|
"release was inferred from repeats that never came, and every key let go 0.75 s",
|
|
"after its press.",
|
|
"",
|
|
"Browser codes carry over unchanged -- `KeyW` is `KeyW` whatever the viewer",
|
|
"does -- so a web consumer pays nothing for this at all."
|
|
],
|
|
"gestures": [
|
|
{
|
|
"name": "rise",
|
|
"fires": "the tick it goes down, one-shot"
|
|
},
|
|
{
|
|
"name": "fall",
|
|
"fires": "the tick it comes back up, one-shot"
|
|
},
|
|
{
|
|
"name": "hold",
|
|
"fires": "every tick it is down -- a dead-man switch, not a mode"
|
|
},
|
|
{
|
|
"name": "toggle",
|
|
"fires": "down until pressed again -- the default for entering a mode"
|
|
},
|
|
{
|
|
"name": "single",
|
|
"fires": "one press and no second inside the click window; switches like `toggle`"
|
|
},
|
|
{
|
|
"name": "double",
|
|
"fires": "two presses, each inside the click window of the last; switches like `toggle`"
|
|
},
|
|
{
|
|
"name": "triple",
|
|
"fires": "three presses, each inside the click window of the last; switches like `toggle`"
|
|
},
|
|
{
|
|
"name": "quadruple",
|
|
"fires": "four presses, each inside the click window of the last; switches like `toggle`"
|
|
},
|
|
{
|
|
"name": "quintuple",
|
|
"fires": "five presses, each inside the click window of the last; switches like `toggle`"
|
|
}
|
|
],
|
|
"_gestures_note": "A control may be bound more than once with different gestures: press to arm and release to go is one button, `rise` and `fall`, named twice. The five click gestures count presses of one control -- the same pad button or key, with the same modifier -- and a press counts when it comes within `click_window_ms` (`[fsm]` in the controller's config) of the one before. A count fires the binding for it the moment no longer count on that control is bound, and otherwise once the window has run out with no further press; so `single` fires at once where it is the only click on its control and waits out the window where a `double` shares it. A click switches a mode the way `toggle` does, and an `event` fires once. A control with a click gesture takes no `rise`, `fall`, `hold` or `toggle` -- every click would be one of those first. This note used to say there would be no double click, because counting needs a clock and a clock depends on how often a host ticks. The window is measured on the timestamps every host already hands the controller, not in ticks, so a host at 50 Hz and one at 1 kHz count the same presses the same way; the resolution is the host's rate, far inside any window a person can click to. No long press: nothing has asked for one.",
|
|
"absent": [
|
|
{
|
|
"name": "view",
|
|
"why": "The pad has this button and the service deliberately does not publish it. Binding it works on a bench through controller/xbox.py, which does report it, and does nothing at all on the robot."
|
|
}
|
|
]
|
|
}
|