# SCS

## Defines
#define | SCS_MAX_STR (SCS_LCD_MAX_COLUMNS+50)
## Functions
s32 | SCS_Init (u32 mode)
s32 | SCS_NumMenuItemsGet (void)
s32 | SCS_NumMenuItemsSet (u8 num_items)
s32 | SCS_PinSet (u8 pin, u8 depressed)
s32 | SCS_PinGet (u8 pin)
s32 | SCS_AllPinsSet (u16 newState)
s32 | SCS_AllPinsGet (void)
s32 | SCS_EncButtonUpdate_Tick (void)
s32 | SCS_ENC_MENU_NotifyChange (s32 incrementer)
s32 | SCS_ENC_MENU_AutoSpeedSet (u16 maxValue)
s32 | SCS_DIN_NotifyToggle (u8 pin, u8 depressed)
s32 | SCS_Tick (void)
s32 | SCS_InstallRoot (scs_menu_page_t *_rootTable, u8 numItems)
s32 | SCS_InstallDisplayHook (s32(*stringFunct)(char *line1, char *line2))
s32 | SCS_InstallEncHook (s32(*encFunct)(s32 incrementer))
s32 | SCS_InstallButtonHook (s32(*buttonFunct)(u8 scsButton, u8 depressed))
s32 | SCS_DisplayUpdateRequest (void)
s32 | SCS_DisplayUpdateInMainPage (u8 enable)
scs_menu_state_t | SCS_MenuStateGet (void)
scs_menu_item_t * | SCS_MenuPageGet (void)
s32 | SCS_ChangePage (scs_menu_item_t *page)
s32 | SCS_ShowSelectedItem (u8 itemNum)
s32 | SCS_Msg (scs_msg_type_t msgType, u16 delay, char *line1, char *line2)
s32 | SCS_MsgStop (void)
s32 | SCS_InstallDelayedActionCallback (void(*callback)(u32 parameter), u16 delay_mS, u32 parameter)
s32 | SCS_UnInstallDelayedActionCallback (void(*callback)(u32 parameter))
s32 | SCS_InstallEditStringCallback (void(*selectCallback)(char *newString), char *actionString, char *initialString, u8 maxChars)
s32 | SCS_InstallEditIpCallback (void(*selectCallback)(u32 newIp), char *headerString, u32 initialIp)
s32 | SCS_InstallEditBrowserCallback (void(*selectCallback)(char *newString), u8(*getListCallback)(u8 offset, char *line), char *actionString, u8 itemWidth, u8 itemsPerPage)
s32 | SCS_LCD_Init (u32 mode)
s32 | SCS_LCD_DeviceGet (void)
s32 | SCS_LCD_DeviceSet (u8 device)
s32 | SCS_LCD_OffsetXGet (void)
s32 | SCS_LCD_OffsetXSet (u8 x_offset)
s32 | SCS_LCD_OffsetYGet (void)
s32 | SCS_LCD_OffsetYSet (u8 y_offset)
s32 | SCS_LCD_Clear (void)
s32 | SCS_LCD_PrintChar (char c)
s32 | SCS_LCD_BufferSet (u16 x, u16 y, char *str)
s32 | SCS_LCD_CursorSet (u16 column, u16 line)
s32 | SCS_LCD_Update (u8 force)
s32 | SCS_LCD_InitSpecialChars (scs_lcd_charset_t charset, u8 force)
s32 | SCS_LCD_SpecialCharsReInit (void)
s32 | SCS_LCD_PrintString (char *str)
s32 | SCS_LCD_PrintFormattedString (char *format,...)
s32 | SCS_LCD_PrintSpaces (int num)
s32 | SCS_LCD_PrintStringPadded (char *str, u32 width)
s32 | SCS_LCD_PrintStringCentered (char *str, u32 width)

## Detailed Description

This code handles the Standard Control Surface (SCS) with a 2x20 LCD, 5 soft buttons, one rotary encoder and one MENU button

Usage example: apps/tutorials/027_scs

