Changes for page Keypad Configuration

Last modified by Alexander Mott on 2024/05/31 19:33

From 40.5 to 40.6

From version 40.6

edited by Alexander Mott
on 2023/02/08 20:19

Change comment: (Autosaved)

To version 46.1

edited by Alexander Mott
on 2024/05/31 19:33

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -2,9 +2,7 @@
  {{toc/}}
  {{/box}}
--(% class="row" %)
--(((
--The showrunner™ program includes several pre-built keypad types suitable for a wide variety of applications. In addition to standard keypad types, showrunner™ supports custom "X-Type" keypad configurations. Custom keypads can be configured from the showrunnerHUB™ Web Interface, or they can be manually added to the config and enabled using the XPanel Touchscreen interface. The [[SHOWRUNNER™ Keypad Types page>>SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome]] page lists all the available built-in keypad types for the most common keypad models:
++The ShowRunnerCLC™ program includes several pre-built keypad types suitable for a wide variety of applications. In addition to standard keypad types, showrunner™ supports custom "X-Type" keypad configurations. Custom keypads can be configured from the ShowRunnerHUB™ Web Interface, or they can be manually added to the config and enabled using the XPanel Touchscreen interface. The [[ShowRunner™ Keypad Types >>SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome]]page lists all the available built-in keypad types for the most common keypad models:
  * [[Cameo Keypads>>SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome||anchor="HCameoKeypads"]]
  * [[Horizon Keypads>>SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome||anchor="HHorizonKeypads"]]
@@ -13,48 +13,136 @@
  * [[Zūm Wireless Keypads>>SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome||anchor="HZūmWirelessKeypads"]]
  It is recommended to use built-in keypad types whenever possible, as configuring custom (X-Type) keypads is a more complex and time-consuming process. If custom keypad programming is required, there are several methods of configuring custom actions detailed in subsequent sections.
--)))
--(% class="row" %)
--(((
  = Keypad Configuration Options =
--Keypads in showrunner™ can be configured using either the XPanel UI or the showrunnerHUB™ UI. Both user interfaces allow for enabling/disabling keypads, changing the keypad area assignment, and modifying the keypad type.
++Keypads in ShowRunnerCLC™ can be configured using either the XPanel UI or the ShowRunnerHUB™ UI. Both user interfaces allow for enabling/disabling keypads, changing the keypad area assignment, and modifying the keypad type.
--If a keypad is manually enabled or disabled through the Keypad Configuration menu, it will stay in that enabled or disabled state until something else (e.g. a scheduled event or a global action) occurs that changes its status. For this reason, it is only recommended to enable or disable keypads through the Keypad Configuration menu for testing purposes. During normal operation, keypads should be enabled and disabled using Scheduled Events.
++If a keypad is manually enabled or disabled through the Keypad Configuration menu, it will stay in that enabled or disabled state until something else (e.g. a scheduled event or a global action) occurs that changes its status. For this reason, it is only recommended to enable or disable keypads through the Keypad Configuration menu for testing purposes. During normal operation, keypads should be enabled and disabled using Scheduled Events. To prevent specific keypads from being disabled by scheduled events, check the "Disallow Disable" box.
--Note that while it is possible to use the XPanel UI to change a keypad from a standard keypad type to a custom X-Type keypad, defining custom functions is only possible through the showrunnerHUB™ UI or by editing the configuration manually. X-Type keypads will perform any actions that are defined in the configuration. If no actions are defined for the keypad, then it will not perform any functions as an X-Type keypad. This means that correctly configured X-Type keypads can be changed into standard type keypads and then changed back into X-Type keypads without any loss of the custom functionality, but that standard type keypads cannot be changed into X-Type keypads without also configuring their custom actions using the showrunnerHUB™ UI or manually editing the configuration file.
++Note that while it is possible to use the XPanel UI to change a keypad from a standard keypad type to a custom X-Type keypad, defining custom functions is only possible through the ShowRunnerHUB™ UI or by editing the configuration manually. X-Type keypads will perform any actions that are defined in the configuration. If no actions are defined for the keypad, then it will not perform any functions as an X-Type keypad. This means that correctly configured X-Type keypads can be changed into standard type keypads and then changed back into X-Type keypads without any loss of the custom functionality, but that standard type keypads cannot be changed into X-Type keypads without also configuring their custom actions using the ShowRunnerHUB™ UI or manually editing the configuration file.
  == XPanel ==
--Standard sh
++The XPanel and touchscreen user interfaces can be used to configure standard keypad types. Custom keypad actions cannot be configured using the XPanel UI, and must be either manually added to the config file or configured using the ShowRunnerHUB™ UI.
--== showrunnerHUB™ ==
++To configure keypads using the XPanel or touchscreen:
--The showrunnerHUB™ Web Interface can be used to configure both To configure keypads using the showrunnerHUB™ UI:
++* Enter the technician PIN code if required
++* Tap the "Settings" gear icon in the top right of the screen
++* Tap the "Keypad Configuration" button
++* Select the desired keypad from the list of keypads on the left
++* Edit the keypad attributes as desired
++** The Keypad Label can be edited from this menu
++*** The Contractor Label still exists, but can only be edited through the ShowRunnerHUB™ UI or by manually editing the configuration file
++** The Area Assignment determines what areas and loads are controlled by standard type keypads
++** The Area Assignment also determines whether a scheduled event will change the keypad's behavior
++*** The Ignore Disable checkbox allows excluding individual keypads from being disabled by scheduled events. Useful in situations where there are multiple keypads assigned to the same area, but only some of them need to be disabled during specific times of day
++*** The Disable Off checkbox allows for using standard keypads with "Area Off" functionality (e.g. F-Type keypads) in front-of-house or otherwise public areas without fear of the lights being turned off by accident
++** The Keypad Type determines the keypad functionality
++*** See the [[ShowRunner™ Keypad Types >>SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome]]page for a list of standard keypad types
++*** Some Keypad Types support direct loads (i.e. performing load-level actions rather than area-level actions), but they can only be edited through the ShowRunnerHUB™ UI or by manually editing the configuration file
++*** Setting a keypad to "X-Type" allows the keypad to perform any previously configured custom actions, but these actions can only be configured through the ShowRunnerHUB™ UI or by manually editing the configuration file
++== ShowRunnerHUB™ ==
++
++The ShowRunnerHUB™ Web Interface can be used to configure both standard keypads as well as custom X-Type keypads. If an X-Type keypad was configured manually by editing the configuration file, then it might be missing some information that is required for the showrunnerHUB™ UI to be able to view and edit the keypad correctly. In these cases it is recommended to either continue editing the keypad manually using the configuration, or re-do the keypad customization with the showrunnerHUB™ UI in order to ensure that all the required information is generated.
++
++Note that the ShowRunnerHUB™ UI performance on 3-Series processors can be slow, and it can require quite a bit of time for all the keypads, areas, loads, etc. to populate. If configuring a large number of keypads using the ShowRunnerHUB™ UI, it is recommended to load the configuration to a 4-Series processor running the same version of ShowRunnerCLC™ to make changes and then save/load that configuration to the 3-Series processor whenever possible.
++
++To configure keypads using the ShowRunnerHUB™ UI:
++
  * Log in to the web interface
  * Click the "Setup" gear icon from the top right of the screen to navigate to the setup menu
  * Click "Keypad Configuration" from the list on the left to bring up a list of keypads defined in the configuration
  * Select the desired keypad from the list of keypads
--* Edit the keypad name, contractor label, area assignment, and type as desired.
--** Detailed instructions on using the keypad configuration menu in the showrunnerHUB™ UI are available [[here>>attach:SHOWRUNNER™ Setup Guide.showrunnerHUB™.Keypad Configuration.WebHome@CI Keypad Editor UI Guide.pdf]]
++* Edit the keypad attributes as desired
++** The Keypad Name/Keypad Label is what is displayed in the XPanel and touchscreen UI, while the Contractor Label is only visible in the configuration file or in this configuration menu
++** The Area Assignment determines what areas and loads are controlled by standard type keypads
++** The Area Assignment also determines whether a scheduled event will change the keypad's behavior
++*** The Ignore Disable checkbox allows excluding individual keypads from being disabled by scheduled events. Useful in situations where there are multiple keypads assigned to the same area, but only some of them need to be disabled during specific times of day
++*** The Disable Off checkbox allows for using standard keypads with "Area Off" functionality (e.g. F-Type keypads) in front-of-house or otherwise public areas without fear of the lights being turned off by accident
++** The Keypad Type determines the keypad functionality
++*** See the [[ShowRunnerCLC™ Keypad Types >>SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome]]page for a list of standard keypad types
++*** Some Keypad Types support direct loads (i.e. performing load-level actions rather than area-level actions). Note that direct loads require saving the configuration and performing a progreset before they take effect.
++*** Setting the keypad to "X-Type" brings up additional options for keypad customization and assigning custom keypad templates
++*** Keypad logic can be verified by toggling on the "Simulate" function, selecting a type of interaction (Press, Tap, Double-Tap, or Hold), and then clicking on the buttons you wish to simulate
++** Detailed instructions on using the Keypad Configuration menu in the ShowRunnerHUB™ UI are available [[here>>attach:SHOWRUNNER™ Setup Guide.showrunnerHUB™.Keypad Configuration.WebHome@CI Keypad Editor UI Guide.pdf]]
--Custom keypads can be configured from the showrunnerHUB™ Web Interface, or they can be manually added to the config and enabled using the XPanel Touchscreen interface.
++The next section contains more detailed information regarding specific custom keypad functions and X-Type templates.
--The next section contains a comprehensive list of actions which can be used to manually configure X-Type keypads from the SrConfig.json file. The table was generated using showrunner™ v3.019, but can be viewed for any version of showrunner™ by connecting to a processor running the desired version of showrunner™ and running the command: ##sr sh ac##
++= Custom (X-Type) Keypad Configuration =
--Note that actions with "None" listed under "Triggers" are read-only and are only able to be used for keypad or keyswitch feedback.
++The ShowRunnerCLC™ X-Type keypad is a customizable keypad type available for Cameo, Horizon, GLPPA-KP, and Zūm Wired keypads. See[[ this document>>attach:SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome@showrunnerKeypadStyles.pdf]] for a list of possible keypad layouts for all keypad types. It is recommended to customize keypads using the ShowRunnerHUB™ UI whenever possible, as keypads which have been manually customized in the configuration will be missing certain attributes that are required to allow them to be subsequently editable from the ShowRunnerHUB™ UI.
--= Custom (X-Type) Keypad Configuration =
++== X-Type Button Models ==
--The showrunner™ X-Type keypad is a customizable keypad type available for Cameo, Horizon, GLPPA-KP, and Zūm Wired keypads. See[[ this document>>attach:SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome@showrunnerKeypadStyles.pdf]] for a list of possible keypad layouts for all keypad types. It is recommended to customize keypads using the showrunnerHUB™ UI whenever possible, as keypads which have been manually customized in the configuration will be missing certain attributes that are required to allow them to be subsequently editable from the showrunnerHUB™ UI.
++(% class="box warningmessage" %)
++(((
++When configuring a button to perform Raise, Lower, or RaiseLower actions, you must also configure a Stop action to trigger on Release. This requires either a Press/Hold/Release or Tap/Hold/Release Button Model to be selected: if no action is to be triggered by a simple button press, then either Button Model is suitable. If an action is to be triggered on button press, you must select either a Press/Hold/Release or Tap/Hold/Release depending on whether you want the press action to trigger every time the button is pressed (Press) or only trigger when the button is not subsequently held (Tap)
++)))
--==   ==
++When configuring X-Type keypads through the ShowRunnerHUB™ UI, there are several "Button Models" available to describe what types of button interactions will have actions assigned to them. There are four main types of button interaction (Press, Tap, Double-Tap, and Hold) plus Release, and Button Models are available for a number of different interaction combinations. The table below describes each of the button interaction types and when they are triggered:
++(% class="table-condensed" %)
++|(% style="width:246px" %)**Interaction Type**|(% style="width:1244px" %)**Behavior**
++|(% style="width:246px" %)Press|(% style="width:1244px" %)Always executes immediately upon button press detected
++|(% style="width:246px" %)Tap|(% style="width:1244px" %)Delayed execution after a button press is detected unless a Double-Tap or Hold is detected
++|(% style="width:246px" %)Double-Tap|(% style="width:1244px" %)Delayed execution after a second button press is detected within the ##"DoubleTapTime"## specified in the configuration
++|(% style="width:246px" %)Hold|(% style="width:1244px" %)Delayed execution after a button is pressed and held longer than the ##"HoldTime"## specified in the configuration
++|(% style="width:246px" %)Release|(% style="width:1244px" %)Always executed
++|(% colspan="2" style="width:219px" %)**Note:** ##"HoldTime"## and ##"DoubleTapTime"## properties are set per-keypad in the ShowRunnerCLC™ configuration and dictate the delay between button press detection and action execution. Valid range is 0.1 to 1.0s, default is 0.5s
++
  == X-Type Templates ==
--Below is a table of possible actions for X-Type keypads (taken from the [[SHOWRUNNER™ Keypad Types page>>SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome]].
++X-Type templates are a powerful tool available in ShowRunnerCLC™ that enable a technician to streamline configuring custom keypads on larger jobs. X-Type templates are similar to custom "standard" type keypads: once a custom template is created, it can be assigned to many different keypads and used to perform the same set of actions on different areas by simply re-mapping the template for each keypad.
++Setting up custom keypads can be time consuming, as every action for every button for every keypad must be individually configured. If the types of functions (e.g. recall scene, toggle load 1, toggle load 2) are repeated across multiple keypads and the only thing that changes between them is the specific loads or areas being affected, then it is worthwhile to set up a template. Templates essentially allow a technician to configure a custom keypad one time, and then easily repeat it for multiple different keypads. When a keypad template is assigned to a keypad, all that is required is that the template be remapped so that it knows which areas, loads, etc. it is targeting for each keypad.
++
++To create an X-Type template using the ShowRunnerHUB™ UI:
++
++* Log in to the web interface
++* Click the "Setup" gear icon from the top right of the screen to navigate to the setup menu
++* Click "Keypad Configuration" from the list on the left to bring up a list of keypads defined in the configuration
++* Select the first keypad that will be assigned a template
++* Change the Keypad Type to "X-Type"
++* Click the gear icon next to the "Keypad Template" field
++* Click "ADD" underneath the "Keypad Templates" heading and name the template
++* Once the template has been created, customize it as necessary
++** Use the Model field to create custom templates for C2N-CBD, HZ-KPCN, GLPPA-KP, or other types of keypads
++** Use the Style Picker button to select the desired button layout
++** Once the Model and Style are selected, click the Edit Actions button to define the template's actions
++*** The Template Actions menu uses the same workflow as the X-Type Actions configuration menu
++**** Select a button
++**** Give the button a descriptive label
++**** Choose the required [[Button Model>>doc:SHOWRUNNER™ Setup Guide.SHOWRUNNER™ Installation Guide.Program Configuration.Keypad Configuration.WebHome||anchor="HX-TypeButtonModels"]]
++**** Add actions for each interaction type on the button (Press, Tap, Double-Tap, Hold, or Release)
++**** When adding an action to a button, you will be prompted to assign a number to the object.
++***** This number is known as the Host Global ID
++***** The Host Global ID is shown in the "[object] #" field. The name for this field updates depending on the type of object being targeted by the action (e.g. it will become "Load #" if the action is targeting loads)
++***** Do not repeat Host Global IDs within a template unless you intend for multiple buttons to target the same object
++****** E.g., if one button acts on an Area and another button acts on a Load, do not use "Area #: 1" and "Load #: 1" - instead, use "Area #:1" and "Load #: 2"
++*** Once all the actions for all the buttons have been configured, exit back to the main Keypad Configuration menu
++* To assign the template to a keypad, click the Keypad Template field and select the desired template
++* Once a template is selected, click the map icon that appears next to the gear icon to open the Template Global Map menu
++* Use the Template Global Map menu to assign specific objects to each custom keypad
++** The Type column indicates what type of object the template is expecting
++*** By default, Host Global IDs are mapped to whatever object has a matching Global ID. These objects may or may note be the correct type of object for the template (e.g., a Host Global ID of 1 usually corresponds to a LoadController object)
++** Use the Object column to select the specific object to be mapped for this keypad
++* Once the first keypad has been assigned the template and remapped:
++** Select the next keypad to be edited
++** Change the Keypad Type to "X-Type"
++** Select the custom template
++** Remap the Host Global IDs
++** Repeat for all keypads using the custom template
++* Miscellaneous tips for configuring keypad templates:
++** Templates should be configured with the maximum number of loads/areas/etc. that any keypad will require, as excess generic objects can be skipped when mapping the template to specific keypads
++*** E.g., if some keypads will have a button toggle 5 loads while others will have the same button toggle 7 loads, then the template should be defined to have 7 loads. Keypads which make use of all 7 loads will have all loads mapped, while the keypads that only require 5 loads should be mapped with "[Skip this Entry]" for the two extra loads
++** In certain situations, keypad templates can be used even if the actual keypad layout does not match the template
++*** For example, a custom 4-button GLPPA-KP template can be used on a 2-button rocker GLPPA-KP as long as buttons 1 and 4 in the template do what is required. The extra functions assigned to buttons 2 and 3 do not matter because they can be skipped when mapping the template and the physical buttons cannot be pressed due to the rocker button cap
++
++The table below contains a comprehensive list of possible actions for X-Type keypads (taken from the [[ShowRunnerCLC™ Keypad Types page>>SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome]]). The table was generated using ShowRunnerCLC™ version 3.019, but can be viewed for any version of ShowRunnerCLC™ by connecting to a processor running the desired version of ShowRunnerCLC™ and executing the command: ##sr sh ac##
++
++Note that actions with "None" listed under "Triggers" are read-only and are only able to be used for keypad or keyswitch feedback, not for performing actions.
++
  {{display excludeFirstHeading="false" reference="SHOWRUNNER™ User Guide & Wiki.SHOWRUNNER™ Keypad Types.WebHome" section="HX-TypeActionsTable"/}}
--)))