diff --git a/docs/design/x52_key_mappings.md b/docs/design/x52_key_mappings.md new file mode 100644 index 0000000..92d637f --- /dev/null +++ b/docs/design/x52_key_mappings.md @@ -0,0 +1,72 @@ +Key mappings for X52 Pro +======================== + +# Key map table + +One simple technique to map the individual keys is as follows: + +| Key | Mode 1 | Mode 2 | Mode 3 | Mode 1 S | Mode 2 S | Mode 3 S | +| ----- | -------- | -------- | -------- | -------- | -------- | -------- | +| Trigg | L Ctrl | `<- M1` | `<- M1` | `<- M1S` | `<- M2S` | `<- M3S` | +| FIRE | SPACE | `<- M1` | `<- M1` | `<- M1S` | `<- M2S` | `<- M3S` | +| ... | | | | | | | +| Pinky | -SHIFT- | -SHIFT- | -SHIFT- | -SHIFT- | -SHIFT- | -SHIFT- | +| D | Tab | `<- M1` | `<- M1` | `<- M1S` | `<- M2S` | `<- M3S` | +| E | Joy E | `<- M1` | `<- M1` | `<- M1S` | `<- M2S` | `<- M3S` | + +The `<- M*` mappings indicate that the key map in the corresponding mode is the +same as in the linked mode. By default, the keys in modes 2 and 3 are linked +with the keymap in mode 1, and the keys in the +shift modes are linked with the +keymap in their primary mode, i.e., mode 1 + shift keymaps are linked with mode +1 keymaps, mode 2 + shift keymaps with mode 2, and mode 3 + shift keymaps with +mode 3. + +Also, it is not necessary to have a specific key bound to each button, instead +it can behave as the same button being pressed, and the application can take +action accordingly. + +# Shift Keys + +The key mapper software for Windows allows the user to map any button to a +keystroke or a set of keystrokes. The keystroke sent is dependent on the mode +and if a shift key is pressed. Although the mapper does allow creation of +several shift keys, this goes to a point of diminishing returns. + +The application design therefore works on the principle of allowing a single +shift key, mapped to the Pinky switch on the stick. The user can choose to +disable the shift mode, reverting to only the mode selector to select the key +maps. + +One additional possibility is to have the shift button latched, i.e., the first +press and release turns on the shift mode, and the next press and release turns +it off. Compare this with the unlatched case where the user must press and hold +the shift button to trigger the shift mode. By default, the shift key is +unlatched, although a user can enable it on a per-profile basis. + +Finally, when the shift mode is entered, this must be indicated by sending the +control message to turn on the SHIFT indicator in the MFD. Similarly, when the +shift mode is exited, the application must turn off the SHIFT indicator. + +# Clutch button + +The clutch feature is an optional enhancement to allow switching of profiles on +the fly, without having to exit the game the user is in. This button (marked +`i`) reports as a regular button, but the Windows driver allows the user to +select it as a clutch. The clutch can also be latched. + +When the clutch button is enabled, entering clutch mode should be signaled by +blinking the clutch and POV hat LEDs. There is a specific message to enable +and disable the blinking. In clutch mode, the hat can be used to select +different profiles displayed on the MFD screen by going in the north and south +directions. The current profile can be cleared by moving the hat west, and the +selected profile can be enabled by moving the hat east. + +When in clutch mode, the other buttons do not send their mappings to the +applicaton, instead, they are captured by the driver and the driver application +will display the current mapping on the MFD. The mode selector however, will +work as expected, by changing the display to highlight the current mode. The +application will also determine the current mapping by examining the mode. + +Clutch mode can only be exited by means of the clutch button. If the clutch +button is disabled, then the clutch button behaves as any normal button and can +be mapped to a keypress. diff --git a/docs/x52_mfd_pages.md b/docs/design/x52_mfd_pages.md similarity index 65% rename from docs/x52_mfd_pages.md rename to docs/design/x52_mfd_pages.md index 511eb39..029b877 100644 --- a/docs/x52_mfd_pages.md +++ b/docs/design/x52_mfd_pages.md @@ -19,23 +19,25 @@ buttons, to allow the programmer to create custom handlers. # API - x52_mfd_create_page(uint8_t *page_id, - char *description, - x52_page_callback *handler) +```c +x52_mfd_create_page(uint8_t *page_id, + char *description, + x52_page_callback *handler) - x52_mfd_write_line(uint8_t page_id, - uint8_t line, - char *text, - uint8_t length) +x52_mfd_write_line(uint8_t page_id, + uint8_t line, + char *text, + uint8_t length) - x52_mfd_update_page(uint8_t page_id, - uint8_t activate) +x52_mfd_update_page(uint8_t page_id, + uint8_t activate) - x52_mfd_delete_page(uint8_t page_id) +x52_mfd_delete_page(uint8_t page_id) - typedef void (*x52_page_callback)(uint8_t page_id, - uint8_t event, - uint8_t state) +typedef void (*x52_page_callback)(uint8_t page_id, + uint8_t event, + uint8_t state) +``` ## Steps @@ -52,11 +54,11 @@ The callback API is a function that takes three arguments as follows: 1. A page ID (8 bits) which identifies the current page. This allows a single callback handler to handle multiple pages. 2. An 8-bit event identifier. Currently, this is defined to be one of: - * X52\_MFD\_EVENT\_UP - * X52\_MFD\_EVENT\_DN - * X52\_MFD\_EVENT\_SEL + * `X52_MFD_EVENT_UP` + * `X52_MFD_EVENT_DN` + * `X52_MFD_EVENT_SEL` 3. An 8-bit state identifier. Currently, this is defined to be one of: - * X52\_MFD\_BUTTON\_STATE\_UP - * X52\_MFD\_BUTTON\_STATE\_DN + * `X52_MFD_BUTTON_STATE_UP` + * `X52_MFD_BUTTON_STATE_DN`