Optional compile flags which can be added to mios32_config.h

     // optionally these 8 pins can be re-assigned
     // note that you could also assign them to global variables for soft-configuration!
     // Encoder pins can be disabled by setting value 255 (use SCS_PIN_DEC/INC in this case)
     #define SCS_PIN_ENC_MENU_A 0
     #define SCS_PIN_ENC_MENU_B 1
     #define SCS_PIN_EXIT       2
     #define SCS_PIN_SOFT1      3
     #define SCS_PIN_SOFT2      4
     #define SCS_PIN_SOFT3      5
     #define SCS_PIN_SOFT4      6
     #define SCS_PIN_SOFT5      7 // optional if SCS_NUM_MENU_ITEMS >= 5
     #define SCS_PIN_SOFT6      8 // optional if SCS_NUM_MENU_ITEMS >= 6
     #define SCS_PIN_SOFT7      9 // optional if SCS_NUM_MENU_ITEMS >= 7
     #define SCS_PIN_SOFT8      10 // optional if SCS_NUM_MENU_ITEMS >= 8
     #define SCS_PIN_SOFT9      11 // optional if SCS_NUM_MENU_ITEMS >= 9
     #define SCS_PIN_SOFT10     12 // optional if SCS_NUM_MENU_ITEMS >= 10

     // if set to 1, the menu handler doesn't require a soft button
     // instead, items are selected with the rotary encoder, and the selection is
     // confirmed with a "SELECT" button (button connected to SCS_PIN_SOFT1)
     // The remaining SOFT buttons have no function!
     #define SCS_MENU_NO_SOFT_BUTTON_MODE 0

     // Optional Inc/Dec button (e.g. as encoder replacement)
     // it's save to assign them to the same pins like the encoder (SCS_PIN_ENC_MENU_A and SCS_PIN_ENC_MENU_B)
     // in order to use the DEC/INC pins, either disable the encoder by assigning SCS_PIN_ENC to invalid values
     // (e.g. 255), or set SCS_PIN_* to free pins
     //
     // the optional DEC button
     #define SCS_PIN_DEC 0
     // the optional INC button
     #define SCS_PIN_INC 1

     // encoder id which is used for MIOS32_ENC
     #define SCS_ENC_MENU_ID 0

     // the encoder type (see mios32_enc.h for available types)
     #define SCS_ENC_MENU_TYPE DETENTED2

     // number of menu items which are displayed on screen
     // each item allocates 5x2 characters
     #define SCS_NUM_MENU_ITEMS 4

     // width of an item (5 by default, so that 4 items can be output on a 2x20 LCD)
     #define SCS_MENU_ITEM_WIDTH 5

     // threshold for automatic toggle mode
     // if the maximum value of an item is >0, and <=SCS_MENU_ITEM_TOGGLE_THRESHOLD is
     // selected with a soft button, the item value will be immediately incremented
     // and not selected
     #define SCS_MENU_ITEM_TOGGLE_THRESHOLD 4

     // maximum width of a temporary message
     #define SCS_MSG_MAX_CHAR 20

     // Debounce counter reload value (in mS)
     // Allowed values 0..255 - 0 turns off debouncing
     #define SCS_BUTTON_DEBOUNCE_RELOAD 20

LCD utility functions for Standard Control Surface

Re-Used from MIDIbox SEQ V4 project, here the original doc:

========================================================================== The 2x80 screen is buffered and can be output over multiple LCDs (e.g. 2 * 2x40, but also 4 * 2x20)

The application should only access the displays via SEQ_LCD_* commands.

The buffer method has the advantage, that multiple tasks can write to the LCD without accessing the IO pins or the requirement for semaphores (to save time)

Only changed characters (marked with flag 7 of each buffer byte) will be transfered to the LCD. This greatly improves performance as well, especially if a graphical display should ever be supported by MBSEQ, but also in the emulation.

Another advantage: LCD access works independent from the physical dimension of the LCDs. They are combined to one large 2x80 display, and SEQ_LCD_Update() will take care for switching between the devices and setting the cursor. If different LCDs should be used, only SCS_LCD_Update() needs to be changed. ==========================================================================

By default we configure this driver to support a single LCD with the size 2x<SCS_NUM_MENU_ITEMS*SCS_MENU_ITEM_WIDTH> (see scs_lcd.h, this size can be overruled from external, e.g. in mios32_config.h)

## Define Documentation

#define SCS_MAX_STR (SCS_LCD_MAX_COLUMNS+50)

## Function Documentation

s32 SCS_AllPinsGet | ( | void |  | ) |

Returns the current state of all pins

Returns:
  the state of all pins

s32 SCS_AllPinsSet | ( | u16 | newState | ) |

Call this function to set all SCS pins at once

Parameters:

  `[in]` | newState | new state of all pins

Returns:
  < 0 on errors

s32 SCS_ChangePage | ( | scs_menu_item_t * | page | ) |

Changes to the given page

s32 SCS_DIN_NotifyToggle | ( | u8 | pin,
|  | u8 | depressed |
| ) |  |  |

This function should be called from APP_DIN_NotifyToggle when a button has been toggled

Parameters:

  `[in]` | pin | the pin number (SCS_PIN_xxx)
  `[in]` | depressed | the pin state

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 SCS_DisplayUpdateInMainPage | ( | u8 | enable | ) |

Enables/Disables LCD output when SCS is in SCS_MENU_STATE_MAINPAGE

