====== Command:EXTRA (EX) ======

-->MS2000 and RM2000 Syntax ^

^Shortcut | EX <wrap lo>//version 9.53//</wrap> |
^Format  |EXTRA [X?] [Y?] [Z=lock_ki] [M=button_code] [R=small_enc] [T?] |
^Remembered |Using SS Z |

<--

--> Tiger Syntax ^

^Shortcut | EX <wrap lo>//version 3.51//</wrap> |
^Format  |[Addr#]EXTRA [X?] [Y?] [Z=lock_ki] [M=button_code] [R=small_enc] [T?] |
^Type |Card-Addressed|
^Remembered |Using [Addr#]SS Z |

<--

**X?**  Provides the ''CRISP'' bottom line string as is shown on the LCD display.

**Y?**  Returns the ''SNR'' value shown on the LCD after log amp calibration.

The **Z** argument sets the integral error servo parameter. The default is ''1''. Higher values may improve speed settling but can also generate instability. Use sparingly.

This is also the ''lock_ki'' value for ''CRISP''. When ''CRISP'' enters the lock state (''LK F=83'') it changes the [[commands:ki|KI Z]] value for the Z axis. ''KI Z'' is restored to the initial value when ''CRISP'' enters the stop state (''LK F=79'').

<WRAP center round info 80%>
When CRISP restores KI Z after using lock_ki, it uses a saved value that is set only once when the controller powers on. If you want to change KI Z, use [[commands:saveset|SS Z]] and power cycle the controller so that it can restore KI Z to the correct value. It is not recommended to set KI Z unless you are an advanced user.
</WRAP>

<wrap lo>MS-2000 9.2p or Tiger v3.42 required</wrap> \\
**T?:** The controller detects the resolution of the ADC during initialization.

^Code^DAC^CPU^
| 0 | 10-bit ADC | ''C8051F122'' |
| 1 | 12-bit ADC | ''C8051F120'' |

<wrap lo>MS-2000 9.2n or Tiger v3.36 required</wrap> \\
**M?** Returns the ''button_flag_byte'' and resets the value to ''0''.

**M=#** Modify the ''button_flag_byte'' with the button code and call the button functions associated with that code.

This command differs from [[commands:benable|BE F]] which does not modify the ''button_flag_byte'' and only calls a single button function.

-->Additional Details About M? ^

The ''button_flag_byte'' stores the state of the last detected button press for each button. When the controller is powered on, the value is initialized to ''0''. As the user presses buttons the value of the ''button_flag_byte'' changes, it is important to note that this value only changes when you **release** the button.

After receiving the ''EXTRA M?'' command, the internal value on the controller is reset to ''0'', enabling you to detect new button presses.

If a button has already been pressed, and then is pressed again, the new state overwrites the old state for that button.
Example: if you do a ''Normal Press'' and then a ''Long Press'' on the ''Joystick Button'', the next time you send the "''EXTRA M?''" command the state of the ''Joystick Button'' will be ''Long Press''.

**Zero/Halt button presses only have the states 0 and 1. (Not Pressed and Normal Press)**

The ''button_flag_byte'' is divided into four ''2-bit'' sections that each contain the state of a button:
^Bits	^Button ^
|1-2	|@ Button|
|3-4	|Home Button|
|5-6	|Joystick Button|
|7-8	|Zero/Halt Button|

Each ''2-bit'' section can take on the values ''0-3'', these codes represent the state of the button.
^Decimal ^Binary ^State ^
|0 | ''00'' |Not Pressed|
|1 | ''01'' |Normal Press|
|2 | ''10'' |Long Press|
|3 | ''11'' |Extra Long Press|

Example:
  - @ Button Normal Press
  - Home Button Long Press
  - Joystick Extra Long Press
  - Zero/Halt Normal Press
  - Send serial command ''EXTRA M?''

\\
Results of steps ''1-5'' in binary:
  - ''button_flag_byte = 00 00 00 01''
  - ''button_flag_byte = 00 00 10 01''
  - ''button_flag_byte = 00 11 10 01''
  - ''button_flag_byte = 01 11 10 01''
  - ''button_flag_byte = 00 00 00 00'' (''serial command reset'')

<--

\\

Example Python code for extracting button states from the button_flag_byte:

{{section>:python_code#parse_button_flag&noheader&nofooter}}

-->Additional Details About M=button_code ^

This function allows you to simulate button presses programmatically through a serial command.

\\
This command modifies the ''button_flag_byte'' and calls the button functions associated with that button code.

The button codes are the same values that are returned by ''EXTRA M?''. The input value is clamped to the range: 0-127.

If a button code represents multiple button presses then the button functions will be called in the order =>\\
@, Home, Joystick, Zero/Halt (LSB => MSB)

You can expect the same behavior as if you were pressing physical buttons =>

  - Send the command ''EXTRA M=3'': ''button_flag_byte'' = 3, @ Extra Long Press button function called.
  - Send the command ''EXTRA M=1'': ''button_flag_byte'' = 1, @ Normal Press button function called.
  - Send the command ''EXTRA M=5'': ''button_flag_byte'' = 5, @ Normal Press and Home Normal Press button functions called.

\\
This demonstrates that button presses are overwritten as if you were interacting with the physical controller pressing buttons.

<--

Example Python code for creating a button_flag_byte:

{{section>:python_code#create_button_flag&noheader&nofooter}}

{{tag>commands tiger ms2000 crisp}}