Returns:
  < 0 on errors

s32 SCS_DisplayUpdateRequest | ( | void |  | ) |

Can be called from external to force a display update

Returns:
  < 0 on errors

s32 SCS_ENC_MENU_AutoSpeedSet | ( | u16 | maxValue | ) |

This function changes the encoder speed depending on the item value range It's called when a new parameter has been selected Optionally it can be called from external (selection function) if another speed setting is desired

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 SCS_ENC_MENU_NotifyChange | ( | s32 | incrementer | ) |

This function should be called from APP_ENC_NotifyChange when the encoder has been moved

Parameters:

  `[in]` | incrementer | the incrementer (+/- 1)

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 SCS_EncButtonUpdate_Tick | ( | void |  | ) |

This handler should be called periodically from APP_SRIO_ServicePrepare

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 SCS_Init | ( | u32 | mode | ) |

Initialisation of Standard Control Surface

Parameters:

  `[in]` | mode | currently only mode 0 supported

Returns:
  < 0 if initialisation failed

Here is the call graph for this function:

s32 SCS_InstallButtonHook | ( | s32(*)(u8 scsButton, u8 depressed) | buttonFunct | ) |

Installs button handler for overruling If it returns 0, the button movement will be handled by the SCS If it returns 1, the SCS will ignore the button event

Parameters:

  `[in]` | buttonFunct | the button function

Returns:
  < 0 on errors

s32 SCS_InstallDelayedActionCallback | ( | void(*)(u32 parameter) | callback,
|  | u16 | delay_mS,
|  | u32 | parameter |
| ) |  |  |

Function will be called after given delay with given parameter
See tutorial/027_scs for usage example
Note that only a single callback function can be handled, if another one was active before, it will be dropped.

Here is the call graph for this function:

s32 SCS_InstallDisplayHook | ( | s32(*)(char *line1, char *line2) | stringFunct | ) |

Installs string function which can overrule the display output If it returns 0, the original SCS output will be print If it returns 1, the output copied into line1 and/or line2 will be print If a line is not changed (line[0] = 0 or line[1] = 0), the original output will be displayed - this allows to overrule only a single line

Parameters:

  `[in]` | stringFunct | pointer to print function

Returns:
  < 0 on errors

s32 SCS_InstallEditBrowserCallback | ( | void(*)(char *newString) | selectCallback,
|  | u8(*)(u8 offset, char *line) | getListCallback,
|  | char * | actionString,
|  | u8 | itemWidth,
|  | u8 | itemsPerPage |
| ) |  |  |

Can be called from an item select function to enter IP editing mode See tutorial/027_scs for usage example

s32 SCS_InstallEditIpCallback | ( | void(*)(u32 newIp) | selectCallback,
|  | char * | headerString,
|  | u32 | initialIp |
| ) |  |  |

Can be called from an item select function to enter IP editing mode See tutorial/027_scs for usage example

s32 SCS_InstallEditStringCallback | ( | void(*)(char *newString) | selectCallback,
|  | char * | actionString,
|  | char * | initialString,
|  | u8 | maxChars |
| ) |  |  |

Can be called from an item select function to enter string editing mode (e.g. to enter a filename).
See tutorial/027_scs for usage example

s32 SCS_InstallEncHook | ( | s32(*)(s32 incrementer) | encFunct | ) |

Installs encoder handler for overruling If it returns 0, the encoder increment will be handled by the SCS If it returns 1, the SCS will ignore the encoder

Parameters:

  `[in]` | encFunct | the encoder function

Returns:
  < 0 on errors

s32 SCS_InstallRoot | ( | scs_menu_page_t * | _rootTable,
|  | u8 | numItems |
| ) |  |  |

Installs a root table

Parameters:

  `[in]` | rootTable | pointer to table of pages
  `[in]` | numItems | number of items in table

Returns:
  < 0 on errors

s32 SCS_LCD_BufferSet | ( | u16 | x,
|  | u16 | y,
|  | char * | str |
| ) |  |  |

s32 SCS_LCD_Clear | ( | void |  | ) |

s32 SCS_LCD_CursorSet | ( | u16 | column,
|  | u16 | line |
| ) |  |  |

s32 SCS_LCD_DeviceGet | ( | void |  | ) |

returns the LCD device at which the SCS starts to print the screen

s32 SCS_LCD_DeviceSet | ( | u8 | device | ) |

sets the LCD device at which the SCS should start to print the screen

s32 SCS_LCD_Init | ( | u32 | mode | ) |

Display Initialisation

Here is the call graph for this function:

s32 SCS_LCD_InitSpecialChars | ( | scs_lcd_charset_t | charset,
|  | u8 | force |
| ) |  |  |

Here is the call graph for this function:

s32 SCS_LCD_OffsetXGet | ( | void |  | ) |

returns the X offset at which the SCS starts to print the screen

s32 SCS_LCD_OffsetXSet | ( | u8 | x_offset | ) |

sets the X offset at which the SCS should start to print the screen

s32 SCS_LCD_OffsetYGet | ( | void |  | ) |

returns the Y offset at which the SCS starts to print the screen

s32 SCS_LCD_OffsetYSet | ( | u8 | y_offset | ) |

sets the Y offset at which the SCS should start to print the screen

s32 SCS_LCD_PrintChar | ( | char | c | ) |

s32 SCS_LCD_PrintFormattedString | ( | char * | format,
|  |  | ... |
| ) |  |  |

Here is the call graph for this function:

s32 SCS_LCD_PrintSpaces | ( | int | num | ) |

Here is the call graph for this function:

s32 SCS_LCD_PrintString | ( | char * | str | ) |

Here is the call graph for this function:

s32 SCS_LCD_PrintStringCentered | ( | char * | str,
|  | u32 | width |
| ) |  |  |

Here is the call graph for this function:

s32 SCS_LCD_PrintStringPadded | ( | char * | str,
|  | u32 | width |
| ) |  |  |

Here is the call graph for this function:

s32 SCS_LCD_SpecialCharsReInit | ( | void |  | ) |

Here is the call graph for this function:

s32 SCS_LCD_Update | ( | u8 | force | ) |

Here is the call graph for this function:

scs_menu_item_t* SCS_MenuPageGet | ( | void |  | ) |

Returns the current page pointer (not menu item as the scs_menu_item_t type could imply) if menu state is SCS_MENU_STATE_INSIDE_PAGE or SCS_MENU_STATE_EDIT_ITEM, otherwise returns NULL
Can be used in display/button/encoder hook to overrule something if a certain page is displayed
See apps/controllers/midio128_v3/src/scs_config.c for usage example

scs_menu_state_t SCS_MenuStateGet | ( | void |  | ) |

Returns the current display state

s32 SCS_Msg | ( | scs_msg_type_t | msgType,
|  | u16 | delay,
|  | char * | line1,
|  | char * | line2 |
| ) |  |  |

Print temporary user messages (e.g. warnings, errors) expects mS delay and two lines, each up to 18 characters

Examples:

         // try *one* of these lines (only last message will be displayed for given delay)
         SCS_Msg(SCS_MSG_L, 1000, "Left", "Side");
     // or:
         SCS_Msg(SCS_MSG_R, 1000, "Right", "Side");
     // or:
         SCS_InstallDelayedActionCallback(clearPatch, 2000, selectedPatch);
         SCS_Msg(SEQ_UI_MSG_DELAYED_ACTION_L, 2001, "", "to clear patch");

Here is the call graph for this function:

s32 SCS_MsgStop | ( | void |  | ) |

Stops temporary message if no SD card warning

s32 SCS_NumMenuItemsGet | ( | void |  | ) |

returns the number of menu items which are visible on screen

s32 SCS_NumMenuItemsSet | ( | u8 | num_items | ) |

Sets the number of menu items which are visible on screen

Parameters:

  `[in]` | num_items | must be between 1..SCS_NUM_MENU_ITEMS

Returns:
  != 0 if invalid value

s32 SCS_PinGet | ( | u8 | pin | ) |

Returns the current pin state of a given pin

Parameters:

  `[in]` | pin | the pin number (SCS_PIN_ENC_MENU_A .. SCS_PIN_SOFT5)

Returns:
  < 0 on errors, 0 if pin pressed, > 0 if pin depressed

s32 SCS_PinSet | ( | u8 | pin,
|  | u8 | depressed |
| ) |  |  |

Call this function if the SCS is controlled from DIN pins

Parameters:

  `[in]` | pin | the pin number (SCS_PIN_ENC_MENU_A .. SCS_PIN_SOFT5)
  `[in]` | depressed | the pin value (0 if pressed, != 0 if depressed)

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 SCS_ShowSelectedItem | ( | u8 | itemNum | ) |

Can be used for flashing the item in display if the standard routine is not used, but overlayed by via a displayHook

Returns:
  1 if itemNum matches with the selected item, and item should be displayed, otherwise 0

s32 SCS_Tick | ( | void |  | ) |

This handler should be called from a FreeRTOS task each millisecond with low priority

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 SCS_UnInstallDelayedActionCallback | ( | void(*)(u32 parameter) | callback | ) |

Disables delayed action of the given callback function
Only relevant if the callback should be disabled before the delay given via SCS_InstallDelayedActionCallback passed.
After this delay has passed, the callback will be dropped automatically.

Here is the call graph for this function: