edoc.site g2s103

G2S ™ MESSAGE PROTOCOL V1.0.3 Game To System Gaming Standards Association G2S Technical Committee Standard v1.0 Adopted: 2006/12/15 Released: 2007/04/12 Document ID: gsa-p0075.003.01 GAMINGSTANDARDS.COM G2S™ Message Protocol v1.0.3, Document ID gsa-p0075.003.01 Released 2007/04/12, by Gaming Standards Association (GSA). Patents and Intellectual Property Note: The user's attention is called to the possibility that compliance with this [standard/specification] may require use of an invention covered by patent rights. By publication of this [standard/ specification], GSA takes no position with respect to the validity of any such patent rights or their impact on this [standard/specification]. Similarly, GSA takes no position with respect to the terms or conditions under which such rights may be made available from the holder of any such rights. Contact GSA for further information. Trademarks and Copyright Copyright © 2006 - 2007 Gaming Standards Association (GSA). All rights reserved. All trademarks used within this document are the property of their respective owners. Gaming Standards Association and the puzzle-piece GSA logo are registered trademarks and/or trademarks of the Gaming Standards Association. GSA Contact Information GSA – Gaming Standards Association 48377 Fremont Blvd., Suite 117 Fremont, CA 94538 Phone: +1(510) 492-4060 Fax: +1(510) 492.4001 E-mail: sec@gamingstandards.com WWW: http://www.gamingstandards.com G2S™ Message Protocol v1.0.3 Table of Contents Table of Contents I About This Document .................................................................................... xxxix I.I Goals and Benefits of the GSA G2S Message Protocol ...................................................... xxxix I.II G2S Compliance ................................................................................................................. xxxix I.II.I XML 1.0 and XSD 1.0................................................................................................. xxxix I.II.II Required and Optional Functionality ......................................................................... xxxix I.III Term Definitions .......................................................................................................................xl I.IV Document Conventions and Organization ............................................................................. xlii I.IV.I Indicating Requirements, Recommendations, and Options .......................................... xlii I.IV.II Abbreviations and Labels Used in Tables.................................................................... xlii I.IV.III Graphical Conventions ................................................................................................ xlii I.IV.IV Document Organization ............................................................................................. xliv I.V Acknowledgements................................................................................................................ xliv 1 g2sMessage ........................................................................................................... 1 1.1 Introduction .............................................................................................................................. 1 1.2 XML Version 1.0 and XML Schema (XSD) Version 1.0 ........................................................... 1 1.3 Transport Requirements .......................................................................................................... 2 1.4 Point-to-Point Message Handling............................................................................................. 3 1.5 Application-Level Message Handling ....................................................................................... 3 1.6 Classes & Devices ................................................................................................................... 5 1.6.1 Device Structure ............................................................................................................. 5 1.7 Multiple Hosts........................................................................................................................... 6 1.7.1 1.7.2 1.7.3 1.7.4 Owners, Foreign Owners, and Guests ........................................................................... 6 Registered hostIds.......................................................................................................... 6 Devices Foreign Hosts Cannot Own .............................................................................. 6 Functional Requirements Dependent on Owner ............................................................ 7 1.8 Device Identifiers...................................................................................................................... 7 1.8.1 Adding Devices............................................................................................................... 7 1.9 Device Subscriptions................................................................................................................ 8 1.9.1 1.9.2 1.9.3 1.9.4 1.9.5 Device Owner ................................................................................................................. 8 Device Guests ................................................................................................................ 8 Registered Hosts ............................................................................................................ 9 Active & Inactive Devices ............................................................................................... 9 Changes To Devices ...................................................................................................... 9 1.10 Host & EGM Identifiers......................................................................................................... 10 1.11 Unique Identifiers ................................................................................................................. 10 1.12 Date/Time Format ................................................................................................................ 11 1.13 Meters .................................................................................................................................. 11 1.14 Transaction Logs.................................................................................................................. 12 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page i G2S™ Message Protocol v1.0.3 1.14.1 1.14.2 1.14.3 1.14.4 1.14.5 1.14.6 Table of Contents transactionId ............................................................................................................... 12 logSequence............................................................................................................... 12 transactionId vs. logSequence ................................................................................... 12 Recovery from Outage and Duplicate Detection ........................................................ 13 Commands to Query Log Contents ............................................................................ 13 Log Commands and deviceId Values ......................................................................... 13 1.15 Event Handling..................................................................................................................... 13 1.16 Event Subscriptions ............................................................................................................. 14 1.17 g2sMessage Element........................................................................................................... 15 1.18 Point-to-Point Format ........................................................................................................... 16 1.18.1 g2sBody Element ....................................................................................................... 17 1.18.2 g2sAck Element.......................................................................................................... 18 1.18.3 Point-to-Point Class-Level Elements .......................................................................... 20 1.18.4 Command Retry ......................................................................................................... 24 1.18.5 Processing Order........................................................................................................ 24 1.18.6 Class-Level Command Examples: Standard Notification ........................................... 24 1.18.7 Class-Level Command Examples: Standard Request ............................................... 25 1.18.8 Class-Level Command Examples: Standard Response............................................. 25 1.18.9 Class-Level Command Example: Response Reporting Error .................................... 25 1.18.10 Standard Error Handling........................................................................................... 25 1.18.11 Command Queues ................................................................................................... 34 1.18.12 Communications States............................................................................................ 34 1.19 Multicast Format................................................................................................................... 36 1.19.1 g2sMulticast Element ................................................................................................. 37 1.19.2 Multicast Class-Level Attributes ................................................................................. 37 1.19.3 Multicast Example ...................................................................................................... 38 1.20 EGM Restart, Recovery & Activation ................................................................................... 39 1.20.1 1.20.2 1.20.3 1.20.4 1.20.5 1.20.6 EGM Restart............................................................................................................... 39 EGM Recovery ........................................................................................................... 39 EGM Activation........................................................................................................... 40 EGM Deactivation....................................................................................................... 41 Affects Of Disabling Devices ...................................................................................... 41 Restart Sequence ....................................................................................................... 42 1.21 Persistent Memory ............................................................................................................... 44 1.22 Namespaces and Protocol Extensions ................................................................................ 45 1.22.1 Namespaces............................................................................................................... 45 1.22.2 Protocol Extensions .................................................................................................... 45 1.23 Data Types........................................................................................................................... 49 1.24 Error Codes.......................................................................................................................... 50 1.25 Event Codes......................................................................................................................... 51 1.25.1 G2S_APE001 At Least One Syntax/Semantic Command Error ................................ 51 1.25.2 G2S_APE002 Invalid sessionId Received In Response ........................................... 51 Page ii gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 2 communications Class ....................................................................................... 53 2.1 Introduction ............................................................................................................................ 53 2.2 Sending, Resending and commandIds .................................................................................. 53 2.3 Point-to-Point Communications.............................................................................................. 54 2.3.1 2.3.2 2.3.3 2.3.4 2.3.5 2.3.6 2.3.7 2.3.8 2.3.9 Association Attributes ................................................................................................... 56 closed State.................................................................................................................. 56 opening State ............................................................................................................... 57 sync State..................................................................................................................... 58 onLine State ................................................................................................................. 59 overflow State............................................................................................................... 60 closing State ................................................................................................................. 60 Transport Events .......................................................................................................... 61 Lost Communications ................................................................................................... 61 2.4 Multicast Service .................................................................................................................... 62 2.4.1 2.4.2 2.4.3 2.4.4 2.4.5 2.4.6 Multicast Identifiers ....................................................................................................... 63 Joining a Multicast Group ............................................................................................. 64 Receiving a Multicast Message .................................................................................... 64 Leaving a Multicast Group ............................................................................................ 65 Getting a List of Multicast Groups, getMcastList .......................................................... 65 Multicast Message Security .......................................................................................... 66 2.5 Request-Response Pairs ....................................................................................................... 67 2.6 setCommsState Command .................................................................................................... 68 2.7 getCommsStatus Command .................................................................................................. 68 2.8 commsStatus Command........................................................................................................ 69 2.9 getCommsProfile Command .................................................................................................. 70 2.10 commsProfile Command...................................................................................................... 70 2.11 commsOnLine Command .................................................................................................... 71 2.12 commsOnLineAck Command .............................................................................................. 72 2.13 commsDisabled Command .................................................................................................. 73 2.14 commsDisabledAck Command ............................................................................................ 73 2.15 commsClosing Command .................................................................................................... 73 2.16 commsClosingAck Command .............................................................................................. 74 2.17 getDescriptor Command ...................................................................................................... 74 2.18 descriptorList Command ...................................................................................................... 75 2.19 joinMcast Command ............................................................................................................ 77 2.20 joinMcastAck Command ...................................................................................................... 77 2.21 leaveMcast Command ......................................................................................................... 78 2.22 leaveMcastAck Command ................................................................................................... 78 2.23 mcastKeyUpdate Command ................................................................................................ 79 2.24 mcastKeyAck Command...................................................................................................... 79 2.25 getMcastKeyUpdate Command ........................................................................................... 79 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page iii G2S™ Message Protocol v1.0.3 Table of Contents 2.26 getMcastList Command ....................................................................................................... 80 2.27 mcastList Command ............................................................................................................ 80 2.28 setKeepAlive Command....................................................................................................... 81 2.29 setKeepAliveAck Command................................................................................................. 81 2.30 keepAlive Command ............................................................................................................ 82 2.31 keepAliveAck Command ...................................................................................................... 82 2.32 Data Types........................................................................................................................... 83 2.32.1 Reserved transportStates Enumerations.................................................................... 83 2.32.2 Reserved equipmentTypes Enumerations ................................................................. 83 2.33 Error Codes.......................................................................................................................... 84 2.34 Event Codes......................................................................................................................... 85 2.34.1 evaluate(state)............................................................................................................ 86 2.34.2 G2S_CME001 Comms Disabled by EGM ................................................................. 86 2.34.3 G2S_CME002 Comms Enabled by EGM .................................................................. 86 2.34.4 G2S_CME003 Comms Disabled by Host .................................................................. 87 2.34.5 G2S_CME004 Comms Enabled by Host ................................................................... 87 2.34.6 G2S_CME005 Comms Configuration Change by Host ............................................. 87 2.34.7 G2S_CME006 Comms Configuration Change by EGM ............................................ 88 2.34.8 G2S_CME099 Comms All Faults Cleared ................................................................. 88 2.34.9 G2S_CME100 Comms Established .......................................................................... 88 2.34.10 G2S_CME101 Comms Not Established .................................................................. 89 2.34.11 G2S_CME102 Comms Outbound Overflow ............................................................ 89 2.34.12 G2S_CME103 Comms Outbound Overflow Cleared .............................................. 90 2.34.13 G2S_CME104 Comms Inbound Overflow ............................................................... 90 2.34.14 G2S_CME105 Comms Inbound Overflow Cleared ................................................. 90 2.34.15 G2S_CME110 Join Multicast Group ........................................................................ 91 2.34.16 G2S_CME111 Leave Multicast Group .................................................................... 91 2.34.17 G2S_CME112 Multicast Message Error .................................................................. 91 2.34.18 G2S_CME113 Security Parameters Updated ......................................................... 92 2.34.19 G2S_CME120 Comms Host Unreachable .............................................................. 92 2.34.20 G2S_CME121 Comms Transport Up ...................................................................... 92 2.34.21 G2S_CME122 Comms Transport Down ................................................................. 92 2.35 Examples ............................................................................................................................. 93 2.35.1 Communication Status Command Sequence............................................................. 93 2.35.2 keepAlive Command Sequence ................................................................................. 94 2.35.3 Descriptor Command Sequence ................................................................................ 95 3 cabinet Class ....................................................................................................... 97 3.1 Introduction ............................................................................................................................ 97 3.2 Currencies, Locales and Floor Information ............................................................................ 97 3.3 Disable, Lockout and Cabinet State....................................................................................... 98 3.4 Cabinet Doors ........................................................................................................................ 99 3.5 Meters .................................................................................................................................... 99 3.6 Request-Response Pairs ..................................................................................................... 100 3.7 setCabinetState Command .................................................................................................. 101 3.8 getCabinetStatus Command ................................................................................................ 102 Page iv gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 3.9 cabinetStatus Command...................................................................................................... 102 3.10 getCabinetProfile Command .............................................................................................. 104 3.11 cabinetProfile Command.................................................................................................... 104 3.12 setCabinetLockOut Command ........................................................................................... 106 3.13 setDateTime Command ..................................................................................................... 107 3.14 getDateTime Command ..................................................................................................... 107 3.15 cabinetDateTime Command .............................................................................................. 107 3.16 resetProcessor Command ................................................................................................. 108 3.17 resetStarted Command ...................................................................................................... 109 3.18 Data Types......................................................................................................................... 110 3.18.1 Reserved cabinetStyles Data Type Enumerations ................................................... 111 3.18.2 egmStates Data Type Enumerations........................................................................ 111 3.18.3 acceptNonCashAmts Data Type Enumerations ....................................................... 111 3.19 Error Codes........................................................................................................................ 112 3.20 Event Codes....................................................................................................................... 113 3.20.1 evaluate(state).......................................................................................................... 116 3.20.2 G2S_CBE001 EGM Disabled Cabinet .................................................................... 116 3.20.3 G2S_CBE002 EGM Enabled Cabinet ..................................................................... 117 3.20.4 G2S_CBE003 Host Disabled Cabinet ..................................................................... 117 3.20.5 G2S_CBE004 Host Enabled Cabinet ...................................................................... 118 3.20.6 G2S_CBE005 Host Changed Cabinet Config ......................................................... 118 3.20.7 G2S_CBE006 Operator Changed Cabinet Config .................................................. 118 3.21 Events: Resulting from setCabinetLockOut ...................................................................... 119 3.21.1 G2S_CBE009 Host Locked Cabinet ........................................................................ 119 3.21.2 G2S_CBE010 Host Unlocked Cabinet .................................................................... 119 3.22 Events: Resulting from setCabinetState ............................................................................ 120 3.22.1 G2S_CBE101 Host Disabled Game Play ................................................................ 120 3.22.2 G2S_CBE102 Host Enabled Game Play ................................................................. 120 3.22.3 G2S_CBE103 Host Disabled Money In ................................................................... 121 3.22.4 G2S_CBE104 Host Enabled Money In .................................................................... 121 3.22.5 G2S_CBE105 Host Disabled Money Out ................................................................ 122 3.22.6 G2S_CBE106 Host Enabled Money Out ................................................................. 122 3.23 Events: Resulting from cabState Changes ........................................................................ 123 3.23.1 G2S_CBE201 Comms Issue EGM Disabled ........................................................... 123 3.23.2 G2S_CBE202 EGM Disabled - Operator Menu ...................................................... 123 3.23.3 G2S_CBE203 Device Failure Disabled EGM .......................................................... 124 3.23.4 G2S_CBE204 Host Command Disabled EGM ........................................................ 124 3.23.5 G2S_CBE205 EGM Enabled and Playable ............................................................. 125 3.23.6 G2S_CBE206 Operator Menu Activated ................................................................. 125 3.23.7 G2S_CBE207 Demo Mode Activated ...................................................................... 126 3.23.8 G2S_CBE208 Meters/Audit Mode Initiated ............................................................. 126 3.23.9 G2S_CBE209 EGM Locked - Operator Menu ......................................................... 127 3.23.10 G2S_CBE210 Device Action Locked EGM ........................................................... 127 3.23.11 G2S_CBE211 Host Action Locked EGM ............................................................... 128 3.24 Events: Resulting from cabinetStatus Changes................................................................. 129 3.24.1 G2S_CBE301 Service Lamp On ............................................................................. 129 3.24.2 G2S_CBE302 Service Lamp Off ............................................................................. 129 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page v G2S™ Message Protocol v1.0.3 Table of Contents 3.24.3 G2S_CBE303 Logic Door Open .............................................................................. 130 3.24.4 G2S_CBE304 Logic Door Closed ........................................................................... 130 3.24.5 G2S_CBE305 Auxiliary Door Open ......................................................................... 130 3.24.6 G2S_CBE306 Auxiliary Door Closed ...................................................................... 131 3.24.7 G2S_CBE307 Cabinet Door Open .......................................................................... 131 3.24.8 G2S_CBE308 Cabinet Door Closed ........................................................................ 131 3.24.9 G2S_CBE309 General Cabinet Tilt ......................................................................... 132 3.24.10 G2S_CBE310 Video Display Error ........................................................................ 132 3.24.11 G2S_CBE311 NVM Failure ................................................................................... 132 3.24.12 G2S_CBE312 General Memory Failure ................................................................ 133 3.24.13 G2S_CBE313 Cabinet Tilt Cleared ....................................................................... 133 3.24.14 G2S_CBE314 Game Combo Activated ................................................................. 133 3.24.15 G2S_CBE326 Hard Meters Disconnected ............................................................ 134 3.24.16 G2S_CBE327 Hard Meters Reconnected ............................................................. 134 3.25 Events: Resulting from setDateTime.................................................................................. 135 3.25.1 G2S_CBE315 Date/Time Changed ......................................................................... 135 3.26 Events: Resulting from cabinetReset ................................................................................. 136 3.26.1 G2S_CBE401 Cabinet Reset Started ...................................................................... 136 3.26.2 G2S_CBE402 Remote Cabinet Reset ..................................................................... 136 3.27 Events: Not Related to Commands.................................................................................... 137 3.27.1 G2S_CBE316 Cash-Out Button Pressed ................................................................ 137 3.27.2 G2S_CBE317 Power Off - Logic Door Open ........................................................... 137 3.27.3 G2S_CBE318 Power Off - Auxiliary Door Open ...................................................... 137 3.27.4 G2S_CBE319 Power Off - Cabinet Door Open ....................................................... 138 3.27.5 G2S_CBE320 Operator Reset Cabinet ................................................................... 138 3.27.6 G2S_CBE321 Life-To-Date Meters Reset ............................................................... 138 3.27.7 G2S_CBE322 NVM Cleared ................................................................................... 139 3.27.8 G2S_CBE323 Backup Battery Low ......................................................................... 139 3.27.9 G2S_CBE324 EGM Power Lost .............................................................................. 139 3.27.10 G2S_CBE325 EGM Power Up .............................................................................. 140 3.28 Examples ........................................................................................................................... 141 3.28.1 3.28.2 3.28.3 3.28.4 Cabinet Status Command Sequences ..................................................................... 141 Cabinet Profile Command Sequence ....................................................................... 144 Date/Time Command Sequences ............................................................................ 145 Processor Reset Command Sequence .................................................................... 146 3.29 Cabinet Device Option Configuration................................................................................. 147 3.29.1 3.29.2 3.29.3 3.29.4 3.29.5 3.29.6 3.29.7 3.29.8 Option Group Definitions .......................................................................................... 147 G2S Protocol Option Definitions............................................................................... 147 G2S Protocol Option Sub-Parameter Definitions ..................................................... 147 G2S Cabinet Profile Option Definitions .................................................................... 148 G2S Cabinet Profile Sub-Parameter Definitions....................................................... 148 Cabinet Limit Option Definitions ............................................................................... 149 Cabinet Limit Sub-Parameter Definitions ................................................................. 149 Example optionItem Elements in optionList.............................................................. 150 4 eventHandler Class ........................................................................................... 155 4.1 Introduction .......................................................................................................................... 155 4.1.1 Determining Events Supported by EGM..................................................................... 155 Page vi gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 4.1.2 4.1.3 4.1.4 4.1.5 4.1.6 4.1.7 4.1.8 Table of Contents Affected Data.............................................................................................................. 155 Subscriptions .............................................................................................................. 155 Persistence: Event and Affected Data ........................................................................ 156 Forced Subscriptions .................................................................................................. 156 Full Event Queue Behavior......................................................................................... 156 Event Processing........................................................................................................ 156 Power Failure and Persisted Subscriptions ................................................................ 158 4.2 Request/Response Pairs ..................................................................................................... 159 4.3 setEventHandlerState Command......................................................................................... 160 4.4 getEventHandlerStatus Command....................................................................................... 160 4.5 eventHandlerStatus Command ............................................................................................ 161 4.6 getEventHandlerProfile Command....................................................................................... 161 4.7 eventHandlerProfile Command ............................................................................................ 162 4.8 getSupportedEvents Command ........................................................................................... 164 4.9 supportedEvents Command................................................................................................. 164 4.10 setEventSub Command ..................................................................................................... 165 4.11 setEventSubAck Command ............................................................................................... 166 4.12 getEventSub Command ..................................................................................................... 166 4.13 eventSubList Command..................................................................................................... 167 4.14 clearEventSub Command .................................................................................................. 169 4.15 clearEventSubAck Command ............................................................................................ 169 4.16 eventReport Command ...................................................................................................... 170 4.16.1 deviceList Element Details ....................................................................................... 171 4.16.2 transactionList Element Details ................................................................................ 172 4.16.3 meterList Element Details......................................................................................... 172 4.17 eventAck Command........................................................................................................... 173 4.18 getEventHandlerLogStatus Command............................................................................... 173 4.19 eventHandlerLogStatus Command .................................................................................... 173 4.20 getEventHandlerLog Command......................................................................................... 174 4.21 eventHandlerLogList Command......................................................................................... 175 4.21.1 affectedDeviceList Element Details .......................................................................... 176 4.21.2 affectedTransactionList Element Details .................................................................. 177 4.21.3 affectedMeterList Element Details............................................................................ 177 4.22 Data Types......................................................................................................................... 178 4.23 Error Codes........................................................................................................................ 178 4.24 Event Codes....................................................................................................................... 179 4.24.1 4.24.2 4.24.3 4.24.4 4.24.5 4.24.6 evaluate(state).......................................................................................................... 179 G2S_EHE001 Event Handler Disabled by EGM ..................................................... 180 G2S_EHE002 Event Handler Enabled by EGM ...................................................... 180 G2S_EHE003 Event Handler Disabled by Host ...................................................... 180 G2S_EHE004 Event Handler Enabled by Host ....................................................... 181 G2S_EHE005 Event Handler Configuration Changed by Host ............................... 181 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page vii G2S™ Message Protocol v1.0.3 Table of Contents 4.24.7 G2S_EHE006 Event Handler Configuration Changed by Operator ........................ 181 4.24.8 G2S_EHE101 Event Subscription Changed ........................................................... 182 4.24.9 G2S_EHE102 Event Handler Queue Overflow ....................................................... 182 4.24.10 G2S_EHE103 Event Handler Queue Overflow Cleared ........................................ 182 4.25 Examples ........................................................................................................................... 183 4.25.1 4.25.2 4.25.3 4.25.4 4.25.5 4.25.6 4.25.7 4.25.8 4.25.9 Supported Event Command Sequence .................................................................... 183 Set Event Subscriptions Command Sequence......................................................... 185 Get Current Event Subscriptions Command Sequence ........................................... 187 Clear Event Subscriptions Command Sequence ..................................................... 188 Set Event Handler State Command Sequence ........................................................ 189 Get Event Handler State Command Sequence ........................................................ 190 Get Event Handler Log Status Command Sequence ............................................... 191 Get Event Handler Log Command Sequence .......................................................... 192 Event Report Command Sequence .......................................................................... 193 4.26 Event Handler Device Option Configuration ...................................................................... 194 4.26.1 4.26.2 4.26.3 4.26.4 4.26.5 4.26.6 Option Group Definitions .......................................................................................... 194 G2S Protocol Option Definitions............................................................................... 194 G2S Protocol Option Sub-Parameter Definitions ..................................................... 194 Forced Subscription Table Option Definitions .......................................................... 195 Forced Subscription Table Sub-Parameter Definitions ............................................ 195 Example optionItem Elements in optionList.............................................................. 196 5 meters Class ...................................................................................................... 199 5.1 Introduction .......................................................................................................................... 199 5.2 Meter Subscriptions ............................................................................................................. 199 5.3 Crafting Periodic Subscriptions ............................................................................................ 200 5.4 Periodic vs. EOD Meter Subscriptions ................................................................................. 200 5.5 Periodic Reports When EGM is Offline ................................................................................ 201 5.6 Meter Classifications ............................................................................................................ 201 5.7 Expected and Omitted Meters.............................................................................................. 202 5.8 Meters and Currencies......................................................................................................... 203 5.9 Credit Meters........................................................................................................................ 204 5.10 Meter Consistency ............................................................................................................. 204 5.11 Meter Consistency in Complex Transactions..................................................................... 205 5.12 Simple and Complex Meters .............................................................................................. 206 5.13 Optional Meter Attributes ................................................................................................... 207 5.14 Extending the Meter Model ................................................................................................ 208 5.15 Metering at the Class and Device Level............................................................................. 208 5.16 Wildcard Conventions ........................................................................................................ 209 5.17 Request-Response Pairs ................................................................................................... 210 5.18 getMeterInfo Command ..................................................................................................... 211 5.18.1 Requesting Wager Category, Denomination, and Currency Meters ........................ 211 Page viii gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 5.18.2 5.18.3 5.18.4 5.18.5 5.18.6 Table of Contents getMeterInfo Elements ............................................................................................. 213 getDeviceMeters Element ........................................................................................ 214 getWagerMeters Element......................................................................................... 215 getGameDenomMeters Element .............................................................................. 215 getCurrencyMeters Element ..................................................................................... 215 5.19 meterInfo Command .......................................................................................................... 216 5.19.1 5.19.2 5.19.3 5.19.4 deviceMeter Element................................................................................................ 217 wagerMeters Element............................................................................................... 218 gameDenomMeters Element .................................................................................... 219 currencyMeters Element........................................................................................... 219 5.20 meterInfoAck Command .................................................................................................... 219 5.21 setMeterSub Command ..................................................................................................... 220 5.22 clearMeterSub Command .................................................................................................. 221 5.23 getMeterSub Command ..................................................................................................... 221 5.24 meterSubList Command .................................................................................................... 222 5.25 Data Types......................................................................................................................... 223 5.25.1 meterSubTypes Reserved Enumerations................................................................. 223 5.25.2 meterInfoTypes Reserved Enumerations ................................................................. 223 5.25.3 meterName Enumerations........................................................................................ 224 5.26 Error Codes........................................................................................................................ 230 5.27 Event Codes....................................................................................................................... 231 5.27.1 G2S_MTE100 Meter Subscription Set .................................................................... 231 5.27.2 G2S_MTE101 Meter Subscription Cleared ............................................................. 231 5.28 Examples ........................................................................................................................... 232 5.28.1 Get Meter Info Command Sequence ........................................................................ 232 5.28.2 Meter Subscription Command Sequences ............................................................... 236 6 gamePlay Class ................................................................................................. 239 6.1 Introduction .......................................................................................................................... 239 6.2 Themes, Paytables, and Denominations ............................................................................. 239 6.2.1 6.2.2 6.2.3 6.2.4 Game Combinations (Game Combos) ....................................................................... 239 Denominations............................................................................................................ 240 Paytables and Wager Categories............................................................................... 240 Game Play Device Collisions ..................................................................................... 241 6.3 Denomination Ranges.......................................................................................................... 242 6.4 playState Transitions............................................................................................................ 243 6.4.1 6.4.2 6.4.3 6.4.4 6.4.5 6.4.6 gameIdle State ........................................................................................................... 244 primaryGameEscrow State......................................................................................... 244 primaryGameStarted State ......................................................................................... 244 progressivePending State .......................................................................................... 244 secondaryGameChoice State..................................................................................... 244 secondaryGameEscrow State .................................................................................... 245 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page ix G2S™ Message Protocol v1.0.3 Table of Contents 6.4.7 secondaryGameStarted State .................................................................................... 245 6.4.8 payGameResults State............................................................................................... 245 6.4.9 gameEnded State....................................................................................................... 245 6.5 Secondary Games ............................................................................................................... 246 6.6 Game Play Device Associations .......................................................................................... 246 6.7 gamePlay Class Associations .............................................................................................. 246 6.8 Request-Response Pairs ..................................................................................................... 247 6.9 setGamePlayState Command.............................................................................................. 248 6.10 getGamePlayStatus Command.......................................................................................... 249 6.11 gamePlayStatus Command ............................................................................................... 249 6.12 getGamePlayProfile Command.......................................................................................... 250 6.13 gamePlayProfile Command ............................................................................................... 250 6.14 getGameDenoms Command ............................................................................................. 252 6.15 setActiveDenoms Command.............................................................................................. 253 6.16 gameDenomList Command ............................................................................................... 254 6.17 getRecallLogStatus Command .......................................................................................... 255 6.18 recallLogStatus Command................................................................................................. 255 6.19 getRecallLog Command..................................................................................................... 256 6.20 recallLogList Command ..................................................................................................... 256 6.21 Data Types......................................................................................................................... 259 6.21.1 playStates Enumerations.......................................................................................... 259 6.21.2 playResults Enumerations ........................................................................................ 260 6.22 Error Codes........................................................................................................................ 261 6.23 Event Codes....................................................................................................................... 262 6.23.1 evaluate(state).......................................................................................................... 263 6.23.2 G2S_GPE001 Device Disabled by EGM ................................................................. 263 6.23.3 G2S_GPE002 Device Enabled by EGM .................................................................. 264 6.23.4 G2S_GPE003 Device Disabled by Host .................................................................. 264 6.23.5 G2S_GPE004 Device Enabled by Host .................................................................. 264 6.23.6 G2S_GPE005 Device Configuration Changed by Host ........................................... 265 6.23.7 G2S_GPE006 Device Configuration Changed at EGM ........................................... 265 6.23.8 G2S_GPE099 Device Tilts Cleared ......................................................................... 265 6.23.9 G2S_GPE101 Primary Game Escrow ..................................................................... 266 6.23.10 G2S_GPE102 Primary Game Failed ..................................................................... 267 6.23.11 G2S_GPE103 Primary Game Started ................................................................... 268 6.23.12 G2S_GPE104 Wager Changed ............................................................................. 270 6.23.13 G2S_GPE105 Primary Game Ended .................................................................... 272 6.23.14 G2S_GPE106 Secondary Game Choice ............................................................... 273 6.23.15 G2S_GPE107 Secondary Game Escrow .............................................................. 274 6.23.16 G2S_GPE108 Secondary Game Failed ................................................................ 275 6.23.17 G2S_GPE109 Secondary Game Started .............................................................. 276 6.23.18 G2S_GPE110 Secondary Game Ended ............................................................... 278 6.23.19 G2S_GPE111 Game Result .................................................................................. 279 6.23.20 G2S_GPE112 Game Ended .................................................................................. 280 6.23.21 G2S_GPE113 Game Idle ...................................................................................... 283 6.23.22 G2S_GPE201 Active Denominations Changed .................................................... 283 Page x gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 6.23.23 G2S_GPE202 Device Tilt ...................................................................................... 284 6.24 Examples ........................................................................................................................... 285 6.24.1 6.24.2 6.24.3 6.24.4 6.24.5 6.24.6 6.24.7 Get Game Play Status Command Sequence ........................................................... 285 Set Game Play State Command Sequence ............................................................. 286 Get Game Play Profile Command Sequence ........................................................... 287 Get Game Denomination Command Sequence ....................................................... 289 Set Active Denominations Command Sequence...................................................... 290 getRecallLogStatus .................................................................................................. 291 getRecallLog............................................................................................................. 291 6.25 Game Play Device Option Configuration ........................................................................... 293 6.25.1 6.25.2 6.25.3 6.25.4 6.25.5 6.25.6 Option Group Definitions .......................................................................................... 293 G2S Protocol Option Definitions............................................................................... 293 G2S Protocol Option Sub-Parameter Definitions ..................................................... 293 Game Play Option Definitions .................................................................................. 294 Game Play Option Sub-Parameter Definitions ......................................................... 294 Example optionItem Elements in optionList.............................................................. 295 7 deviceConfig Class ........................................................................................... 297 8 commConfig Class............................................................................................ 299 8.1 Introduction .......................................................................................................................... 299 8.2 commConfig Overview ......................................................................................................... 299 8.3 commConfig Changes: Contents, Apply Conditions, and Sending Rules............................ 301 8.3.1 8.3.2 8.3.3 8.3.4 Contents ..................................................................................................................... 301 commConfig Change Host Authorization ................................................................... 301 Conditions Under Which Changes Can be Applied .................................................... 301 Rules for Applying Changes That Are Sent from a Host ............................................ 302 8.4 Rules for Changes To Hosts And Device Owners ............................................................... 303 8.5 Default Configuration ........................................................................................................... 303 8.6 Request-Response Pairs ..................................................................................................... 304 8.7 enterCommConfigMode Command ..................................................................................... 305 8.8 getCommConfigModeStatus Command .............................................................................. 305 8.9 commConfigModeStatus Command .................................................................................... 306 8.10 getCommConfigProfile Command ..................................................................................... 306 8.11 commConfigProfile Command ........................................................................................... 307 8.12 getCommHostList Command ............................................................................................. 307 8.13 commHostList Command................................................................................................... 308 8.14 commHostListAck Command............................................................................................. 310 8.15 setCommChange Command.............................................................................................. 310 8.16 cancelCommChange Command ........................................................................................ 314 8.17 authorizeCommChange Command.................................................................................... 314 8.18 commChangeStatus Command ......................................................................................... 315 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xi G2S™ Message Protocol v1.0.3 Table of Contents 8.19 commChangeStatusAck Command ................................................................................... 316 8.20 getCommChangeLogStatus Command ............................................................................. 317 8.21 commChangeLogStatus Command ................................................................................... 317 8.22 getCommChangeLog Command ....................................................................................... 317 8.23 commChangeLogList Command........................................................................................ 318 8.24 Data Types......................................................................................................................... 320 8.24.1 commConfigExceptions Enumerations (Exception Codes) ...................................... 320 8.25 Error Codes........................................................................................................................ 321 8.26 Event Codes....................................................................................................................... 322 8.26.1 evaluate(state).......................................................................................................... 323 8.26.2 G2S_CCE001 commConfig Disabled by EGM ........................................................ 323 8.26.3 G2S_CCE002 commConfig Enabled by EGM ........................................................ 323 8.26.4 G2S_CCE003 commConfig Changed by Host ........................................................ 324 8.26.5 G2S_CCE004 commConfig Changed by Operator ................................................. 324 8.26.6 G2S_CCE101 commConfig Entered Configuration Mode ....................................... 324 8.26.7 G2S_CCE102 commConfig Exited Configuration Mode ......................................... 325 8.26.8 G2S_CCE103 commConfig Configuration Change Pending .................................. 325 8.26.9 G2S_CCE104 commConfig Configuration Authorized by Host ............................... 326 8.26.10 G2S_CCE105 commConfig Configuration Cancelled ........................................... 327 8.26.11 G2S_CCE106 commConfig Configuration Changes Applied ................................ 328 8.26.12 G2S_CCE107 commConfig Configuration Aborted ............................................... 329 8.26.13 G2S_CCE108 commConfig Error .......................................................................... 330 8.26.14 G2S_CCE109 commConfig Configuration Waiting on Authorization .................... 331 8.26.15 G2S_CCE110 commConfig Configuration Change Authorization Timeout ........... 332 8.27 Examples ........................................................................................................................... 333 8.27.1 Host Lists.................................................................................................................. 334 8.27.2 Change commConfig Device .................................................................................... 336 8.28 Communication Configuration Device Option Configuration.............................................. 339 8.28.1 8.28.2 8.28.3 8.28.4 Option Group Definitions .......................................................................................... 339 G2S Protocol Option Definitions............................................................................... 339 G2S Protocol Option Sub-Parameter Definitions ..................................................... 339 Example optionItem Elements in optionList.............................................................. 340 9 optionConfig Class ........................................................................................... 341 9.1 Introduction .......................................................................................................................... 341 9.2 optionConfig Overview ......................................................................................................... 341 9.3 optionConfig Changes: Contents, Apply Conditions, and Sending Rules............................ 343 9.3.1 9.3.2 9.3.3 9.3.4 Contents ..................................................................................................................... 343 optionconfig Change Host Authorization .................................................................... 343 Conditions Under Which Changes Can be Applied .................................................... 343 Rules for Applying Changes That Are Sent ................................................................ 344 9.4 Option Groups and Option Items ......................................................................................... 345 9.4.1 Option Groups ............................................................................................................ 345 9.4.2 Option Items ............................................................................................................... 345 9.5 Default Configuration ........................................................................................................... 346 Page xii gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 9.6 Request-Response Pairs ..................................................................................................... 347 9.7 enterOptionConfigMode Command ..................................................................................... 348 9.8 getOptionConfigModeStatus Command .............................................................................. 348 9.9 optionConfigModeStatus Command .................................................................................... 349 9.10 getOptionConfigProfile Command ..................................................................................... 349 9.11 optionConfigProfile Command ........................................................................................... 350 9.12 getOptionList Command .................................................................................................... 350 9.13 optionList Command .......................................................................................................... 351 9.13.1 deviceOptions........................................................................................................... 352 9.13.2 optionGroup.............................................................................................................. 352 9.13.3 optionItem................................................................................................................. 353 9.13.4 optionParameters ..................................................................................................... 354 9.13.5 integerParameter...................................................................................................... 355 9.13.6 decimalParameter .................................................................................................... 356 9.13.7 stringParameter ........................................................................................................ 357 9.13.8 booleanParameter .................................................................................................... 358 9.13.9 complexParameter ................................................................................................... 359 9.13.10 optionCurrentValues............................................................................................... 360 9.13.11 optionDefaultValues ............................................................................................... 361 9.14 optionListAck Command .................................................................................................... 362 9.15 setOptionChange Command.............................................................................................. 362 9.15.1 option........................................................................................................................ 364 9.15.2 authorizedList ........................................................................................................... 364 9.16 cancelOptionChange Command ........................................................................................ 365 9.17 authorizeOptionChange Command.................................................................................... 365 9.18 optionChangeStatus Command ......................................................................................... 366 9.19 optionChangeStatusAck Command ................................................................................... 367 9.20 getOptionChangeLogStatus Command ............................................................................. 368 9.21 optionChangeLogStatus Command ................................................................................... 368 9.22 getOptionChangeLog Command ....................................................................................... 368 9.23 optionChangeLogList Command........................................................................................ 369 9.24 Data Types......................................................................................................................... 371 9.24.1 optionConfigExceptions: Change Exception Codes ................................................. 371 9.25 Error Codes........................................................................................................................ 372 9.26 Event codes ....................................................................................................................... 373 9.26.1 9.26.2 9.26.3 9.26.4 9.26.5 9.26.6 9.26.7 9.26.8 evaluate(state).......................................................................................................... 374 G2S_OCE001 optionConfig Disabled by EGM ....................................................... 374 G2S_OCE002 optionConfig Enabled by EGM ........................................................ 374 G2S_OCE003 optionConfig Configuration Changed by Host ................................. 375 G2S_OCE004 optionConfig Configuration Changed by Operator .......................... 375 G2S_OCE101 optionConfig Entered Configuration Mode ...................................... 375 G2S_OCE102 optionConfig Exited Configuration Mode ......................................... 376 G2S_OCE103 optionConfig Configuration Change Pending .................................. 376 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xiii G2S™ Message Protocol v1.0.3 Table of Contents 9.26.9 G2S_OCE104 optionConfig Configuration Authorized by Host ............................... 377 9.26.10 G2S_OCE105 optionConfig Configuration Cancelled ........................................... 378 9.26.11 G2S_OCE106 optionConfig Configuration Change Applied ................................. 379 9.26.12 G2S_OCE107 optionConfig Configuration Aborted .............................................. 380 9.26.13 G2S_OCE108 optionConfig Error ......................................................................... 381 9.26.14 G2S_OCE109 optionConfig Configuration Waiting on Authorization .................... 382 9.26.15 G2S_OCE110 optionConfig Configuration Change Authorization Timeout .......... 383 9.27 Examples ........................................................................................................................... 384 9.27.1 Option List Command Sequence.............................................................................. 384 9.27.2 Set Option Command Sequence .............................................................................. 386 9.28 Option Configuration Device Option Configuration ............................................................ 388 9.28.1 9.28.2 9.28.3 9.28.4 Option Group Definitions .......................................................................................... 388 G2S Protocol Option Definitions............................................................................... 388 G2S Protocol Option Sub-Parameter Definitions ..................................................... 388 Example optionItem Elements in optionList.............................................................. 389 10 download Class ............................................................................................... 391 10.1 Introduction ........................................................................................................................ 391 10.2 Packages and Modules...................................................................................................... 392 10.2.1 10.2.2 10.2.3 10.2.4 Definitions................................................................................................................. 392 Download Script Rules Overview ............................................................................. 393 Host Authorized Script .............................................................................................. 394 Transfer Protocol Undefined..................................................................................... 395 10.3 Download Network Overview ............................................................................................. 396 10.3.1 10.3.2 10.3.3 10.3.4 EGM Responsibilities ............................................................................................... 396 System Management Point Responsibilities ............................................................ 396 Software Download Distribution Point Responsibilities ............................................ 397 Authorization Host Responsibilities .......................................................................... 397 10.4 Package States .................................................................................................................. 399 10.5 Script States....................................................................................................................... 401 10.6 Request-Response Pairs ................................................................................................... 403 10.7 setDownloadState Command ............................................................................................ 404 10.8 getDownloadStatus Command .......................................................................................... 404 10.9 downloadStatus Command ................................................................................................ 405 10.10 getDownloadProfile Command ........................................................................................ 405 10.11 downloadProfile Command .............................................................................................. 406 10.12 addPackage Command.................................................................................................... 408 10.13 createPackage Command................................................................................................ 410 10.14 deletePackage Command................................................................................................ 411 10.15 uploadPackage Command............................................................................................... 412 10.16 getPackageStatus Command .......................................................................................... 413 10.17 packageStatus Command................................................................................................ 413 10.18 packageStatusAck Command.......................................................................................... 416 Page xiv gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 10.19 readPackageContents Command .................................................................................... 416 10.20 packageContents Command............................................................................................ 417 10.21 getPackageList Command ............................................................................................... 418 10.22 packageList Command .................................................................................................... 418 10.23 getPackageLogStatus Command .................................................................................... 419 10.24 packageLogStatus Command.......................................................................................... 419 10.25 getPackageLog Command............................................................................................... 419 10.26 packageLogList Command .............................................................................................. 420 10.27 setScript Command.......................................................................................................... 422 10.28 cancelScript Command .................................................................................................... 425 10.29 authorizeScript Command................................................................................................ 426 10.30 getScriptStatus Command ............................................................................................... 426 10.31 scriptStatus Command..................................................................................................... 427 10.32 scriptStatusAck Command............................................................................................... 430 10.33 getScriptList Command.................................................................................................... 431 10.34 scriptList Command ......................................................................................................... 431 10.35 getScriptLogStatus Command ......................................................................................... 431 10.36 scriptLogStatus Command............................................................................................... 432 10.37 getScriptLog Command ................................................................................................... 432 10.38 scriptLogList Command ................................................................................................... 433 10.39 getModuleList Command ................................................................................................. 434 10.40 moduleList Command ...................................................................................................... 435 10.41 Data Types....................................................................................................................... 437 10.41.1 TransferTypes Enumerations ................................................................................. 438 10.41.2 pkgStates Enumerations ........................................................................................ 439 10.41.3 pkgExceptions Enumerations ................................................................................. 439 10.41.4 pkgFormats Enumerations ..................................................................................... 439 10.41.5 transferStates Enumerations .................................................................................. 439 10.41.6 transferExceptions Enumerations........................................................................... 440 10.41.7 scriptStates Enumerations...................................................................................... 440 10.41.8 scriptExceptions Enumerations .............................................................................. 441 10.41.9 operPackage Enumerations ................................................................................... 441 10.41.10 operModule Enumerations ................................................................................... 441 10.41.11 operSystem Enumerations ................................................................................... 441 10.41.12 operCmdStates Enumerations ............................................................................. 442 10.41.13 operCmdExceptions Enumerations ...................................................................... 442 10.41.14 modStates Enumerations ..................................................................................... 442 10.41.15 modTypes Enumerations...................................................................................... 443 10.41.16 modException Enumerations................................................................................ 443 10.41.17 storageApplication Enumerations......................................................................... 443 10.42 Error Codes...................................................................................................................... 444 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xv G2S™ Message Protocol v1.0.3 Table of Contents 10.43 Event Codes..................................................................................................................... 445 10.43.1 evaluate(state) ........................................................................................................ 447 10.43.2 G2S_DLE001 Device Disabled by EGM ............................................................... 447 10.43.3 G2S_DLE002 Device Enabled by EGM ................................................................ 447 10.43.4 G2S_DLE003 Device Disabled by Host ................................................................ 448 10.43.5 G2S_DLE004 Device Enabled by Host ................................................................. 448 10.43.6 G2S_DLE005 Device Configuration Changed by Host ......................................... 448 10.43.7 G2S_DLE006 Device Configuration Changed at EGM ......................................... 449 10.43.8 G2S_DLE007 EGM Locked by Device .................................................................. 449 10.43.9 G2S_DLE008 EGM Unlocked by Device .............................................................. 449 10.43.10 G2S_DLE101 Package Added ............................................................................ 450 10.43.11 G2S_DLE102 Package Download Initiated ......................................................... 451 10.43.12 G2S_DLE103 Package Download Refused ........................................................ 452 10.43.13 G2S_DLE104 Insufficient Storage for Package Download ................................. 453 10.43.14 G2S_DLE105 Package Download in Progress ................................................... 454 10.43.15 G2S_DLE106 Package Download Complete ...................................................... 455 10.43.16 G2S_DLE107 Package Download Aborted ......................................................... 456 10.43.17 G2S_DLE108 Package Passed Validation .......................................................... 457 10.43.18 G2S_DLE109 Package Failed Validation ............................................................ 458 10.43.19 G2S_DLE110 Package Created .......................................................................... 459 10.43.20 G2S_DLE120 Package Upload Requested ......................................................... 460 10.43.21 G2S_DLE121 Package Upload Initiated ............................................................. 461 10.43.22 G2S_DLE122 Package Upload Refused ............................................................. 462 10.43.23 G2S_DLE123 Package Upload in Progress ........................................................ 463 10.43.24 G2S_DLE124 Package Upload Complete ........................................................... 464 10.43.25 G2S_DLE125 Package Upload Aborted ............................................................. 465 10.43.26 G2S_DLE140 Package Deleted .......................................................................... 466 10.43.27 G2S_DLE201 Script Set ...................................................................................... 467 10.43.28 G2S_DLE202 Script Authorization Enabled by Host ........................................... 468 10.43.29 G2S_DLE203 Script Authorization Disabled by Host .......................................... 469 10.43.30 G2S_DLE204 Script Time Started ....................................................................... 470 10.43.31 G2S_DLE205 Script Time Ended ........................................................................ 471 10.43.32 G2S_DLE206 Script EGM Disable Started ......................................................... 472 10.43.33 G2S_DLE207 Script Waiting on Authorization .................................................... 473 10.43.34 G2S_DLE208 Script Waiting on Operator Initiation ............................................. 474 10.43.35 G2S_DLE209 Script Initiated, Commands Executing ......................................... 475 10.43.36 G2S_DLE210 Script Command Execution In Progress ...................................... 476 10.43.37 G2S_DLE211 Script Completed .......................................................................... 477 10.43.38 G2S_DLE212 Script Error ................................................................................... 478 10.43.39 G2S_DLE213 Script Cancelled ........................................................................... 479 10.43.40 G2S_DLE301 Module Added .............................................................................. 479 10.43.41 G2S_DLE302 Module Deleted ............................................................................ 480 10.43.42 G2S_DLE303 Module Enabled ........................................................................... 480 10.43.43 G2S_DLE304 Module Disabled ........................................................................... 480 10.43.44 G2S_DLE305 Module Error ................................................................................. 481 10.44 Examples ......................................................................................................................... 482 10.44.1 10.44.2 10.44.3 10.44.4 10.44.5 10.44.6 Page xvi Device Status Commands ...................................................................................... 482 Device Profile Commands ...................................................................................... 483 Package Commands .............................................................................................. 484 Package Log Commands ....................................................................................... 489 Script Commands ................................................................................................... 491 Script Log Commands ............................................................................................ 497 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 10.44.7 Module List Commands .......................................................................................... 499 10.45 Download Device Option Configuration ........................................................................... 500 10.45.1 10.45.2 10.45.3 10.45.4 10.45.5 10.45.6 Option Group Definitions ........................................................................................ 500 G2S Protocol Option Definitions............................................................................. 500 G2S Protocol Option Sub-Parameter Definitions ................................................... 500 Download Option Definitions .................................................................................. 501 Download Option Sub-Parameter Definitions ......................................................... 501 Example optionItem Elements in optionList............................................................ 502 11 handpay Class ................................................................................................. 505 11.1 Introduction ........................................................................................................................ 505 11.2 Transaction Identifiers........................................................................................................ 506 11.3 Transaction Logs................................................................................................................ 506 11.4 Log Sequence Numbers .................................................................................................... 506 11.5 Meters ................................................................................................................................ 507 11.6 Request-Response Pairs ................................................................................................... 508 11.7 setHandpayState Command .............................................................................................. 509 11.8 getHandpayStatus Command ............................................................................................ 509 11.9 handpayStatus Command.................................................................................................. 510 11.10 getHandpayProfile Command .......................................................................................... 510 11.11 handpayProfile Command................................................................................................ 511 11.12 handpayRequest Command ............................................................................................ 513 11.13 handpayAck Command.................................................................................................... 516 11.14 setRemoteKeyOff Command ........................................................................................... 516 11.15 remoteKeyOffAck Command ........................................................................................... 517 11.16 keyedOff Command ......................................................................................................... 517 11.17 keyedOffAck Command ................................................................................................... 518 11.18 getHandpayLogStatus Command .................................................................................... 518 11.19 handpayLogStatus Command.......................................................................................... 518 11.20 getHandpayLog Command .............................................................................................. 519 11.21 handpayLogList Command .............................................................................................. 519 11.22 Data Types....................................................................................................................... 523 11.22.1 Reserved keyOffType Enumerations ..................................................................... 523 11.23 Error Codes...................................................................................................................... 524 11.24 Event Codes..................................................................................................................... 525 11.24.1 11.24.2 11.24.3 11.24.4 11.24.5 11.24.6 11.24.7 11.24.8 evaluate(state) ........................................................................................................ 526 G2S_JPE001 Handpays Disabled by EGM ........................................................... 526 G2S_JPE002 Handpays Enabled by EGM ........................................................... 526 G2S_JPE003 Handpays Disabled by Host ........................................................... 527 G2S_JPE004 Handpays Enabled by Host ............................................................ 527 G2S_JPE005 Handpay Configuration Changed by Host ...................................... 527 G2S_JPE006 Handpay Configuration Changed by Operator ............................... 528 G2S_JPE101 Handpay Pending ........................................................................... 528 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xvii G2S™ Message Protocol v1.0.3 Table of Contents 11.24.9 G2S_JPE102 Handpay Request Acknowledged ................................................... 529 11.24.10 G2S_JPE103 Remote Key-Off Initiated .............................................................. 531 11.24.11 G2S_JPE104 Handpay Keyed Off ...................................................................... 531 11.24.12 G2S_JPE105 Key-Off Acknowledged ................................................................. 533 11.24.13 G2S_JPE106 Cancelled-Credit Request Cancelled ............................................ 535 11.25 Examples ......................................................................................................................... 537 11.25.1 Handpay Request Commands ............................................................................... 538 11.25.2 Remote Key Off Commands................................................................................... 539 11.25.3 Key Off Commands ................................................................................................ 540 11.26 Handpay Device Option Configuration............................................................................. 541 11.26.1 11.26.2 11.26.3 11.26.4 11.26.5 11.26.6 Option Group Definitions ........................................................................................ 541 G2S Protocol Option Definitions............................................................................. 541 G2S Protocol Option Sub-Parameter Definitions ................................................... 541 Handpay Option Definitions.................................................................................... 542 Handpay Option Sub-Parameter Definitions .......................................................... 542 Example optionItem Elements in optionList............................................................ 543 12 coinAcceptor Class......................................................................................... 547 12.1 Introduction ........................................................................................................................ 547 12.2 Exchange Rates................................................................................................................. 547 12.3 Meters ................................................................................................................................ 547 12.4 Request-Response Pairs ................................................................................................... 548 12.5 setCoinAcceptorState Command....................................................................................... 549 12.6 getCoinAcceptorStatus Command..................................................................................... 549 12.7 coinAcceptorStatus Command........................................................................................... 550 12.8 getCoinAcceptorProfile Command..................................................................................... 551 12.9 coinAcceptorProfile Command........................................................................................... 552 12.10 Data Types....................................................................................................................... 553 12.11 Error Codes...................................................................................................................... 553 12.12 Event Codes..................................................................................................................... 554 12.12.1 evaluate(state) ........................................................................................................ 555 12.12.2 G2S_CAE001 Device Disabled by EGM ............................................................... 555 12.12.3 G2S_CAE002 Device Enabled by EGM ................................................................ 555 12.12.4 G2S_CAE003 Device Disabled by Host ................................................................ 556 12.12.5 G2S_CAE004 Device Enabled by Host ................................................................. 556 12.12.6 G2S_CAE005 Device Configuration Changed by Host ......................................... 556 12.12.7 G2S_CAE006 Device Configuration Changed by Operator .................................. 557 12.12.8 G2S_CAE099 Device Faults Cleared .................................................................... 557 12.12.9 G2S_CAE101 Acceptor Jammed .......................................................................... 557 12.12.10 G2S_CAE102 Acceptor Fault .............................................................................. 558 12.12.11 G2S_CAE103 Diverter Fault ............................................................................... 558 12.12.12 G2S_CAE104 Coin Acceptor Lockout Malfunction ............................................. 558 12.12.13 G2S_CAE105 Inappropriate Coin Not Returned ................................................. 559 12.12.14 G2S_CAE106 Coin In Limit Reached .................................................................. 559 12.12.15 G2S_CAE107 Drop Door Opened ....................................................................... 559 12.12.16 G2S_CAE108 Drop Door Closed ........................................................................ 560 Page xviii gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 12.12.17 G2S_CAE109 Coins Accepted ............................................................................ 560 12.12.18 G2S_CAE901 Device Disconnected ................................................................... 561 12.12.19 G2S_CAE902 Device Connected ........................................................................ 561 12.12.20 G2S_CAE903 Device Firmware Fault ................................................................. 561 12.12.21 G2S_CAE904 Device Mechanical Fault .............................................................. 562 12.12.22 G2S_CAE905 Device Optical Fault ..................................................................... 562 12.12.23 G2S_CAE906 Device Component Fault ............................................................. 562 12.12.24 G2S_CAE907 Device Non-Volatile Memory Fault .............................................. 563 12.12.25 G2S_CAE908 Illegal Activity Detected ................................................................ 563 12.13 Examples ......................................................................................................................... 564 12.13.1 Enable Device Command Sequence...................................................................... 564 12.13.2 Get Profile Command Sequence ............................................................................ 565 12.14 Coin Acceptor Device Option Configuration..................................................................... 566 12.14.1 12.14.2 12.14.3 12.14.4 12.14.5 12.14.6 Option Group Definitions ........................................................................................ 566 G2S Protocol Option Definitions............................................................................. 566 G2S Protocol Option Sub-Parameter Definitions ................................................... 566 Coin Data Table Option Definitions ........................................................................ 567 Coin Data Table Sub-Parameter Definitions .......................................................... 567 Example optionItem Elements in optionList............................................................ 568 13 noteAcceptor Class......................................................................................... 571 13.1 Introduction ........................................................................................................................ 571 13.2 Transaction Logs................................................................................................................ 571 13.3 Log Sequence Numbers .................................................................................................... 571 13.4 Exchange Rates................................................................................................................. 571 13.5 Meters ................................................................................................................................ 572 13.6 Loss Limit Support ............................................................................................................. 572 13.7 Request-Response Pairs ................................................................................................... 573 13.8 setNoteAcceptorState Command....................................................................................... 574 13.9 getNoteAcceptorStatus Command..................................................................................... 574 13.10 noteAcceptorStatus Command ........................................................................................ 575 13.11 getNoteAcceptorProfile Command................................................................................... 576 13.12 noteAcceptorProfile Command ........................................................................................ 576 13.13 getNotesAcceptedStatus Command ................................................................................ 578 13.14 notesAcceptedStatus Command...................................................................................... 578 13.15 getNotesAccepted Command .......................................................................................... 578 13.16 notesAcceptedList Command .......................................................................................... 579 13.17 Data Types....................................................................................................................... 580 13.18 Error Codes...................................................................................................................... 580 13.19 Event Codes..................................................................................................................... 581 13.19.1 13.19.2 13.19.3 13.19.4 evaluate(state) ........................................................................................................ 582 G2S_NAE001 Device Disabled by EGM ............................................................... 582 G2S_NAE002 Device Enabled by EGM ................................................................ 583 G2S_NAE003 Device Disabled by Host ................................................................ 583 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xix G2S™ Message Protocol v1.0.3 Table of Contents 13.19.5 G2S_NAE004 Device Enabled by Host ................................................................. 583 13.19.6 G2S_NAE005 Device Configuration Changed by Host ......................................... 584 13.19.7 G2S_NAE006 Device Configuration Changed by Operator .................................. 584 13.19.8 G2S_NAE099 Device Faults Cleared .................................................................... 584 13.19.9 G2S_NAE101 Acceptor Jammed .......................................................................... 585 13.19.10 G2S_NAE102 Acceptor Fault .............................................................................. 585 13.19.11 G2S_NAE103 Stacker Removed ........................................................................ 585 13.19.12 G2S_NAE104 Stacker Inserted ........................................................................... 586 13.19.13 G2S_NAE105 Stacker Full .................................................................................. 586 13.19.14 G2S_NAE106 Stacker Jammed .......................................................................... 586 13.19.15 G2S_NAE107 Stacker Fault ................................................................................ 587 13.19.16 G2S_NAE108 Note Returned .............................................................................. 587 13.19.17 G2S_NAE109 Voucher Returned ........................................................................ 587 13.19.18 G2S_NAE110 Note or Voucher Rejected ............................................................ 587 13.19.19 G2S_NAE111 Validator Totals Reset .................................................................. 588 13.19.20 G2S_NAE112 Stacker Door Opened .................................................................. 588 13.19.21 G2S_NAE113 Stacker Door Closed .................................................................... 588 13.19.22 G2S_NAE114 Note Stacked ............................................................................... 589 13.19.23 G2S_NAE115 Voucher Stacked .......................................................................... 590 13.19.24 G2S_NAE116 Note In Escrow ............................................................................. 590 13.19.25 G2S_NAE117 Stacker Nearly Full ....................................................................... 590 13.19.26 G2S_NAE901 Device Disconnected ................................................................... 590 13.19.27 G2S_NAE902 Device Connected ........................................................................ 591 13.19.28 G2S_NAE903 Device Firmware Fault ................................................................. 591 13.19.29 G2S_NAE904 Device Mechanical Fault .............................................................. 591 13.19.30 G2S_NAE905 Device Optical Fault ..................................................................... 592 13.19.31 G2S_NAE906 Device Component Fault ............................................................. 592 13.19.32 G2S_NAE907 Device Non-Volatile Memory Fault .............................................. 592 13.19.33 G2S_NAE908 Illegal Activity Detected ................................................................ 593 13.20 Examples ......................................................................................................................... 594 13.20.1 Enable Device Command Sequence...................................................................... 594 13.20.2 Get Profile Command Sequence ............................................................................ 595 13.20.3 Get Log Command Sequence ................................................................................ 597 13.21 Note Acceptor Device Option Configuration .................................................................... 598 13.21.1 13.21.2 13.21.3 13.21.4 13.21.5 13.21.6 13.21.7 13.21.8 Option Group Definitions ........................................................................................ 598 G2S Protocol Option Definitions............................................................................. 598 G2S Protocol Option Sub-Parameter Definitions ................................................... 598 Note Acceptor Option Definitions ........................................................................... 599 Note Acceptor Options Sub-Parameter Definitions ................................................ 599 Note Acceptor Data Table Option Definitions ......................................................... 599 Note Data Table Sub-Parameter Definitions .......................................................... 599 Example optionItem Elements in optionList............................................................ 600 14 hopper Class.................................................................................................... 603 14.1 Introduction ........................................................................................................................ 603 14.2 Exchange Rates................................................................................................................. 603 14.3 Meters ................................................................................................................................ 603 14.4 Request-Response Pairs ................................................................................................... 604 14.5 setHopperState Command................................................................................................. 605 Page xx gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 14.6 getHopperStatus Command............................................................................................... 605 14.7 hopperStatus Command .................................................................................................... 605 14.8 getHopperProfile Command............................................................................................... 607 14.9 hopperProfile Command .................................................................................................... 607 14.10 Data Types....................................................................................................................... 608 14.11 Error Codes...................................................................................................................... 608 14.12 Event Codes..................................................................................................................... 609 14.12.1 evaluate(state) ........................................................................................................ 610 14.12.2 G2S_HPE001 Device Disabled by EGM ............................................................... 610 14.12.3 G2S_HPE002 Device Enabled by EGM ................................................................ 610 14.12.4 G2S_HPE003 Device Disabled by Host ................................................................ 611 14.12.5 G2S_HPE004 Device Enabled by Host ................................................................. 611 14.12.6 G2S_HPE005 Device Configuration Changed by Host ......................................... 611 14.12.7 G2S_HPE006 Device Configuration Changed by Operator .................................. 612 14.12.8 G2S_HPE099 Device Faults Cleared .................................................................... 612 14.12.9 G2S_HPE101 Hopper Empty ................................................................................ 612 14.12.10 G2S_HPE102 Hopper Full .................................................................................. 613 14.12.11 G2S_HPE103 Hopper Jammed .......................................................................... 613 14.12.12 G2S_HPE104 Hopper Below High Water Mark .................................................. 613 14.12.13 G2S_HPE105 Hopper Above High Water Mark .................................................. 613 14.12.14 G2S_HPE106 Hopper Below Low Water Mark ................................................... 614 14.12.15 G2S_HPE107 Hopper Above Low Water Mark ................................................... 614 14.12.16 G2S_HPE108 Hopper Fault ................................................................................ 614 14.12.17 G2S_HPE109 Extra Coins Paid .......................................................................... 615 14.12.18 G2S_HPE110 Runaway Hopper ......................................................................... 615 14.12.19 G2S_HPE111 Dispenser Door Opened .............................................................. 616 14.12.20 G2S_HPE112 Dispenser Door Closed ................................................................ 616 14.12.21 G2S_HPE113 Coins Dispensed .......................................................................... 617 14.12.22 G2S_HPE901 Device Disconnected ................................................................... 618 14.12.23 G2S_HPE902 Device Connected ........................................................................ 618 14.12.24 G2S_HPE903 Device Firmware Fault ................................................................. 618 14.12.25 G2S_HPE904 Device Mechanical Fault .............................................................. 619 14.12.26 G2S_HPE905 Device Optical Fault ..................................................................... 619 14.12.27 G2S_HPE906 Device Component Fault ............................................................. 619 14.12.28 G2S_HPE907 Device Non-Volatile Memory Fault .............................................. 620 14.12.29 G2S_HPE908 Illegal Activity Detected ................................................................ 620 14.13 Examples ......................................................................................................................... 621 14.13.1 14.13.2 14.13.3 14.13.4 Enable Device Command Sequence...................................................................... 621 Get Profile Command Sequence ............................................................................ 622 getHopperProfile: Host Request to EGM................................................................ 622 hopperProfile: EGM Response to getHopperProfile ............................................... 622 14.14 Hopper Device Option Configuration ............................................................................... 623 14.14.1 14.14.2 14.14.3 14.14.4 14.14.5 14.14.6 Option Group Definitions ........................................................................................ 623 G2S Protocol Option Definitions............................................................................. 623 G2S Protocol Options Sub-Parameter Definitions.................................................. 623 Hopper Option Definitions ...................................................................................... 624 Hopper Option Sub-Parameter Definitions ............................................................. 624 Example optionItem Elements in optionList............................................................ 625 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxi G2S™ Message Protocol v1.0.3 Table of Contents 15 noteDispenser Class....................................................................................... 627 15.1 Introduction ........................................................................................................................ 627 15.2 Transaction Logs................................................................................................................ 627 15.3 Log Sequence Numbers .................................................................................................... 627 15.4 Exchange Rates................................................................................................................. 627 15.5 Meters ................................................................................................................................ 627 15.6 Request-Response Pairs ................................................................................................... 628 15.7 setNoteDispenserState Command..................................................................................... 629 15.8 getNoteDispenserStatus Command................................................................................... 629 15.9 noteDispenserStatus Command ........................................................................................ 629 15.10 getNoteDispenserProfile Command................................................................................. 631 15.11 noteDispenserProfile Command ...................................................................................... 631 15.12 getNotesDispensedStatus Command .............................................................................. 632 15.13 notesDispensedStatus Command.................................................................................... 632 15.14 getNotesDispensed Command ........................................................................................ 633 15.15 notesDispensedList Command ........................................................................................ 634 15.16 Data Types....................................................................................................................... 635 15.17 Error Codes...................................................................................................................... 635 15.18 Event Codes..................................................................................................................... 636 15.18.1 evaluate(state) ........................................................................................................ 637 15.18.2 G2S_NDE001 Device Disabled by EGM ............................................................... 637 15.18.3 G2S_NDE002 Device Enabled by EGM ................................................................ 638 15.18.4 G2S_NDE003 Device Disabled by Host ................................................................ 638 15.18.5 G2S_NDE004 Device Enabled by Host ................................................................ 638 15.18.6 G2S_NDE005 Device Configuration Changed by Host ......................................... 639 15.18.7 G2S_NDE006 Device Configuration Changed by Operator .................................. 639 15.18.8 G2S_NDE099 Device Faults Cleared ................................................................... 639 15.18.9 G2S_NDE101 Dispenser Empty ........................................................................... 640 15.18.10 G2S_NDE102 Dispenser Full .............................................................................. 640 15.18.11 G2S_NDE103 Dispenser Jammed ...................................................................... 640 15.18.12 G2S_NDE104 Dispenser Below High Water Mark .............................................. 641 15.18.13 G2S_NDE105 Dispenser Above High Water Mark ............................................. 641 15.18.14 G2S_NDE106 Dispenser Below Low Water Mark ............................................... 641 15.18.15 G2S_NDE107 Dispenser Above Low Water Mark .............................................. 641 15.18.16 G2S_NDE108 Dispenser Fault ............................................................................ 642 15.18.17 G2S_NDE109 Dispenser Door Opened .............................................................. 642 15.18.18 G2S_NDE110 Dispenser Door Closed ................................................................ 642 15.18.19 G2S_NDE111 Note Dispensed ........................................................................... 643 15.18.20 G2S_NDE901 Device Disconnected ................................................................... 644 15.18.21 G2S_NDE902 Device Connected ....................................................................... 644 15.18.22 G2S_NDE903 Device Firmware Fault ................................................................. 645 15.18.23 G2S_NDE904 Device Mechanical Fault .............................................................. 645 15.18.24 G2S_NDE905 Device Optical Fault ..................................................................... 645 15.18.25 G2S_NDE906 Device Component Fault ............................................................. 646 15.18.26 G2S_NDE907 Device Non-Volatile Memory Fault .............................................. 646 15.18.27 G2S_NDE908 Illegal Activity Detected ................................................................ 646 15.19 Examples ......................................................................................................................... 647 Page xxii gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 15.19.1 Enable Device Command Sequence...................................................................... 647 15.19.2 Get Profile Command Sequence ............................................................................ 648 15.19.3 Get Log Command Sequence ................................................................................ 650 15.20 Note Dispenser Device Option Configuration .................................................................. 652 15.20.1 15.20.2 15.20.3 15.20.4 15.20.5 15.20.6 Option Group Definitions ........................................................................................ 652 G2S Protocol Option Definitions............................................................................. 652 G2S Protocol Options Sub-Parameter Definitions.................................................. 652 Note Dispenser Data Table Option Definitions ....................................................... 653 Note Data Table Sub-Parameter Definitions .......................................................... 653 Example optionItem Elements in OptionList ........................................................... 654 16 printer Class .................................................................................................... 657 16.1 Introduction ........................................................................................................................ 657 16.2 Transaction Logs................................................................................................................ 657 16.3 Log Sequence Numbers .................................................................................................... 658 16.4 Meters ................................................................................................................................ 658 16.5 Request-Response Pairs ................................................................................................... 659 16.6 setPrinterState Command.................................................................................................. 660 16.7 getPrinterStatus Command................................................................................................ 660 16.8 printerStatus Command ..................................................................................................... 660 16.9 getPrinterProfile Command................................................................................................ 662 16.10 printerProfile Command ................................................................................................... 662 16.11 getPrinterTemplates Command ....................................................................................... 664 16.12 printerTemplateList Command......................................................................................... 664 16.13 printTicket Command ....................................................................................................... 665 16.14 printComplete Command ................................................................................................. 666 16.15 getPrintLogStatus Command ........................................................................................... 667 16.16 printLogStatus Command ................................................................................................ 667 16.17 getPrintLog Command ..................................................................................................... 668 16.18 printLogList Command ..................................................................................................... 668 16.19 Data Types....................................................................................................................... 670 16.20 Error Codes...................................................................................................................... 670 16.21 Event Codes.................................................................................................................... 671 16.21.1 evaluate(state) ........................................................................................................ 672 16.21.2 G2S_PTE001 Printer Disabled by EGM ................................................................ 672 16.21.3 G2S_PTE002 Printer Enabled by EGM ................................................................. 672 16.21.4 G2S_PTE003 Printer Disabled by Host ................................................................. 673 16.21.5 G2S_PTE004 Printer Enabled by Host ................................................................. 673 16.21.6 G2S_PTE005 Printer Configuration Changed by Host .......................................... 673 16.21.7 G2S_PTE006 Printer Configuration Changed by Operator ................................... 674 16.21.8 G2S_PTE099 All Device Faults Cleared ............................................................... 674 16.21.9 G2S_PTE101 Print Transfer Failed ....................................................................... 675 16.21.10 G2S_PTE102 Print Completed ............................................................................ 676 16.21.11 G2S_PTE103 Print Failed ................................................................................... 677 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxiii G2S™ Message Protocol v1.0.3 Table of Contents 16.21.12 G2S_PTE201 Printer Chassis Opened ............................................................... 678 16.21.13 G2S_PTE202 Printer Chassis Closed ................................................................. 678 16.21.14 G2S_PTE203 Print Head Opened ....................................................................... 678 16.21.15 G2S_PTE204 Print Head Closed ........................................................................ 679 16.21.16 G2S_PTE205 Paper Jam .................................................................................... 679 16.21.17 G2S_PTE206 Paper Low .................................................................................... 679 16.21.18 G2S_PTE207 Paper Empty ................................................................................. 680 16.21.19 G2S_PTE901 Device Disconnected .................................................................... 680 16.21.20 G2S_PTE902 Device Connected ........................................................................ 680 16.21.21 G2S_PTE903 Device Firmware Failure .............................................................. 681 16.21.22 G2S_PTE904 Device Mechanical Failure ........................................................... 681 16.21.23 G2S_PTE905 Device Optical Failure .................................................................. 681 16.21.24 G2S_PTE906 Device Component Failure ........................................................... 682 16.21.25 G2S_PTE907 Device Non-Volatile Memory Failure ............................................ 682 16.22 Examples ......................................................................................................................... 683 16.22.1 Print Ticket Commands .......................................................................................... 684 16.23 Printer Device Option Configuration................................................................................. 685 16.23.1 16.23.2 16.23.3 16.23.4 16.23.5 16.23.6 16.23.7 16.23.8 Option Group Definitions ........................................................................................ 685 G2S Protocol Option Definitions............................................................................. 685 G2S Protocol Options Sub-Parameter Definitions.................................................. 685 Printer Template Table Option Definitions.............................................................. 686 Printer Template Table Sub-Parameter Definitions ................................................ 686 Printer Region Table Option Definitions ................................................................. 686 Printer Region Table Sub-Parameter Definitions ................................................... 686 Example optionItem Elements in optionList............................................................ 687 17 progressive Class ........................................................................................... 689 17.1 Introduction ........................................................................................................................ 689 17.2 Progressive Identifiers and Levels ..................................................................................... 689 17.3 Progressive Contributions .................................................................................................. 689 17.4 EGM-Based Mystery Progressives .................................................................................... 690 17.5 Progressive Configuration Identifier ................................................................................... 690 17.6 No Progressive Information................................................................................................ 690 17.7 Transaction Identifier.......................................................................................................... 690 17.8 Transaction Logs................................................................................................................ 691 17.9 Request-Response Pairs ................................................................................................... 692 17.10 setProgressiveState Command ....................................................................................... 693 17.11 setProgressiveLockOut Command .................................................................................. 693 17.12 getProgressiveStatus Command ..................................................................................... 694 17.13 progressiveStatus Command........................................................................................... 694 17.14 getProgressiveProfile Command ..................................................................................... 695 17.15 progressiveProfile Command........................................................................................... 696 17.15.1 Configuration: Mapping Games to Progressives .................................................... 696 17.16 setProgressiveValue Command....................................................................................... 698 17.17 progressiveValueAck Command...................................................................................... 698 Page xxiv gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 17.18 progressiveHit Command................................................................................................. 699 17.18.1 EGM Timeout ......................................................................................................... 699 17.18.2 Host Rejection of EGM Progressive Hit.................................................................. 699 17.19 setProgressiveWin Command.......................................................................................... 701 17.20 progressiveCommit Command......................................................................................... 702 17.21 progressiveCommitAck Command................................................................................... 703 17.22 getProgressiveHostInfo Command .................................................................................. 703 17.23 progressiveHostInfo Command........................................................................................ 703 17.24 getProgressiveLogStatus Command ............................................................................... 705 17.25 progressiveLogStatus Command..................................................................................... 705 17.26 getProgressiveLog Command.......................................................................................... 706 17.27 progressiveLogList Command ......................................................................................... 706 17.28 Data Types....................................................................................................................... 708 17.28.1 progExceptions Enumerations: Progressive Award Exception Codes .................. 708 17.29 Error Codes...................................................................................................................... 709 17.30 Event Codes..................................................................................................................... 710 17.30.1 evaluate(state) ........................................................................................................ 711 17.30.2 G2S_PGE001 Progressive Disabled by EGM ....................................................... 711 17.30.3 G2S_PGE002 Progressive Enabled by EGM ........................................................ 711 17.30.4 G2S_PGE003 Progressive Disabled by Host ........................................................ 712 17.30.5 G2S_PGE004 Progressive Enabled by Host ........................................................ 712 17.30.6 G2S_PGE005 Progressive Configuration Changed by Host ................................. 712 17.30.7 G2S_PGE006 Progressive Configuration Changed by Operator .......................... 713 17.30.8 G2S_PGE009 EGM Locked by Progressive Host ................................................. 713 17.30.9 G2S_PGE010 EGM Unlocked by Progressive Host ............................................. 713 17.30.10 G2S_PGE101 Progressive Money Wagered ...................................................... 714 17.30.11 G2S_PGE102 Progressive Hit ............................................................................ 714 17.30.12 G2S_PGE103 Progressive Hit Ack ..................................................................... 716 17.30.13 G2S_PGE104 Progressive Committed ............................................................... 717 17.30.14 G2S_PGE105 Progressive Win Acknowledged/Closed ...................................... 718 17.30.15 G2S_PGE106 Progressive Failed ....................................................................... 719 17.31 Examples ........................................................................................................................ 720 17.31.1 17.31.2 17.31.3 17.31.4 17.31.5 Progressive Device Status Commands .................................................................. 720 Progressive Profile Commands .............................................................................. 720 Progressive Log Commands .................................................................................. 720 Progressive Host Information Commands .............................................................. 720 Progressive Commands ......................................................................................... 721 17.32 Progressive Device Option Configuration ........................................................................ 724 17.32.1 17.32.2 17.32.3 17.32.4 17.32.5 17.32.6 Option Group Definitions ........................................................................................ 724 G2S Protocol Option Definitions............................................................................. 724 G2S Protocol Option Sub-Parameter Definitions ................................................... 724 Progressive Data Table Option Definitions............................................................. 725 Progressive Data Table Sub-Parameter Definitions ............................................... 725 Example optionItem Elements in OptionList ........................................................... 726 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxv G2S™ Message Protocol v1.0.3 Table of Contents 18 idReader Class ................................................................................................ 729 18.1 Introduction ........................................................................................................................ 729 18.2 Transaction Logs................................................................................................................ 730 18.3 Meters ................................................................................................................................ 730 18.4 Request-Response Pairs ................................................................................................... 731 18.5 setIdReaderState Command.............................................................................................. 732 18.6 getIdReaderStatus Command............................................................................................ 732 18.7 idReaderStatus Command................................................................................................. 733 18.8 getIdReaderProfile Command............................................................................................ 735 18.9 idReaderProfile Command................................................................................................. 735 18.10 getIdValidation Command................................................................................................ 739 18.11 setIdValidation Command ................................................................................................ 739 18.12 Data Types....................................................................................................................... 742 18.12.1 18.12.2 18.12.3 18.12.4 idTypes Enumerations: Identification Holder Types ............................................... 742 idStates Enumerations: Identification Statuses ...................................................... 743 idSources Enumerations: Identification Validation Sources ................................... 743 idValidMethods Enumerations: Identification Validation Methods .......................... 743 18.13 Error Codes...................................................................................................................... 744 18.14 Event Codes.................................................................................................................... 745 18.14.1 evaluate(state) ........................................................................................................ 746 18.14.2 G2S_IDE001 Device Disabled by EGM ................................................................ 746 18.14.3 G2S_IDE002 Device Enabled by EGM ................................................................. 746 18.14.4 G2S_IDE003 Device Disabled by Host ................................................................. 747 18.14.5 G2S_IDE004 ID Reader Enabled by Host ............................................................. 747 18.14.6 G2S_IDE005 Device Configuration Changed by Host .......................................... 747 18.14.7 G2S_IDE006 Device Configuration Changed by Operator ................................... 748 18.14.8 G2S_IDE099 Device Faults Cleared ..................................................................... 748 18.14.9 G2S_IDE101 Valid ID Presented .......................................................................... 749 18.14.10 G2S_IDE102 Invalid ID Presented ...................................................................... 750 18.14.11 G2S_IDE103 ID Cleared From Reader ............................................................... 751 18.14.12 G2S_IDE104 ID Validated Offline ....................................................................... 752 18.14.13 G2S_IDE105 Unable To Validate Id Offline ........................................................ 753 18.14.14 G2S_IDE106 Validation Information Changed .................................................... 754 18.14.15 G2S_IDE107 ID Validation Expired (ID Abandoned) .......................................... 755 18.14.16 G2S_IDE108 Invalid Validation Information Received ........................................ 756 18.14.17 G2S_IDE901 Device Disconnected .................................................................... 757 18.14.18 G2S_IDE902 Device Connected ......................................................................... 757 18.14.19 G2S_IDE903 Device Firmware Failure ............................................................... 757 18.14.20 G2S_IDE904 Device Mechanical Failure ............................................................ 758 18.14.21 G2S_IDE905 Device Optical Failure ................................................................... 758 18.14.22 G2S_IDE906 Device Component Failure ............................................................ 758 18.14.23 G2S_IDE907 Device Non-Volatile Memory Failure ............................................. 759 18.15 Examples ......................................................................................................................... 760 18.15.1 getIdValidation Command ...................................................................................... 761 18.15.2 setIdValidation Command ...................................................................................... 761 18.16 ID Reader Device Option Configuration........................................................................... 762 Page xxvi gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 18.16.1 Option Group Definitions ........................................................................................ 762 18.16.2 G2S Protocol Option Definitions............................................................................. 762 18.16.3 G2S Protocol Option Sub-Parameter Definitions ................................................... 762 18.16.4 ID Reader Option Definitions.................................................................................. 763 18.16.5 ID Reader Option Sub-Parameter Definitions ........................................................ 763 18.16.6 ID Reader Message Option Definitions .................................................................. 764 18.16.7 ID Reader Message Sub-Parameter Definitions .................................................... 764 18.16.8 ID Pattern Table Option Definitions ........................................................................ 765 18.16.9 ID Pattern Table Sub-Parameter Definitions .......................................................... 765 18.16.10 Example optionItem Elements in OptionList ......................................................... 766 19 bonus Class ..................................................................................................... 771 19.1 Introduction ........................................................................................................................ 771 19.2 Game Status and Game Delay .......................................................................................... 771 19.3 Bonus Awards and Game State......................................................................................... 772 19.4 Loss of Bonus Host Communications ................................................................................ 772 19.5 Bonus and Transaction Identifiers...................................................................................... 773 19.6 Transaction Logs................................................................................................................ 773 19.7 Log Sequence Numbers .................................................................................................... 773 19.8 Meters ................................................................................................................................ 773 19.9 Bonus Contributions........................................................................................................... 773 19.10 Request-Response Pairs ................................................................................................. 774 19.11 setBonusState Command ................................................................................................ 775 19.12 getBonusStatus Command .............................................................................................. 775 19.13 setBonusLockOut Command ........................................................................................... 775 19.14 setGameDelay Command................................................................................................ 776 19.15 bonusStatus Command.................................................................................................... 777 19.16 getBonusProfile Command .............................................................................................. 778 19.17 bonusProfile Command.................................................................................................... 778 19.18 bonusActivity Command .................................................................................................. 779 19.19 setBonusAward Command .............................................................................................. 780 19.20 bonusAwardAck Command.............................................................................................. 782 19.21 cancelBonusAward Command......................................................................................... 782 19.22 cancelBonusAwardAck Command................................................................................... 783 19.23 commitBonus Command.................................................................................................. 783 19.24 commitBonusAck Command............................................................................................ 784 19.25 setBonusMessage Command .......................................................................................... 785 19.26 bonusMessageAck Command ......................................................................................... 785 19.27 getBonusLogStatus Command ........................................................................................ 786 19.28 bonusLogStatus Command.............................................................................................. 786 19.29 getBonusLog Command .................................................................................................. 786 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxvii G2S™ Message Protocol v1.0.3 Table of Contents 19.30 bonusLogList Command .................................................................................................. 787 19.31 Data Types....................................................................................................................... 789 19.31.1 BonusExceptions: Exception Codes....................................................................... 789 19.32 Error Codes...................................................................................................................... 790 19.33 Event Codes..................................................................................................................... 791 19.33.1 evaluate(state) ........................................................................................................ 792 19.33.2 G2S_BNE001 Device Disabled by EGM ............................................................... 792 19.33.3 G2S_BNE002 Device Enabled by EGM ................................................................ 792 19.33.4 G2S_BNE003 Device Disabled by host ................................................................ 793 19.33.5 G2S_BNE004 Device Enabled by host ................................................................. 793 19.33.6 G2S_BNE005 Device Configuration Changed by Host ......................................... 793 19.33.7 G2S_BNE006 Device Configuration Changed by Operator .................................. 794 19.33.8 G2S_BNE007 EGM Locked by Host ..................................................................... 794 19.33.9 G2S_BNE008 EGM Unlocked by Host .................................................................. 794 19.33.10 G2S_BNE101 Bonus Period Started ................................................................... 795 19.33.11 G2S_BNE102 Bonus Period Ended .................................................................... 795 19.33.12 G2S_BNE103 Bonus Award Pending ................................................................. 796 19.33.13 G2S_BNE104 Bonus Award Paid ....................................................................... 797 19.33.14 G2S_BNE105 Bonus Award Failed ..................................................................... 800 19.33.15 G2S_BNE106 Bonus Award Canceled ............................................................... 801 19.33.16 G2S_BNE107 Bonus Award Acknowledged ....................................................... 802 19.33.17 G2S_BNE108 Bonus Host Communications Lost ............................................... 803 19.33.18 G2S_BNE109 Bonus Host Communications Restored ....................................... 803 19.34 Examples ......................................................................................................................... 804 19.34.1 19.34.2 19.34.3 19.34.4 19.34.5 19.34.6 Device State Commands ........................................................................................ 804 Device Profile Commands ...................................................................................... 805 Bonus Award Commands ....................................................................................... 806 Bonus Cancellation Commands ............................................................................. 808 Bonus Message Commands .................................................................................. 808 Device Log Commands .......................................................................................... 808 19.35 Bonus Device Option Configuration ................................................................................. 809 19.35.1 19.35.2 19.35.3 19.35.4 Option Group Definitions ........................................................................................ 809 G2S Protocol Option Definitions............................................................................. 809 G2S Protocol Option Sub-Parameter Definitions ................................................... 809 Example optionItem Elements in OptionList ........................................................... 810 20 player Class ..................................................................................................... 813 20.1 Introduction ........................................................................................................................ 813 20.2 ID Reader........................................................................................................................... 813 20.3 Countdowns and Point Awards .......................................................................................... 814 20.4 Countdown Basis and Countdown Carryover .................................................................... 817 20.5 Countdown Basis and RPN................................................................................................ 817 20.6 Offline Player Tracking....................................................................................................... 817 20.7 Hot Player .......................................................................................................................... 818 20.8 Interval Ratings .................................................................................................................. 818 20.9 Final Ratings ...................................................................................................................... 819 Page xxviii gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 20.10 Configuration Management.............................................................................................. 819 20.11 Transaction Identifiers...................................................................................................... 819 20.12 Transaction Logs.............................................................................................................. 820 20.13 Log Sequence Numbers .................................................................................................. 820 20.14 Request-Response Pairs ................................................................................................. 821 20.15 setPlayerState Command ................................................................................................ 822 20.16 getPlayerStatus Command .............................................................................................. 822 20.17 playerStatus Command.................................................................................................... 822 20.18 getPlayerProfile Command .............................................................................................. 824 20.19 playerProfile Command.................................................................................................... 824 20.20 getCountdownOverride Command................................................................................... 826 20.21 setCountdownOverride Command................................................................................... 827 20.22 playerSessionStart Command ......................................................................................... 828 20.23 playerSessionStartAck Command ................................................................................... 829 20.24 setCarryOver Command .................................................................................................. 830 20.25 carryOverAck Command.................................................................................................. 830 20.26 setPointBalance Command.............................................................................................. 831 20.27 setPlayerOverride Command........................................................................................... 831 20.28 setHostPoints Command ................................................................................................. 832 20.29 hostPointsAck Command................................................................................................. 832 20.30 playerSessionEnd Command........................................................................................... 833 20.31 playerSessionEndAck Command..................................................................................... 835 20.32 setPlayerMessage Command .......................................................................................... 836 20.33 playerMessageAck Command ......................................................................................... 836 20.34 getPlayerLogStatus Command ........................................................................................ 837 20.35 playerLogStatus Command.............................................................................................. 837 20.36 getPlayerLog Command .................................................................................................. 837 20.37 playerLogList Command .................................................................................................. 838 20.38 Data Types....................................................................................................................... 841 20.39 Error Codes...................................................................................................................... 841 20.40 Event Codes..................................................................................................................... 842 20.40.1 evaluate(state) ........................................................................................................ 843 20.40.2 G2S_PRE001 Player Device Disabled by EGM .................................................... 843 20.40.3 G2S_PRE002 Player Device Enabled by EGM ..................................................... 844 20.40.4 G2S_PRE003 Player Device Disabled by Host ..................................................... 844 20.40.5 G2S_PRE004 Player Device Enabled by Host ..................................................... 845 20.40.6 G2S_PRE005 Player Device Configuration Changed by Host .............................. 845 20.40.7 G2S_PRE006 Player Device Configuration Changed by Operator ....................... 846 20.40.8 G2S_PRE100 Session Started .............................................................................. 847 20.40.9 G2S_PRE101 Interval Rating ................................................................................ 848 20.40.10 G2S_PRE102 Hot Player Threshold Reached .................................................... 848 20.40.11 G2S_PRE103 Session Ended ............................................................................. 850 20.40.12 G2S_PRE104 Session End Acknowledged ........................................................ 851 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxix G2S™ Message Protocol v1.0.3 Table of Contents 20.40.13 G2S_PRE105 RPN Processing Failure ............................................................... 852 20.40.14 G2S_PRE106 Generic Countdown Override Set ................................................ 852 20.40.15 G2S_PRE107 Generic Countdown Override Activated ....................................... 853 20.40.16 G2S_PRE108 Player Override Set ...................................................................... 854 20.40.17 G2S_PRE109 Player Override Activated ............................................................ 855 20.40.18 G2S_PRE110 Base Countdown Activated .......................................................... 856 20.40.19 G2S_PRE111 Player Carryover Set .................................................................... 857 20.40.20 G2S_PRE112 Player Point Balance Set ............................................................. 858 20.40.21 G2S_PRE113 Host Points Set ............................................................................ 859 20.40.22 G2S_PRE114 Session Updated .......................................................................... 860 20.40.23 G2S_PRE115 Un-Carded Hot Player Level 0 ..................................................... 861 20.40.24 G2S_PRE116 Un-Carded Hot Player Level 1 ..................................................... 861 20.40.25 G2S_PRE117 Un-Carded Hot Player Level 2 ..................................................... 861 20.40.26 G2S_PRE118 Un-Carded Hot Player Level 3 ..................................................... 862 20.40.27 G2S_PRE119 Un-Carded Hot Player Level 4 ..................................................... 862 20.40.28 G2S_PRE120 Un-Carded Hot Player Level 5 ..................................................... 862 20.41 Examples ......................................................................................................................... 863 20.41.1 Player Status Commands ....................................................................................... 863 20.41.2 Player Profile Commands ....................................................................................... 865 20.41.3 Countdown Override Commands ........................................................................... 866 20.41.4 Carry Over Commands........................................................................................... 868 20.41.5 Point Balance Commands ...................................................................................... 869 20.41.6 Player Override Commands ................................................................................... 870 20.41.7 Session End Commands ........................................................................................ 871 20.41.8 Host Points Commands .......................................................................................... 872 20.41.9 Player Message Commands .................................................................................. 873 20.41.10 Player Log Status Commands .............................................................................. 874 20.41.11 Player Log Commands ......................................................................................... 875 20.42 Player Device Option Configuration ................................................................................. 876 20.42.1 20.42.2 20.42.3 20.42.4 20.42.5 20.42.6 20.42.7 20.42.8 Option Group Definitions ........................................................................................ 876 G2S Protocol Options Definitions ........................................................................... 876 G2S Protocol Option Sub-Parameter Definitions ................................................... 876 Player Option Definitions ........................................................................................ 877 Player Option Sub-Parameter Definitions............................................................... 877 Player Message Option Definitions ........................................................................ 878 Player Message Sub-Parameter Definitions........................................................... 878 Example optionItem Elements in OptionList ........................................................... 879 21 voucher Class.................................................................................................. 885 21.1 Introduction ........................................................................................................................ 885 21.2 Transaction Identifiers........................................................................................................ 885 21.3 Seeds and Validation Ids ................................................................................................... 886 21.4 Manual Authentication........................................................................................................ 887 21.4.1 Test Cases for Voucher Authentication Algorithm .................................................... 888 21.5 Transaction Logs................................................................................................................ 889 21.6 Log Sequence Numbers .................................................................................................... 890 Page xxx gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 21.7 Meters ................................................................................................................................ 890 21.8 Request-Response Pairs ................................................................................................... 891 21.9 setVoucherState Command ............................................................................................... 892 21.10 setVoucherLockOut Command ........................................................................................ 892 21.11 getVoucherStatus Command ........................................................................................... 893 21.12 voucherStatus Command................................................................................................. 893 21.13 getVoucherProfile Command ........................................................................................... 893 21.14 voucherProfile Command................................................................................................. 894 21.15 getValidationData Command ........................................................................................... 897 21.16 validationData Command................................................................................................. 898 21.17 issueVoucher Command.................................................................................................. 899 21.18 issueVoucherAck Command............................................................................................ 902 21.19 redeemVoucher Command .............................................................................................. 902 21.20 authorizeVoucher Command ........................................................................................... 903 21.21 commitVoucher Command............................................................................................... 905 21.22 commitVoucherAck Command......................................................................................... 906 21.23 getVoucherLogStatus Command ..................................................................................... 906 21.24 voucherLogStatus Command........................................................................................... 907 21.25 getVoucherLog Command ............................................................................................... 907 21.26 voucherLogList Command ............................................................................................... 908 21.27 Data Types....................................................................................................................... 911 21.27.1 21.27.2 21.27.3 21.27.4 21.27.5 21.27.6 21.27.7 voucherActions Enumerations: Voucher Action Codes .......................................... 912 hostVoucherActions Enumerations: Host Action Codes......................................... 912 egmVoucherActions Enumerations: EGM Action Codes........................................ 912 hostVoucherExceptions: Host Transfer Exception Codes ...................................... 912 egmVoucherExceptions: EGM Transfer Exception Codes ..................................... 913 voucherSources Enumerations: Voucher Source Codes ....................................... 913 voucherStates Enumerations: Voucher Transaction Status Codes........................ 913 21.28 Error Codes...................................................................................................................... 914 21.29 Event Codes..................................................................................................................... 915 21.29.1 evaluate(state) ........................................................................................................ 916 21.29.2 G2S_VCE001 Vouchers Disabled by EGM ........................................................... 916 21.29.3 G2S_VCE002 Vouchers Enabled by EGM ............................................................ 916 21.29.4 G2S_VCE003 Vouchers Disabled by Host ............................................................ 917 21.29.5 G2S_VCE004 Vouchers Enabled by Host ............................................................ 917 21.29.6 G2S_VCE005 Voucher Configuration Changed by Host ...................................... 917 21.29.7 G2S_VCE006 Voucher Configuration Changed by Operator ................................ 918 21.29.8 G2S_VCE009 EGM Locked by Voucher Host ....................................................... 918 21.29.9 G2S_VCE010 EGM Unlocked by Voucher Host ................................................... 918 21.29.10 G2S_VCE101 Validation ID Data Expired ........................................................... 919 21.29.11 G2S_VCE102 Validation ID Data Updated ......................................................... 919 21.29.12 G2S_VCE103 Voucher Issued ............................................................................ 920 21.29.13 G2S_VCE105 Voucher Issue Command Acknowledged .................................... 922 21.29.14 G2S_VCE106 Voucher Redemption Requested ................................................. 923 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxxi G2S™ Message Protocol v1.0.3 Table of Contents 21.29.15 G2S_VCE107 Voucher Authorized ..................................................................... 924 21.29.16 G2S_VCE108 Voucher Redeemed ..................................................................... 925 21.29.17 G2S_VCE109 Voucher Rejected ........................................................................ 927 21.29.18 G2S_VCE111 Voucher Commit Command Acknowledged ................................ 928 21.30 Examples ......................................................................................................................... 929 21.30.1 21.30.2 21.30.3 21.30.4 21.30.5 Voucher Device Status Commands........................................................................ 929 Voucher Device Profile Commands........................................................................ 929 Validation Data Commands .................................................................................... 929 Voucher Issuance and Redemption Commands .................................................... 930 Voucher Log Commands ........................................................................................ 932 21.31 Voucher Device Option Configuration.............................................................................. 933 21.31.1 21.31.2 21.31.3 21.31.4 21.31.5 21.31.6 21.31.7 21.31.8 Option Group Definitions ........................................................................................ 933 G2S Protocol Option Definitions............................................................................. 933 G2S Protocol Option Sub-Parameter Definitions ................................................... 933 Voucher Option Definitions ..................................................................................... 934 Voucher Option Sub-Parameter Definitions ........................................................... 934 Voucher Text Field Option Definitions .................................................................... 935 Voucher Text Field Sub-Parameter Definitions ...................................................... 935 Example optionItem Elements in OptionList ........................................................... 936 22 wat Class.......................................................................................................... 941 22.1 Introduction ........................................................................................................................ 941 22.2 Transaction Identifiers........................................................................................................ 941 22.3 Transaction Logs................................................................................................................ 941 22.4 Log Sequence Numbers .................................................................................................... 942 22.5 Meters ................................................................................................................................ 942 22.6 Wagering Accounts ............................................................................................................ 942 22.7 Transfer Overview.............................................................................................................. 943 22.8 Player Interface Mode ........................................................................................................ 943 22.9 EGM-initiated Cash-Outs ................................................................................................... 944 22.10 Suggested Transfer Procedures ...................................................................................... 945 22.10.1 EGM-Initiated Transfer to EGM in EGM-Controlled Mode ..................................... 945 22.10.2 Host-Initiated Transfer to EGM in Host-Controlled Mode (Request Sent before Player Selects Amounts)945 22.10.3 Host-Initiated Transfer to EGM in Host-Controlled Mode (Request Sent after Player Selects Amounts)946 22.10.4 EGM-Initiated Transfer to Host in EGM-Controlled Mode ...................................... 946 22.10.5 EGM-Initiated Transfer to Host in Host-Controlled Mode ....................................... 946 22.10.6 Host-Initiated Transfer to Host in Host-Controlled Mode ........................................ 946 22.11 Request-Response Pairs ................................................................................................. 947 22.12 setWatState Command .................................................................................................... 948 22.13 setWatLockOut Command ............................................................................................... 948 22.14 getWatStatus Command .................................................................................................. 948 Page xxxii gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 22.15 watStatus Command........................................................................................................ 949 22.16 getWatProfile Command .................................................................................................. 949 22.17 watProfile Command........................................................................................................ 950 22.18 getKeyPair Command ...................................................................................................... 952 22.19 keyPair Command............................................................................................................ 953 22.20 getWatAccounts Command ............................................................................................. 954 22.21 watAccountList Command ............................................................................................... 955 22.22 getWatBalance Command ............................................................................................... 957 22.23 watBalance Command ..................................................................................................... 958 22.24 setWatCashOut Command .............................................................................................. 958 22.25 initiateRequest Command................................................................................................ 959 22.26 requestPending Command .............................................................................................. 960 22.27 cancelRequest Command................................................................................................ 961 22.28 cancelRequestAck Command.......................................................................................... 961 22.29 initiateTransfer Command................................................................................................ 962 22.30 authorizeTransfer Command ........................................................................................... 964 22.31 commitTransfer Command............................................................................................... 966 22.32 commitTransferAck Command......................................................................................... 968 22.33 getWatLogStatus Command ............................................................................................ 968 22.34 watLogStatus Command.................................................................................................. 969 22.35 getWatLog Command ...................................................................................................... 969 22.36 watLogList Command ...................................................................................................... 970 22.37 Data Types....................................................................................................................... 973 22.37.1 22.37.2 22.37.3 22.37.4 22.37.5 22.37.6 22.37.7 22.37.8 interfaceModes Enumerations: Player Interface Mode Codes ............................... 973 cashOutModes Enumerations: Cash-Out Mode Codes ......................................... 974 watDirections Enumerations: WAT Direction Codes .............................................. 974 watPayMethods Enumerations: Pay Method Codes .............................................. 974 watHostExceptions Enumerations: Host Transfer Exception Codes ...................... 974 watEgmExceptions Enumerations: EGM Transfer Exception Codes ..................... 975 watStates Enumerations: WAT Transaction State Codes ...................................... 975 Reserved hashTypes Enumerations ...................................................................... 976 22.38 Error Codes...................................................................................................................... 976 22.39 Event Codes..................................................................................................................... 977 22.39.1 evaluate(state) ........................................................................................................ 978 22.39.2 G2S_WTE001 WAT Disabled by EGM ................................................................. 978 22.39.3 G2S_WTE002 WAT Enabled by EGM .................................................................. 978 22.39.4 G2S_WTE003 WAT Disabled by Host .................................................................. 979 22.39.5 G2S_WTE004 WAT Enabled by Host ................................................................... 979 22.39.6 G2S_WTE005 WAT Configuration Changed by Host ........................................... 979 22.39.7 G2S_WTE006 WAT Configuration Changed by Operator .................................... 980 22.39.8 G2S_WTE009 EGM Locked by WAT Host ........................................................... 980 22.39.9 G2S_WTE010 EGM Unlocked by WAT Host ........................................................ 980 22.39.10 G2S_WTE101 WAT Cash-Out to Host Disabled ................................................. 981 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxxiii G2S™ Message Protocol v1.0.3 Table of Contents 22.39.11 G2S_WTE102 WAT Cash-Out to Host Enabled ................................................. 981 22.39.12 G2S_WTE103 WAT Transfer Requested by Host .............................................. 982 22.39.13 G2S_WTE104 WAT Transfer Cancel Requested by Host .................................. 983 22.39.14 G2S_WTE105 WAT Transfer Initiated ................................................................ 984 22.39.15 G2S_WTE106 WAT Transfer Authorized ............................................................ 986 22.39.16 G2S_WTE107 WAT Transfer Completed ............................................................ 987 22.39.17 G2S_WTE108 WAT Commit Command Acknowledged ..................................... 990 22.39.18 G2S_WTE109 New Key Pair Established ........................................................... 991 22.39.19 G2S_WTE110 New Key Pair Failed – Invalid Key Value .................................... 991 22.40 Examples ......................................................................................................................... 992 22.40.1 22.40.2 22.40.3 22.40.4 22.40.5 22.40.6 WAT Device Status Commands ............................................................................. 992 WAT Device Profile Commands ............................................................................. 992 Host-Initiated Transfer to EGM in Host-Controlled Mode ....................................... 992 EGM-Initiated Transfer to Host in Host-Controlled Mode ....................................... 996 EGM-Initiated Transfer to EGM in EGM-Controlled Mode ..................................... 998 WAT Log Commands ........................................................................................... 1000 22.41 WAT Device Option Configuration ................................................................................. 1001 22.41.1 22.41.2 22.41.3 22.41.4 22.41.5 22.41.6 Option Group Definitions ...................................................................................... 1001 G2S Protocol Option Definitions........................................................................... 1001 G2S Protocol Option Sub-Parameter Definitions ................................................. 1001 WAT Option Definitions ........................................................................................ 1002 WAT Option Sub-Parameter Definitions ............................................................... 1002 Example optionItem Elements in OptionList ......................................................... 1003 23 gat Class ........................................................................................................ 1007 23.1 Introduction ...................................................................................................................... 1007 23.1.1 23.1.2 23.1.3 23.1.4 23.1.5 23.1.6 Regulatory Requirements ....................................................................................... 1007 History .................................................................................................................... 1008 Special Functions ................................................................................................... 1009 GAT Security .......................................................................................................... 1013 Use Cases .............................................................................................................. 1014 GAT and Modules and Components ...................................................................... 1017 23.2 Transaction Logs.............................................................................................................. 1018 23.3 Log Sequence Numbers .................................................................................................. 1018 23.4 Meters .............................................................................................................................. 1018 23.5 Request-Response Pairs ................................................................................................. 1019 23.6 getGatProfile Command................................................................................................... 1020 23.7 gatProfile Command ........................................................................................................ 1020 23.8 getComponentList Command .......................................................................................... 1021 23.9 componentList Command ................................................................................................ 1021 23.10 doVerification Command................................................................................................ 1023 23.11 getVerificationStatus Command..................................................................................... 1024 23.12 verificationStatus Command .......................................................................................... 1025 23.13 verificationResult Command .......................................................................................... 1026 Page xxxiv gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Table of Contents 23.14 verificationResultAck Command .................................................................................... 1027 23.15 getSpecialFunctions Command ..................................................................................... 1027 23.16 specialFunctions Command........................................................................................... 1028 23.17 runSpecialFunction Command....................................................................................... 1029 23.18 specialFunctionResult Command .................................................................................. 1029 23.19 getGatLogStatus Command........................................................................................... 1030 23.20 gatLogStatus Command ................................................................................................ 1030 23.21 getGatLog Command..................................................................................................... 1031 23.22 gatLogList Command ..................................................................................................... 1032 23.23 Data Types..................................................................................................................... 1034 23.23.1 Reserved componentTypes Enumerations .......................................................... 1035 23.23.2 Reserved algorithmTypes Enumerations ............................................................. 1035 23.24 Error Codes.................................................................................................................... 1036 23.25 Event Codes................................................................................................................... 1037 23.25.1 G2S_GAE005 Device Configuration Changed by Host ....................................... 1038 23.25.2 G2S_GAE006 Device Configuration Changed by Operator ................................ 1038 23.25.3 G2S_GAE101 Verification Queued ..................................................................... 1039 23.25.4 G2S_GAE102 Verification Started ...................................................................... 1040 23.25.5 G2S_GAE103 Verification Complete ................................................................... 1041 23.25.6 G2S_GAE104 Verification Error .......................................................................... 1042 23.25.7 G2S_GAE105 Verification Result Acknowledged and Passed ........................... 1043 23.25.8 G2S_GAE106 Verification Result Acknowledged and Failed .............................. 1044 23.25.9 G2S_GAE107 Special Function Executed .......................................................... 1045 23.26 Examples ....................................................................................................................... 1046 23.26.1 23.26.2 23.26.3 23.26.4 23.26.5 Get Component List Command Sequence ........................................................... 1046 Component Verification Command Sequence ..................................................... 1047 Get Special Functions Command Sequence........................................................ 1049 Run Special Function Command Sequence......................................................... 1050 gat Log Retrieval Command Sequence................................................................ 1051 23.27 GAT Device Option Configuration.................................................................................. 1052 23.27.1 23.27.2 23.27.3 23.27.4 Option Group Definitions ...................................................................................... 1052 G2S Protocol Option Definitions........................................................................... 1052 G2S Protocol Option Sub-Parameter Definitions ................................................. 1052 Example optionItem Elements in OptionList ......................................................... 1053 24 central Class .................................................................................................. 1055 24.1 Introduction ...................................................................................................................... 1055 24.2 Definition of Central Determination .................................................................................. 1055 24.3 Configuration Management.............................................................................................. 1055 24.3.1 Single-Line 3-Reel Game, Example 1 .................................................................... 1057 24.3.2 Single Line 3 Reel Game, Example 2..................................................................... 1057 24.4 Game Resolution and Outcome Display .......................................................................... 1058 24.4.1 outcomeReference Attribute ................................................................................... 1058 24.4.2 outcomeType Attribute ........................................................................................... 1058 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxxv G2S™ Message Protocol v1.0.3 Table of Contents 24.4.3 winLevelIndex Attribute .......................................................................................... 1058 24.4.4 Identifying Finite Deals ........................................................................................... 1059 24.5 Relationship of Central Devices to Game Play Devices .................................................. 1059 24.6 Event Coordination between Game Play and Central devices ........................................ 1060 24.7 Transaction Logs.............................................................................................................. 1061 24.8 Log Sequence Numbers .................................................................................................. 1061 24.9 Meters .............................................................................................................................. 1061 24.10 Request-Response Pairs ............................................................................................... 1062 24.11 setCentralState Command............................................................................................. 1063 24.12 getCentralStatus Command........................................................................................... 1063 24.13 centralStatus Command................................................................................................. 1063 24.14 getCentralProfile Command........................................................................................... 1064 24.15 centralProfile Command................................................................................................. 1064 24.16 getCentralOutcome Command ...................................................................................... 1065 24.16.1 EGM Timeout ....................................................................................................... 1065 24.17 centralOutcome Command ............................................................................................ 1066 24.18 commitOutcome Command ........................................................................................... 1067 24.19 commitOutcomeAck Command ..................................................................................... 1068 24.20 getCentralLogStatus Command..................................................................................... 1068 24.21 centralLogStatus Command........................................................................................... 1068 24.22 getCentralLog Command ............................................................................................... 1069 24.23 centralLogList Command ............................................................................................... 1069 24.24 Data Types..................................................................................................................... 1072 24.24.1 outcomeExceptions Enumerations ....................................................................... 1072 24.25 Error Codes.................................................................................................................... 1073 24.26 Event Codes................................................................................................................... 1074 24.26.1 evaluate(state) ...................................................................................................... 1075 24.26.2 G2S_CLE001 Central Device Disabled by EGM ................................................. 1075 24.26.3 G2S_CLE002 Central Device Enabled by EGM .................................................. 1075 24.26.4 G2S_CLE003 Central Device Disabled by Host .................................................. 1076 24.26.5 G2S_CLE004 Central Device Enabled by Host .................................................. 1076 24.26.6 G2S_CLE005 Central Device Configuration Changed by Host ........................... 1076 24.26.7 G2S_CLE006 Central Device Configuration Changed by Operator .................... 1077 24.26.8 G2S_CLE101 Central Device Outcome Requested ............................................ 1077 24.26.9 G2S_CLE102 Central Device Outcome Failure .................................................. 1078 24.26.10 G2S_CLE103 Central Device Outcome Received ............................................ 1079 24.26.11 G2S_CLE104 Central Device Outcome Committed .......................................... 1080 24.27 Examples ....................................................................................................................... 1081 24.27.1 24.27.2 24.27.3 24.27.4 Status Commands ................................................................................................ 1081 Profile Commands ................................................................................................ 1081 Outcome Commands............................................................................................ 1082 Log Commands .................................................................................................... 1083 24.28 Central Device Option Configuration.............................................................................. 1085 Page xxxvi gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 24.28.1 24.28.2 24.28.3 24.28.4 24.28.5 24.28.6 Table of Contents Option Group Definitions ...................................................................................... 1085 G2S Protocol Option Definitions........................................................................... 1085 G2S Protocol Option Sub-Parameter Definitions ................................................. 1085 Game Play Device List Option Definitions ............................................................ 1086 Central Option Sub-Parameter Definitions ........................................................... 1086 Example optionItem Elements in OptionList ......................................................... 1087 A Global Data Types ......................................................................................... 1091 A.1 applyConditions Enumerations .......................................................................................... 1094 A.2 authorizationStates Enumerations..................................................................................... 1094 A.3 disableConditions Enumerations ....................................................................................... 1094 A.4 idReaderTypes: Reserved Enumerations.......................................................................... 1095 A.5 deviceClass: Reserved Enumerations............................................................................... 1095 A.6 creditTypes Enumerations ................................................................................................. 1096 A.7 idRestricts Enumerations: Identification Restrictions......................................................... 1096 A.8 timeoutActionType Enumerations...................................................................................... 1096 B Balancing The G2S Meter Model .................................................................. 1097 B.1 Introduction ........................................................................................................................ 1097 B.2 Player Buy-In ..................................................................................................................... 1099 B.2.1 Player puts a currency into the EGM. ...................................................................... 1099 B.2.2 Player puts a voucher into the EGM or makes a transfer from a WAT account. ..... 1099 B.3 Player Cash-Out ................................................................................................................ 1100 B.3.1 Player cashes out – EGM dispenses currency. ....................................................... 1100 B.3.2 Player cashes out – EGM generates a handpay...................................................... 1100 B.3.3 Player cashes out – EGM generates a voucher or makes a WAT transfer.............. 1101 B.4 Primary Game Wagers ...................................................................................................... 1102 B.4.1 Player initiates game play and makes wagers on a game. ...................................... 1102 B.5 Game Outcome ................................................................................................................. 1103 B.5.1 Game Outcome In Detail (for Demonstration Purposes Only) ................................. 1103 B.5.2 Game Outcome In Aggregate .................................................................................. 1106 B.5.3 Bonuses ................................................................................................................... 1107 B.6 Balancing The EGM In Total.............................................................................................. 1110 B.7 Balancing The EGM by Credit Type .................................................................................. 1111 B.8 Reconciliations................................................................................................................... 1112 C Standard XML Data Types ............................................................................ 1115 D Reverse Polish Notation (RPN) .................................................................... 1117 D.1 Introduction........................................................................................................................ 1117 D.2 Grammar ........................................................................................................................... 1117 D.3 Performance Meter Names ............................................................................................... 1118 D.4 Syntax Rules ..................................................................................................................... 1118 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxxvii G2S™ Message Protocol v1.0.3 Table of Contents D.5 Test Cases ........................................................................................................................ 1119 D.6 Error Handling ................................................................................................................... 1119 E Minimum Display Requirements .................................................................. 1121 E.1 ASCII Character Support ................................................................................................... 1121 E.2 Substitution Tokens ........................................................................................................... 1122 F G2S Event Summary ...................................................................................... 1123 G G2S_CRC16 and G2S_CRC32 Algorithms .................................................. 1135 H Handpay Flow ................................................................................................ 1137 I Nevada Required Meters vs. G2S Meters ...................................................... 1139 Index of Elements and Attributes ................................................................... 1141 Index of Subjects .............................................................................................. 1177 Page xxxviii gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 I About This Document About This Document This section is an overview of the G2S protocol and this document. It includes a description of the purpose and benefits of the protocol. See Document Conventions and Organization, on page xlii, for an explanation of the conventions used in this document and the document organization. I.I Goals and Benefits of the GSA G2S Message Protocol The G2S (Game to System) protocol provides a messaging standard, using XML version 1.0, for communications between gaming devices (such as game software, meters, and hoppers) and gaming management systems (such as progressives, cashless, and accounting). The acceptance, implementation, widespread deployment, change management, and future technological advancements to GSA’s G2S protocol will allow the gaming industry to concentrate on the creation of innovative, appealing gaming products and operations. The G2S protocol will employ standards and technologies from the computer industry, including but not limited to TCP, SSL, fully formed XML, and other IP protocols for the primary protocol, and physical transport technologies, including but not limited to Ethernet and other IP transport mechanisms. Where practical, the G2S protocol will also accommodate other computer industry standards such as streaming audio and video on the physical transport layer. Using proven technologies will enable GSA to provide reliable products quickly to the industry at a significant savings to manufacturers, operators, and regulators. I.II G2S Compliance I.II.I XML 1.0 and XSD 1.0 To be G2S compliant, G2S implementations must conform to XML 1.0 and XML Schema (XSD) 1.0. For more information, visit: • XML 1.0: http://www.w3.org/XML/. • XSD 1.0: http://www.w3.org/XML/Schema/. I.II.II Required and Optional Functionality Definition of the required and optional functionality within the G2S protocol is currently under development. These definitions will frame the requirements for products to be certified as compliant with the G2S protocol. When defined, at minimum, a product will need to support at least the required classes/functionality in order to become certified as G2S compliant. Support for the remaining classes/functionality will be optional. Products may also be certified as compliant in optional classes/functionality. Optional classes are divided into two categories: administrative and application. Administrative classes are those that systems use to perform administrative functions, such as configuration and download. These classes provide useful alternatives to their manual counterparts, allowing configuration of EGMs to be automated and performed remotely rather than on site, one-by-one, and manually. Application classes are those that define specific operational functionality, such as those to support progressives, bonusing, and vouchers. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xxxix G2S™ Message Protocol v1.0.3 I.III About This Document Term Definitions The following are terms and acronyms used in this document. active 1. An EGM that is enabled and playable, in which all devices identified as being required for play are enabled both by the host and the EGM. 2. A device that is assigned to an owner during configuration and is permitted, when enabled, to perform its intended functions. Information can be requested and sent only for active devices. 3. A game combination that is accessible to a player and can be played. administrative class An optional G2S class of commands used to perform administrative functions, such as configuration and download. These classes provide useful alternatives to their manual counterparts, allowing configuration of EGMs to be automated and performed remotely rather than onsite, oneby-one, and manually. application class An optional G2S class of commands that define a specific operational functionality, such progressives, bonusing, and vouchers. camel-case Style of the G2S naming convention. Attribute and element names must begin with a lower-case letter and thereafter, each new word is capitalized. Examples: g2sMessage, getMeterInfo. core class A G2S class of commands that MUST be supported in order to be considered as meeting the minimum requirements for compliance with the standard. data set A defined set of data, such as meter data, or transaction log data, or device status data. In the context of event handling, data sets are associated with the time an event is sent. EGM Electronic Gaming Machine, such as a slot or video machine. EOD End of Day. force Indicates an action made through a configuration server or manually at an EGM. Used in reference to event subscriptions. G2S Game to System. game combo A game combination. One theme, one paytable, and one denomination. guest A registered host system that may subscribe to events and meters of an EGM’s devices, but that does not control the device. There can be multiple guest hosts to a device. A host can be the owner of one device, and a guest of other devices. See also owner and registered host. join To add one of the devices of an EGM to the list of recipients in a defined multicast group. See also multicast. multicast Method of communications in which communications are directed from a single host to a multicast group (a group of one or more devices, see join). NVM Non-volatile memory. Page xl gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 About This Document operator 1. The establishment within which G2S hosts and EGMs are operated. 2. An individual in the establishment. Often used when indicating actions taken physically by a person at the EGM, such as manual configuration. optional class A G2S class of commands that is not a core class and not required to be implemented to be considered as meeting the minimum requirements for compliance with the standard. originator The entity, typically an EGM or host, that originates (generates) a message. owner The registered host system that is allowed to write to a device and controls the device. There can be only one owner of a device. par-sheet Paytable definition, percentages contributed, withheld, etc. point-to-point Method of communications in which communication takes place between a single host and a single EGM. profile The theme, paytable, and wager categories of a gamePlay device. registered host A host from which an EGM can receive commands. The list of registered hosts can be configured in the EGM manually or through a configuration server. secondary game A game in which the winnings that resulted from the primary game can be wagered, won, and lost, such as a double-or-nothing game where winnings from the primary game can be wagered and doubled or lost entirely. wildcard Characters used to indicate all instances of a particular group, rather than a particular instance, such as using G2S_all to indicate all meters or -1 to indicate all devices. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xli G2S™ Message Protocol v1.0.3 About This Document I.IV Document Conventions and Organization I.IV.I Indicating Requirements, Recommendations, and Options Terms and phrases in this document that indicate requirements, recommendations, and options in the G2S Message Protocol are used as defined in the IETF RFC 2119. In summary: to indicate requirements, this document uses "MUST", "MUST NOT", "REQUIRED", "SHALL", or "SHALL NOT". to indicate recommendations, this document uses "SHOULD", "SHOULD NOT", "RECOMMENDED". to indicate options, this document uses "MAY" or "OPTIONAL". I.IV.II Abbreviations and Labels Used in Tables Element, attribute, and data type descriptions in this document appear in three-column tables. The following abbreviations and labels appear in the Restrictions columns. Abbreviation/Label Description default: <empty> A documentation standard used in certain cases to specify a string value with a length of 0 (zero) characters. default: <null> A documentation standard used in certain cases to specify a value of default:<null> when no default value exists for an optional attribute. This implies that no default value will exist in the schema, and therefore the optional attribute has no default value assigned to it by the host or EGM processing the message. For example, this is used throughout the documentation when an attribute of type xs:dateTime is optional. length Total number of characters allowed. minIncl/maxIncl Minimum and maximum inclusive values, such as 1 through 99, including the values 1 and 99. minLen/maxLen Minimum and maximum number of characters allowed. minOcc/maxOcc Minimum and maximum number of allowable instances. type Data type of the element or attribute being described. I.IV.III Graphical Conventions Graphical representations of G2S elements are included throughout the chapters to give a quick visual description of the contents of the element being described in a particular section, such as a class element at the beginning of a chapter, and in later sections, the command elements. This section describes the various symbols that appear in the graphical element representations. Each element is represented by a single rectangle or two overlapping rectangles that contain the element name. A single rectangle with a solid outline indicates an element that is required and should occur one time. A rectangle that includes a plus symbol (+) on the right side indicates a complex Page xlii gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 About This Document element that has child elements. In the example below, the element g2sMessage is shown, which contains a choice of three elements, g2sBody, g2sAck, or g2sMulticast. Optional child elements are indicated by rectangles with dotted outlines. In the example element on the following page, this means that only one category of meters may be requested or meters in all categories may be requested. Multiple instances of some elements may be allowed, such as each of the getMeterInfo child elements. Two overlapping rectangles indicate multiple instances are allowed. When multiple instances are allowed, the minimum and maximum number of times the element can occur are shown below the rectangles, to the right. getMeterInfo gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page xliii G2S™ Message Protocol v1.0.3 I.IV.IV About This Document Document Organization I.IV.IV.I Command Classes and Chapter Order As noted previously in G2S Compliance, after Chapter 1 which describes the G2S message envelope, the remaining chapters describe core or optional classes as defined in G2S certification requirements. A number of data types defined in the G2S protocol can be used globally. These are defined in Appendix A. For your convenience, the XML standard data types used in the G2S Message Protocol, such as string and integer, are listed in Appendix C. This appendix refers you to the XML 1.0 standard, found at www.w3.org, for the data type definitions. I.IV.IV.II Structure of Command Class Chapters Each chapter that describe a command class in the G2S protocol is structured as follows: 1. Description of the class. 2. Summary of commands in the class. This summary includes a graphical representation of the first level of child elements (the commands) in the class element. See page xlii for a description of the graphical conventions. 3. Request-response pair tables. These tables show commands originated by EGMs and responses if applicable, and commands originated by hosts with responses if applicable. In tables defining commands originated by hosts, whether owners or guests or both may originate a command is also indicated. 4. Sections for each command in the class. If a command element contains complex content, the information is presented in the following order: a. Command attributes, if any. b. Command child elements, if any. Elements that are used by more than one command are described in detail only once in the class chapter, at first mention. c. Child element attributes, if any. d. Child elements of the elements in b. e. and so on.... 5. Class data types. 6. Class error and event codes. 7. Sample messages. 8. State and Sequence diagrams, in some cases, such as the WAT class. 9. Additional information. I.V Acknowledgements The Gaming Standards Association would like to express its appreciation to all members of the G2S committee, past and present, for their significant contribution and dedication to the creation of this standard. Page xliv gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1 Chapter 1 g2sMessage g2sMessage In addition to this document, an XML Schema defines the syntax for the G2S Message Protocol. The XML Schema also defines semantic information such as default values. This document supplements the XML Schema, defining additional requirements and semantics. A valid g2sMessage meets all the requirements of the XML Schema and all the requirements of this document. For compatibility with validating implementations based on the XML Schema, the syntax defined in the XML Schema has precedence. 1.1 Introduction The Game-to-System, or G2S, protocol is designed to communicate information between an electronic gaming machine, or EGM, and one or more host systems. G2S is designed to minimize the interference of these communication activities with actual game play. This goal has been achieved by separating the delivery of messages from the processing of their contents. Within the G2S protocol, this is referred to as asynchronous behavior. The G2S protocol operates at two levels; the message level and the application level. The message level is responsible for transmitting and receiving messages between an EGM and one or more hosts. A message may contain one or more application-level commands. An application-level command is sent from an EGM to a host, or vice versa, to initiate an action or to report the results of an action. The act of receiving a message is not bound to the act of executing a command contained within the message. The message level only guarantees that a message has been delivered; it does not guarantee that a command within the message is ever executed. The application level is responsible for the execution of commands, including retry and recovery. A command may be executed at any time subsequent to its delivery. At the application-level, many commands require responses. The responses to these requests are returned to the originator of the request in messages that are independent from the messages that contained the requests. There is no relationship between a message containing a request command and the message that contains the response. In fact, responses may be sent on independent communication channels. Matching of requests to responses is performed at the application-level. At the message level, there is no requirement that the recipient of a message persist any of the commands contained within the message or that the recipient actually ever process the commands. Asynchronous application-level acknowledgements are used to confirm that commands have been processed. Retry and recovery mechanisms at the application level are used to guarantee that commands are delivered and processed. 1.2 XML Version 1.0 and XML Schema (XSD) Version 1.0 To be compliant with the G2S protocol, G2S implementations MUST conform to: • XML version 1.0 and • XML Schema version 1.0. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 1 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.3 Transport Requirements The G2S message protocol is designed so that it can be used with various different transport mechanisms. The protocol itself does not require a specific transport mechanism; however, it does impose the following requirements on the transport mechanisms used with the message protocol. First, the transport MUST be able to deliver XML 1.0 messages. All messages within the G2S protocol are constructed using XML 1.0. Second, the transport MUST provide secure point-to-point and secure multicast services. These services MAY be provided by the same transport mechanism or separate transport mechanisms. G2S assumes that a secure association exists between the end-points and that the association has been authenticated, authorized and provides message integrity and confidentiality. Third, for point-to-point messages, the transport MUST guarantee that messages are received in the order that they are sent. If a sender generates two messages, for example message A then message B, the transport MUST guarantee that message A is received before message B. Any duplicate messages introduced by the transport MUST NOT be presented to the G2S message level. The transport MUST present each message once and only once. Any inability to deliver messages in order MUST be reported as a transport failure by the transport mechanism. Following a transport failure, any transport connections or associations that may have been established with respect to the failed message stream MUST be aborted. This MAY cause the G2S application level to report a communication failure. The application level MAY attempt to establish a new transport connection or association to replace the failed one. Fourth, for point-to-point messages, the transport MUST provide a mechanism for delivering responses from the recipient of a message back to the sender. The transport MUST provide a mechanism for the recipient of a message to send message-level acknowledgements and errors back to the originator of a message. The transport MUST guarantee that such responses are sent in the same order in which the original messages were received and that the responses are delivered in the same order as sent. Message-level acknowledgements and errors do not contain any information that allows either to be correlated with the original message. Fifth, for multicast messages, the transport MUST guarantee that messages are delivered in the order sent; however, omissions MAY occur. The G2S multicast delivery service is an unacknowledged besteffort service. Any duplicate messages introduced by the transport MUST NOT be presented to the G2S message level. The transport MUST present each message once and only once. These requirements may be fulfilled by a variety of transports. The Transport Committee of the Gaming Standards Association is responsible for identifying and publishing such transports and approving them for use with the G2S protocol. Page 2 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1.4 Chapter 1 g2sMessage Point-to-Point Message Handling The G2S point-to-point message delivery service is an acknowledged message protocol. Each message is acknowledged by the recipient. There are no equivalent message-level acknowledgements for the G2S multicast message delivery service. When the G2S point-to-point message delivery service is used, a g2sAck response message acknowledges that the commands within a g2sBody message were received. The response simply acknowledges that the message and the commands contained within the message have been received. It does not indicate whether or when the recipient will process the commands. Processing of commands takes place at the application level. At a minimum, the egmId and hostId attributes contained within the g2sBody element MUST be validated. Optionally, before an acknowledgement is sent, the message MAY be checked to ensure that it is well-formed XML 1.0 and the message MAY be validated against one or more XML schemas. If errors are detected, the errors MUST be reported to the originator of the message using the errorCode and errorText attributes of the g2sAck element. This subject is discussed in more detail in Section 1.18.1 g2sBody Element. 1.5 Application-Level Message Handling Since the message-level protocol only guarantees that a command is delivered, any requirement that a command is actually processed by the recipient is handled at the application level. When there is such a requirement, asynchronous application-level responses are sent by the recipient of a command back to the originator. This application-level response is sent in a new message-level message that is originated by the recipient of the original command. Within the G2S protocol, these application-level responses take the form of commands. Application-level requests and responses share the same command structure. An attribute within the command structure indicates whether a command is a request, response or notification (see Section 1.18.3.2). The G2S protocol includes application-level responses for all requests and, thus, provides a mechanism that can be used to guarantee that all commands are processed. However, the protocol does not require that application-level responses be used. The originator of a command may elect to send the command as a request that requires a response. Alternatively, the originator of a command can elect to send the command as a notification that will not result in a response. When a request is received, a response MUST be sent to acknowledge that the command was processed. When a notification is received, the recipient MUST NOT send an application-level response. The following example highlights the behavior expected from the G2S protocol (see also Figure 1.1): 1. At the application level, the host generates a command to change the game that is currently available for play. 2. At the message level, the host sends a message to the EGM containing the command. 3. At the message level, the EGM sends an acknowledgement that it has received the message, queuing the command for later application-level processing. 4. At the application level, when appropriate, the EGM processes the command, changing the game currently available for play and generating an event command that announces that the new game is currently available for play. 5. At the message level, the EGM sends a message to the host containing the event command. 6. At the message level, the host sends an acknowledgement that it has received the message, queuing the command for later application-level processing. 7. At the application level, the host processes the command, updating its database to reflect that the new game is currently available for play at the EGM. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 3 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 The following is a graphical representation of the process described above for G2S message handling. EGM HOST Application level Message level Message level 2 Send message Queue commands 3 Dequeue commands Acknowledge message 1 Change game Game changed 4 5 Queue commands Send message 6 Acknowledge message Dequeue commands 7 Application level Update game status Figure 1.1 Message Handling Page 4 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1.6 Chapter 1 g2sMessage Classes & Devices The application-level commands are organized into classes. In general, these classes relate to specific functions or features of the EGM, i.e. meters, cabinet, jackpots, progressives, vouchers, etc. Some classes support physical devices such as coin acceptors, note acceptors, printers, etc. Other classes support logical devices such as games, handpays, vouchers, progressives, etc. At a minimum, an EGM MUST support the core classes as defined in G2S certification requirements. The EGM MAY support additional optional classes, categorized as administrative and application classes, depending on its exact capabilities. The protocol supports but does not require the optional classes. Within the G2S protocol, in general, a class itself is not directly addressable, just devices within the class. A class defines the set of commands and behavior of devices within the class. Devices can be viewed as instantiations of a class. For example, the gamePlay class defines the commands and behavior of actual games. Each game within an EGM is a separate device within that class. All classes can support multiple devices. However, for practical reasons, some classes may only support one active device at a time. This subject is discussed is more detail on a class-by-class basis. All commands are directed at specific devices. There are no commands that are directed at the EGM itself. The EGM simply acts as a container for a set of devices. The devices embody the features and functions of the EGM. Thus, all commands reference the EGM, the class of a device, and the device itself. 1.6.1 Device Structure An EGM MUST persist the device structure exposed to host systems. Following an outage, the devices exposed to host systems before the outage MUST be the same as the devices exposed to host systems after the outage. The device identifiers assigned before the outage must be the same as the device identifiers assigned after the outage. New devices added during the outage MUST be assigned new device identifiers and MUST also be exposed following the outage. The EGM MUST persist the device identifiers and MUST assign the same device identifiers to each device in every subsequent connection. There may be commands in flight. If the device structure was changed following an outage, those commands might not be routed to or reference the correct device. In addition to the device structure, an EGM MUST persist all critical protocol-related data, including configurations, meters and transaction logs associated with a device, so that, following an outage, the EGM may return to the same state that it was in prior to the outage. When recovering from an outage, the EGM MUST use the configuration that was in place prior to the outage. That configuration may return the EGM to the exact state it was in prior to the outage. Alternatively, the configuration may specify that the EGM enter another state. For example, the configuration may specify that a host must enable the EGM before game play may resume or that the EGM return to its default configuration. 1.6.1.1 Adding Devices The G2S protocol anticipates that, over time, new devices may be added to an EGM and obsolete devices may be removed. When new devices are added, the EGM MUST allocate persistent memory to those devices. When obsolete devices are removed, the persistent memory may be recovered. During this process, the EGM MUST ensure that unique device identifiers (see also Section 1.8) are assigned to each new device. In general, device identifiers MUST never be reused. A new device identifier MUST be assigned to each new device added to the EGM. However, in certain cases, when a new device replaces an old device, e.g. a coin acceptor is replaced, and the functionality of the new device is identical to the old device, the EGM may treat the new device as if it was the old device, reusing the old device identifier. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 5 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.7 Multiple Hosts The G2S protocol allows an EGM to communicate with multiple host systems. The list of hosts with which an EGM may communicate using the G2S protocol is part of the EGM’s initial configuration information. The configuration may be set locally at the EGM or remotely using a G2S configuration server. An EGM MUST NOT communicate using the G2S protocol, except to the hosts as configured within this list. 1.7.1 Owners, Foreign Owners, and Guests In addition to the list of permitted hosts, the EGM’s initial configuration identifies which host owns — that is, may write to and control — each of its logical and physical devices. To avoid conflicting instructions, certain application-level commands can only be performed by a single host identified as the owner of the device. As noted above, all commands are directed at a device within the EGM. Only the designated owner of the device can perform the commands restricted to owners. Other commands may be open to all permitted hosts as guests. The list of commands for a class and the ownership restrictions are provided with the description of each class. See also Sections 1.9.1 and 1.9.2 for more information about owner and guest hosts. The design of the G2S protocol requires that each device have an owner. However, the owner does not have to be a host that communicates using the G2S protocol. The owner may be using a protocol other than G2S, such as SAS, or the owner may be the EGM itself, such as a stand-alone progressive. Within this document, hosts communicating with the G2S protocol are referred to as G2S hosts. Hosts using a protocol other than G2S are referred to as foreign hosts. Devices owned by a foreign host are described as foreign-owned. Devices owned by the EGM are described as EGM-owned. 1.7.2 Registered hostIds G2S hosts MUST be registered in the EGM and MUST be assigned a host identifier (see Section 1.10 for more information on host identifiers). The EGM MUST NOT use the G2S protocol to communicate with unregistered G2S hosts. The EGM MAY contain EGM-owned and foreign-owned devices that are not exposed through the G2S protocol. Operational, jurisdictional and certification requirements will dictate when an EGM-owned or foreign-owned device MUST be exposed through the G2S protocol. It is recommended that, at a minimum, all devices that can affect the EGM’s meters be exposed through the G2S protocol. Host identifier 0 (zero) is used for EGM-owned and foreign-owned devices. By convention, host identifier 0 (zero) MUST always be contained in the list of registered hosts. Host identifiers for G2S hosts MUST be integer values greater than 0 (zero). 1.7.3 Devices Foreign Hosts Cannot Own Since foreign hosts use protocols other than G2S to communicate with the devices that they own and all communications between an EGM and an EGM-owned device are internal to the EGM, foreign hosts and the EGM itself MUST NOT own devices in the communications, eventHandler, meters and optionConfig classes (event handler and meters devices are used to manage the delivery of events and meters to G2S hosts via communications devices; option configuration devices are used to remotely set options for G2S-controlled devices.). Likewise, the commConfig class, which is used to configure communications parameters, device ownership and guest permissions for G2S hosts and the EGM itself, MUST NOT be owned by a foreign host. Only G2S hosts and the EGM itself are included in the host list exposed by the commConfig class – foreign hosts are not. Communications and device ownership for foreign hosts is outside the scope of the G2S protocol. The ownership of foreign-owned devices is exposed through the G2S protocol, but cannot be changed through the protocol. Only G2S hosts may own devices within the communications, eventHandler, meters, optionConfig and commConfig classes – foreign hosts and the EGM itself may not. Devices in all other classes may be owned by G2S hosts, foreign hosts or the EGM itself. Page 6 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1.7.4 Chapter 1 g2sMessage Functional Requirements Dependent on Owner To the extent permitted to meet operational and jurisdictional requirements, devices owned by G2S hosts MUST support the full range of functionality described by the G2S protocol. In general, this functionality includes meters, events, transaction logs, device statuses and device profiles. Foreign-owned and EGM-owned devices are not required to support the same level of functionality as G2Sowned devices. At a minimum, foreign-owned devices (when they are required to be exposed through the G2S protocol) and EGM-owned devices MUST be capable of reporting meters through the meters devices of G2S hosts and reporting events through the event handler devices of G2S hosts. In addition, device descriptors for foreign-owned and EGM-owned devices MUST be exposed through the communications devices of G2S hosts. Additional support for transaction logs, device statuses, device profiles, and other functionality MAY be required to meet operational, jurisdictional or certification requirements. For any commands that the EGM does not support, it MUST return error code G2S_APX008 Command Not Supported. A G2S host may determine the complete list of devices contained within the EGM by requesting the device descriptor list through its communications device. This list contains devices owned by G2S hosts as well as devices owned by foreign hosts and the EGM itself. When a device is owned by the EGM or a foreign host, the ownerId of the device descriptor is set to 0 (zero). For G2S-owned devices, the ownerId of the device descriptor is set to the host identifier of the G2S host that owns the device. Each G2S host MUST own a device within the communications, eventHandler and meters classes. Each G2S host may also own devices in other host-oriented classes, such as optionConfig and gat. By definition, the device identifier of these devices is the host identifier of the G2S host that owns the device. Foreign hosts and the EGM itself do not own devices within those classes. 1.8 Device Identifiers Via the G2S protocol, you can discover the devices contained within an EGM. Each device within an EGM is given a unique device identifier, deviceId, by the EGM. The G2S protocol uses this identifier to uniquely address each specific device within an EGM. This is crucial because an EGM may contain multiple instances of a single type of device. Thus, whenever a command is sent to an EGM, both the EGM identifier and the device identifier MUST be referenced. Every point-to-point command sent to/from an EGM MUST include the egmId and the deviceId. Every multicast command sent to an EGM MUST include the multicastId. The multicastId is associated with specific EGMs and devices. The device identifier, deviceId, is only unique within its class. Each class independently manages the assignment of deviceIds to devices within the class. Device identifiers MUST be positive integer values. Device identifier 0 (zero) is reserved for class-level commands. By convention, device identifier –1 (negative one) is used in certain commands to request all active devices. Once a device identifier has been assigned to a device, the EGM MUST persist the association between the device and the device identifier, using the same device identifier for the same device each time the EGM restarts. If persistent memory is cleared, causing the associations between devices and device identifiers to be lost, the EGM MUST set the deviceReset attribute of the commsOnLine command to true. At this time, the EGM may assign new device identifiers. When a host receives such a command, the host MUST assume that the associations between devices and device identifiers have changed and that the meters associated with devices may have been lost. In such a case, it is recommended that the host treat the EGM as if it were a new EGM, creating a new instance for the EGM. 1.8.1 Adding Devices Whenever a new device is added to an EGM or an old device is removed, the EGM MUST notify each host by setting the deviceChanged attribute of the commsOnLine command to true. The deviceChanged attribute gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 7 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 alerts the host that there were additions or deletions to the device structure of the EGM. In this case, it is recommended that the host review the device structure of the EGM and reset its meter and event subscriptions as necessary. See Chapter 2, for more information about the commsOnline command. 1.9 Device Subscriptions Prior to initiating communications with the host systems, the EGM is assigned a communications address. It is also given the communications addresses of the host systems. At a minimum, this information can be keyed directly into the EGM. Alternatively, the information can be obtained from a G2S configuration server. For security, an EGM will only accept commands from host systems that have been so configured. An EGM MUST NOT establish communications with hosts that are not in its list of registered hosts. Host authentication is dependent on the G2S transport protocol used. Host authentication is performed within the G2S transport layer. For the purposes of the G2S message protocol, it is assumed that the hosts have been authenticated and the host identifiers and communication addresses specified within the messages are valid. 1.9.1 Device Owner For the purposes of the G2S protocol, the EGM is organized into devices, such as cabinets, meters, jackpots, hoppers, progressives, and so on. Each device MUST have an owner. The owner has control of the device and is the only entity allowed to write to the device. The owner may be the EGM or a host. In the case where the EGM is the owner, the host identifier is 0 (zero). Other hosts are considered guests of the device. A host may be the owner of multiple devices and, at the same time, be guests of others. There may also be multiple devices within a class. Different hosts may own different devices within a class. If an EGM supports the optionConfig class, the device MAY have a secondary owner, the configurator, that is responsible for configuring the device’s options. The configurator may be the same as the owner or it may be a different entity. In addition, the configurator can be the EGM using host identifier 0, in which case, the device can only be configured locally at the EGM. The owner and configurator, plus the list of guests, for each device are determined as part of the initial EGM configuration discussed above. The EGM MUST only accept option configuration commands for the device from the configurator of the device. The EGM MUST only accept control commands related to the native class of the device from the owner of the device. The EGM MUST only accept non-control commands related to the native class of the device from guests of the device. The lists of commands available to owners and guests are clearly identified at the beginning of each chapter. By default, an EGM will direct all EGM-originated requests related to a device to the owner of the device. Only the owner of a device receives such commands. The owner may direct host-originated requests to devices that it owns within the EGM. The EGM MUST respond to all properly formed requests from the owner of a device. In the case where an EGM owns a device, the owner commands are not transmitted over the network, i.e. only events, guest requests and responses to guests requests appear on the network. 1.9.2 Device Guests Guests may direct certain requests to devices that they do not own. These requests are clearly listed in a table at the beginning of each chapter. The EGM MUST only respond to such requests if the guest is a permitted guest of the device. The list of permitted guests for a device can be configured locally at the EGM or remotely via a configuration server. Within the eventHandler class, hosts may subscribe to events generated by devices. A host may subscribe to any event generated by a device that it owns. It may also subscribe to events generated by devices to which it is Page 8 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 1 g2sMessage a permitted guest. A host may not subscribe to events for devices that it does not own or to which it is not a permitted guest. Within the meters class, a host may request and subscribe to meters for all devices. A host may make such requests and subscriptions regardless of ownership or guest permissions. There are no restrictions on access to meter information. 1.9.3 Registered Hosts As noted above, when an EGM is initially configured, both the owners of its devices and any additional guests MUST be registered in the machine. At a minimum, registration can be achieved by keying the information directly into the machine. In addition, a more automated method, such as a configuration server, can be employed. The pool of registered owners and guests form the complete set of subscribers to an EGM. The EGM MUST NOT process commands from host systems outside this set of subscribers. If a command is restricted to the owner of a device and the command is sent by another host, the EGM will not execute the command. The EGM MUST send error G2S_APX010 Command Restricted to Owner in the application-level response. Likewise, if a command is sent by a host that is neither the owner nor a permitted guest of the device, the EGM MUST send error G2S_APX012 Command Restricted to Owner and Guests in the application-level response. 1.9.4 Active & Inactive Devices Over time, the devices contained within the EGM may change. Devices may be added and removed from an EGM. Also, devices may be made active or inactive. The full set of devices contained within the EGM is exposed through the commConfig class (see Chapter 8). This class is used to assign owners, guests and configurators to devices and to make a device active or inactive. Only active devices may have guests. Outside of the deviceConfig and commConfig class, only active devices are exposed by the protocol. Unless a device is active within the commConfig class (or manually by an operator locally at the EGM), the device will not be addressable through other classes within the protocol. Only active devices appear in the descriptorList for the EGM. Only active devices appear in the device-level meters for the EGM (class-level meters contain the life-to-date meters for a class and are available regardless of the status of the underlying devices). 1.9.5 Changes To Devices When an EGM first initiates communications, it will send an initial commsOnLine command to each registered host. This command is designed to notify the host systems that the EGM is available and ready to start processing commands. If the deviceChanged attribute of the commsOnline command is set to true, the host should check the EGM’s device structure and the host’s subscriptions. There may have been changes to the device structure of the EGM. During the course of operations, the EGM will send other communications-related commands to the host. These commands imply that the EGM’s device structure and the host’s subscriptions are still intact and that the host does not necessarily have to reset its subscriptions. Any time the devices within an EGM are added or removed, host subscriptions are compromised. Host subscriptions are oriented around deviceIds. The addition or removal of a device may jeopardize the monitoring and control of the EGM. Thus, any time the underlying nature of any of the devices within an EGM changes, a host should validate its meter and event subscriptions. Whenever the device structure changes, the EGM MUST send a commsOnLine command, with the deviceChanged attribute set to true, to each affected host. If a host is not an owner or a guest of a device then it does not necessarily receive a commsOnLine command. An EGM is only required to send a commsOnLine to a host whose owner or guest status was affected by the change. At that point, the host should re-interrogate the EGM to identify new devices, resetting its event and meter subscriptions as necessary. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 9 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 Any time the device structure of the EGM is reset, the EGM must send a commsOnLine command to each host with the deviceReset attribute set to true. Because the devices within the EGM may have been renumbered, subscriptions set by a host may no longer reference the correct devices. Thus, when a host receives such a command, it is recommended that the host re-interrogate the EGM and reset its meter and event subscriptions. It is also recommended that the host clear any unsent commands queued for the EGM. Those commands may not be targeted to the correct device. Changes to the device structure of an EGM may be made locally at the EGM or remotely via a configuration server. As noted above, whenever such changes are made, the EGM must enter its restart sequence and send a commsOnLine command to each registered host, as appropriate. More information on the commsOnLine command can be found in the communications class (see Chapter 2). 1.10 Host & EGM Identifiers Each host system within a gaming network is assigned a unique host identifier by the administrator of the network. Host identifiers MUST be positive integer values. By convention, host identifier 0 (zero) is used within the protocol to identify the EGM. The host identifier for a particular host system MUST be configured into the host system. The host system MUST validate this host identifier against the host identifier contained within each message received from an EGM. If the host identifier contained within a message is incorrect then the host MUST respond to the EGM with error G2S_MSX001 Incorrect HostId Specified. An EGM MUST validate the host identifier associated with a given communications channel against the host identifier contained with each message received from a host. If the host identifier contained within a message is incorrect then the EGM MUST respond to the host with error G2S_MSX001 Incorrect HostId Specified. Each EGM is assigned a unique EGM identifier by the manufacturer. EGM identifiers are 32-character alphanumeric strings. To avoid duplication across manufacturers, the Gaming Standards Association assigns one or more unique prefixes to each manufacturer. Each manufacturer MUST prefix the EGM identifiers that it assigns to its machines with one of its GSA-assigned prefixes followed by the underscore character, for example GSA_12345. See Section 1.11 Unique Identifiers, for additional restrictions. An EGM identifier MUST be registered with a host system before the EGM may commence communications with the host. If the EGM identifier contained within a message is incorrect then the host MUST respond to the EGM with error G2S_MSX002 Incorrect EgmId Specified. An EGM MUST validate the EGM identifier contained within each message received from a host. If the EGM identifier contained within a message is incorrect then the EGM MUST respond to the host with error G2S_MSX002 Incorrect EgmId Specified. 1.11 Unique Identifiers Unique identifiers appear throughout the G2S protocol, especially in enumeration lists. By convention, when such identifiers are part of the G2S protocol definition, they are always prefixed by "G2S" followed by the underscore character, for example G2S_largeWin. When such identifiers are assigned by a manufacturer, they MUST be prefixed by one of the manufacturer’s GSA-assigned prefixes followed by the underscore character, for example ATR_newEnumeration. The prefix MUST be constructed using the ASCII characters [A-Z0-9]. No other characters are permitted. The underscore character MUST be used to separate the prefix from the suffix. The suffix MUST be constructed from "printable" ASCII characters (see below). When constructing suffixes, a modified camel-case style is preferred—that is, begin the suffix in lower case and thereafter capitalize each new word, as in the suffix Page 10 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 "newEnumeration". Within the G2S protocol, all elements, attributes, identifiers and other protocol-related constructs are case-sensitive. The complete XML schema pattern that supports all "printable" ASCII characters is as follows: [!"#$%&'()*+,\-\./0-9:;<=>\?@A-Z\[\\\]\^_`a-z{|}~] The following special characters MUST be specified using their corresponding entity references when constructing XML messages. Table 1.1 Characters to be Specified Using Entity References Character Entity Reference Description & & Ampersand < < Less Than > > Greater Than " " Quote ' ' Apostrophe 1.12 Date/Time Format By convention, the G2S protocol requires that the complete XML date/time format be supported. The following example illustrates this format: 2006-06-17T11:26:18.563-05:00 All date/time values MUST be represented as Coordinated Universal Time (UTC). Time-zone offsets, if used, are in reference to UTC. If time-zone offsets are omitted then the recipient of a date/time value can assume that the date/time is UTC. In practice, local date/time can be converted to UTC and sent without a time-zone offset. Alternatively, local date/time can be sent with the appropriate time-zone offset to UTC. Time MUST be supported to the millisecond, which is 3 (three) digits to the right of the decimal place. Additional digits of precision beyond three MUST be truncated by the recipient. If less than three digits to the right of the decimal place are sent, or the decimal place is omitted, then the recipient MUST replace the omitted values with zeros. Hours, minutes and seconds are required and may not be omitted. 1.13 Meters Within the G2S protocol, each device is metered separately. Meters are always available on a device-by-device basis. An EGM MUST store all meter information in persistent memory. The class description for a device includes the list of meters used by the device. In addition to device-level meters, the G2S protocol also provides class-level meters. These meters represent the totals for all devices within the class. Because devices may be added and removed from an EGM, it is possible that the device-level meters will not add up to the class-level meters. Typically, class-level meters will be used to meet long-term accounting requirements. Device-level meters will mostly be used for short-term operational analysis and reconciliation. By convention, device identifier 0 (zero) is used to identify class-level meters. The same command set is used to request device-level and class-level meters. For some devices, e.g. game play and currency handling devices, the G2S protocol provides additional detail meters below the device level. In the case of game play devices, additional detail meters are available by gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 11 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 denomination and wager category. For currency handling devices, additional detail meters are available by currency and denomination. A separate command set is used to access the detail meters. Monetary meters are expressed in one thousandths of the minor unit of the base currency of the EGM to accommodate fractional cent play. For example, if the base currency is United States Dollars, then denominations would be expressed in millicents. Typically, depending on the base currency of the EGM, there is an implied decimal place to convert from the minor unit to the major unit of the currency. Because monetary meters are recorded in thousandths of the minor unit, there will always be a conversion applied to convert meter values to minor or major units of the currency. More information on the base currency of the EGM may be found in the chapter on the cabinet class (see Chapter 3). The maximum meter value supported by the G2S protocol is 999,999,999,999,999. 1.14 Transaction Logs The G2S protocol requires that an EGM maintain logs of critical transactions in persistent storage. In case of power or communications outages, these logs are used to preserve and recover critical transactions. During EGM recovery due to a power outage, a communications outage or any other event that may have caused commands to be lost, the EGM MUST resend any commands required to complete transactions that were not acknowledged at the application level by the host. Transaction logs are maintained on a class-by-class basis; all of the transactions related to a particular class are contained within a single class-level log. The number of transactions that MUST be maintained in persistent storage by the EGM may be configured on a class-by-class basis. By default, it is recommended that the last 35 transactions be maintained. 1.14.1 transactionId A unique transaction identifier, transactionId, is assigned to each logical transaction. This unique transaction identifier is contained in each command associated with the transaction. The same transaction identifier will appear in each command that is part of a multi-step transaction. The transaction identifier provides context to the host and EGM so that they can quickly and simply identify and update their transaction records. Transaction identifiers MUST be generated as a monotonically-increasing sequence starting at 1 (one). The EGM MUST maintain the counter used to generate transaction identifiers in persistent storage. A common counter MUST be used for all transactions within the EGM. 1.14.2 logSequence A unique log sequence number, logSequence, is also assigned to each log record. The EGM MUST generate the log sequence numbers as a monotonically-increasing sequence starting at 1 (one). The EGM MUST maintain the counters used to generate log sequence numbers in persistent storage. A separate counter MUST be used for each log. Within a single transaction log, the log sequence numbers MUST appear as an unbroken monotonically-increasing series. 1.14.3 transactionId vs. logSequence Transaction identifiers uniquely identify individual transactions within an EGM. Log sequence numbers identify the sequence of transactions within a single transaction log. Both are generated as monotonicallyincreasing series. However, as noted, they serve two completely different purposes. Transaction identifiers identify a unique transaction within the EGM. Log sequences identify a unique transaction within a class-level log. Page 12 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1.14.4 Chapter 1 g2sMessage Recovery from Outage and Duplicate Detection When recovering from an outage, an EGM MUST resend commands to complete all critical transactions that were not acknowledged at the application level by the host. Due to timing differences, this process may cause the EGM to send duplicate commands to the host. The host MUST be aware of this possibility and be prepared to detect duplicate logical commands coming from an EGM. Transactions MUST be recovered on a class-by-class basis. When multiple transactions are recovered from a single class, those transactions MUST be retried in proper sequential order. There is no requirement that an EGM recover transactions in sequential order across multiple classes, only within a single class. 1.14.5 Commands to Query Log Contents A standard set of commands is used to query the contents of transaction logs. A similar set of commands is used with all classes. First, a getClassLogStatus command is used to request the last log sequence number and the number of entries within a log. These values are returned in the lastSequence and totalEntries attributes of a classLogStatus command. Second, a getClassLog command is used to request one or more records from the log. Optionally, the command may contain a lastSequence and/or totalEntries attribute. These attributes are used to fine-tune the contents of the classlogList command that is used to return the requested log contents. getClassLog • If the lastSequence is set to 0 (zero), the returned list MUST start with the last transaction added to the log and work backward, in descending logSequence order. • If lastSequence is not set to 0 (zero), the returned list MUST start with the specified transaction and work backward, in descending logSequence order. • If the transaction specified by the lastSequence is not in the log, the EGM MUST return an empty list. • If totalEntries is set to 0 (zero), the list MUST include all transactions in the log where the logSequence is less than or equal to the starting position determined by the lastSequence value. • If totalEntries is not set to 0 (zero), the returned list MUST include either the number of transactions specified or the number of transactions in the log where the logSequence is less than or equal to the starting position determined by the lastSequence value, whichever is less. 1.14.6 Log Commands and deviceId Values A host may issue a getClassLogStatus or getClassLog command to any valid deviceId within a class (except eventHandler class, see below) that is contained in the descriptorList, and the response will be constructed as if the request was issued to deviceId 0 (zero). No special filtering is performed if the commands are directed to a non-zero deviceId; the ClassLogStatus and ClassLogList may contain records corresponding to several device identifiers. NOTE: The only exception to this is the eventHandler class, where there is a separate log for each device. 1.15 Event Handling The G2S protocol uses events to report that an action has taken place at an EGM. Events are always reported after the action has taken place—events are after-the-fact. In general, an event is generated whenever the state of a device changes. An event may be related to a change in the status of the device, its meters, or its transaction log. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 13 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 In many cases, there may be a series of commands exchanged between an EGM and a host before an event occurs—commands are before-the-fact. For example, an EGM may request a new voucher configuration. This action is not reported as an event since it has not changed the state of the EGM. Until the EGM receives a new configuration that is different than its current configuration and the EGM applies that new configuration, no event is reported. After the EGM applies the new configuration and, thus, changes its state, then an event is reported. Each class description contains the list of events for the class. With each event, there is a description of the device states, meters and transaction updates associated with the event. These descriptions clearly identify the cause of an event and the updates associated with an event. They are designed to provide clear guidance for implementation and compliance testing. Each event generated by an EGM MUST be assigned a unique event identifier. Event identifiers are similar to transaction identifiers. However, event identifiers are used to sequence EGM-related events while transaction identifiers are used to sequence EGM-related transactions. Event identifiers MUST be generated as a monotonically-increasing sequence starting at 1 (one). The EGM MUST maintain the counter used to generate event identifiers in persistent storage. A single counter MUST be used for all events generated by the EGM. The sequence of event identifiers MUST appear as an unbroken, monotonically increasing series. 1.16 Event Subscriptions The G2S protocol contains a special eventHandler class (see Chapter 4). A host may use this class to subscribe to a set of events. Each host may set its own subscription. Thus, there is one event handler device per host. When an event occurs, the EGM will check each host’s subscription to determine whether the event should be sent to the host. At the time a host subscribes to events, the host may choose to have the EGM persist the events until acknowledged by the host. The host may make this choice on an event-by-event basis. It is expected that an EGM will only allocate a limited amount of persistent memory for this feature. Thus, if communications are interrupted, it is possible that an EGM may not have sufficient space to store additional events. In such a case, the EGM may overwrite the oldest events, discard new events and remain enabled, or discard new events and become disabled. The preferred behavior as well as the number of events which must be persisted and the retry frequency may be set locally at the EGM or remotely through a configuration server. By default, overwriting the oldest events, a minimum of 200 events, and a retry frequency of 30 seconds are recommended. Event subscriptions are evaluated at the time an event is generated by a device. The EGM MUST compare the event to the subscription of each host and place a command containing the event on the outbound communications queue of each qualifying host. At the same time, if the host has requested that the event be persisted, the EGM must persist the event in the event log of the eventHandler device of the host. Such events must be persisted and retried by the EGM until acknowledged at the application level by the host. As part of its event subscription, a host may request that the EGM send additional associated data. This data MUST be included as part of the command used to report the event. The data MUST be collected and sent when the event is initially generated and whenever the event is retried. The associated data will reflect the state of devices, meters and transactions at the time the command containing the event is placed on the outbound command queue, not the state at the time the event actually occurred. The host may choose to have affected class meters, device meters, transaction log records and/or device states sent with an event. The EGM MUST identify the affected data based on the updates that it performed in conjunction with the event. If one or more attributes of a transaction log record are updated, the complete transaction log record MUST be sent. And, if one or more attributes of a device status record are updated, the complete device status record MUST be sent. However, a particular data set—that is, class meters, device Page 14 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 1 g2sMessage meters, device statuses, or log records—should only be sent if data within that data set was actually updated. There is no requirement to send data sets that were not updated as a result of the event. The documentation for each event provides clear guidelines regarding the data that may be updated in conjunction with an event. In the cases of class meters and device meters, a host may instruct the EGM to only send updatable meters for affected devices. In these cases, rather than sending all meters for the affected device, the EGM only sends meters that could have been updated by the event. The exact list of meters that could have been updated by an event is identified in the detailed description of each event. The host may select this option on an event-byevent basis for each device within the EGM. The EGM MUST persist the list of data sets updated in conjunction with an event with the event log record for the event. When an event is retried, the EGM MUST use this list of data sets to collect and send the affected data associated with the event. As noted above, this data will reflect the current values of the data set, not the values at the time the event occurred. The retry-indicator contained in the class-level element of the retried command may be used by a host to determine whether the affected data was captured concurrently with the event. Event subscriptions MAY also be forced into an EGM. Such subscriptions can be entered locally by an operator at the EGM or remotely through a configuration server. A property may elect to force certain critical events, such as security events, to a host to meet specific regulatory requirements. The EGM MUST treat such subscriptions as if they had been set by the host itself. A host MAY subscribe to the same events. In that case, when processing such an event, the EGM MUST "OR" the affected-data and persistence attributes of the event subscriptions. A host may not clear a forced subscription. It is intended that the logs used to record and track events behave similarly to the logs used to record and track transactions. Both contain log sequence numbers and acknowledgement indicators. Both must be persisted by the EGM. However, event logs are maintained on a host-by-host basis while transaction logs are maintained on a class-by-class basis. For transaction logs, the owner of the device that generated a transaction MUST acknowledge the transaction. For event logs, the owner of the event log, not the owner of the device that generated the event, MUST acknowledge the event. The event subscriptions for host systems are considered part of the protocol-related configuration data. As such, the event subscriptions MUST be persisted by the EGM and used by the EGM following a restart. 1.17 g2sMessage Element The g2sMessage element forms the root element of all messages exchanged between a host and an EGM. This element forms the outer wrapper for all such messages. The g2sMessage element has no attributes. It has three possible sub-elements. The first two sub-elements, g2sBody and g2sAck, support point-to-point message delivery. The third sub-element, g2sMulticast, supports multicast message delivery. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 15 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 The point-to-point format is quite specific. It is used for communications between a single host and a single EGM. Commands within a g2sBody specify a particular device within an EGM. The point-to-point format is designed to be used when a host needs to manipulate a single device within an EGM. It is also used by EGMs to request transaction authorizations and to report events. All commands within the G2S protocol can be used with the point-to-point format (see Section 1.18). The multicast format is much more general. It is used for communications between a single host and a group of EGMs. Commands are not directed at a single device within a single EGM. Instead, commands are directed at a multicast group. One or more devices may be joined to a multicast group. All of the commands within a multicast message are passed to all of the devices joined to a multicast group. At the application-level, reference values contained within the commands, e.g. progressive identifier and progressive level, may be used by a device to identify which commands are relevant to that device. Such filtering is done at the application level, not the message level. Only a small subset of commands can be used with the multicast format. Those commands are clearly identified in the class descriptions. This subject is discussed in further detail in Section 1.19 as well as Chapter 2 in the communications class. 1.18 Point-to-Point Format The g2sBody element contains a set of attributes that identify the sender, receiver and date/time of a message. It also contains the application-level commands contained in class-level sub-elements. The g2sAck element acknowledges the receipt of a message. Like the g2sBody element, it contains a set of attributes that identify the sender, receiver and date/time of the message. Ignoring the attributes for a moment, the following example highlights the structure of a G2S point-to-point message and its acknowledgement: Message <g2sMessage> <g2sBody> <anyClass> <anyCommand /> </anyClass> <anyClass> <anyCommand /> </anyClass> </g2sBody> </g2sMessage> // Message Level // Class Level // Application Level // Class Level // Application Level Acknowledgement <g2sMessage> <g2sAck /> </g2sMessage> // Message Level In the above examples, anyClass and anyCommand are not actual G2S elements. They are used as an example to demonstrate how messages are constructed within the G2S protocol. The anyClass element represents the standard class-level element used for command routing and error reporting. The anyCommand element represents a class-specific application-level function. Point-to-point commands are always constructed in this way. The g2sMessage element forms the outer wrapper for both the original message and the acknowledgement. The g2sBody element contains information that identifies the message itself. This information is reiterated in the g2sAck element of the message-level response. The g2sAck element identifies the message that was specified in the g2sBody element of the original request—that is, the message being acknowledged. The g2sBody element also contains the application-level commands. Page 16 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.18.1 g2sBody Element The g2sBody element contains a set of attributes that identify the message. These attributes include the host identifier, the EGM identifier, and the date and time that the message was sent. All of these attributes are required. Table 1.2 g2sBody Attributes Attribute Restrictions Description hostId type: deviceId use: required Host identifier assigned by the gaming network administrator. egmId type: egmId use: required EGM identifier assigned by the manufacturer. dateTimeSent type: dateTime use: required Actual date and time that the message was sent. The following example highlights the attributes of the g2sBody element: <g2sBody hostId = "1" egmId = "GSA_12345" dateTimeSent = "2005-12-10T10:54:27.123-05:00" > The g2sBody element also contains the application-level commands included in the message. A single g2sBody element may contain multiple application-level commands. Each application-level command is contained within a class-level element. The class-level element contains a standard set of attributes that are used to control the processing of the application-level commands. The same set of class-level attributes are used for all classes. Class-level elements are discussed in Section 1.18.3. At a minimum, the egmId and hostId attributes contained within the g2sBody element MUST be validated. If the resident transport layer provides the hostId and/or egmId values these values MAY be used to construct the g2sAck. Additionally, before an acknowledgement is sent, the message MAY be checked to ensure that it is well-formed XML 1.0 and the message MAY be validated against one or more XML schemas. If errors are detected, the errors MUST be reported to the originator of the message using the errorCode and errorText attributes of the g2sAck element. The list of relevant error codes is included near the end of this chapter. The egmId and hostId uniquely identify a transport association. If either parameter is not the expected value, then the commands contained within the message MUST NOT be processed by the recipient and an appropriate error code (G2S_MSX001 or G2S_MSX002) MUST be returned in the g2sAck to the originator. The originator of the message MUST remove the commands contained within the original message from its outbound queue. Depending on the transport used, when first establishing communications with a host, an EGM may have to provide information to the host so that the host can originate messages to the EGM. If the host does not have that information or the host is unable to establish communications to the EGM using that information, then the commands contained within the message MUST not be processed by the host and error G2S_MSX003 Communications Not Online MUST be returned in the g2sAck to the EGM. The EGM MUST then reinitialize its communication queues and reestablish communications with the host starting with the commsOnLine command. The communications class, Chapter 2, contains more information on this subject. If the XML is not well-formed, then the commands contained within the message MUST NOT be processed by the recipient, and error G2S_MSX004 Incomplete/Malformed XML MUST be returned in the g2sAck to the originator. The originator of the message MUST remove the commands contained within the original message from its outbound queue. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 17 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 If further validation of the XML schemas fails, then the commands contained within the message MUST NOT be processed by the recipient and error G2S_MSX005 Invalid Data Type Encountered MUST be returned in the g2sAck to the originator. The originator of the message MUST remove the commands contained within the original message from its outbound queue. 1.18.2 g2sAck Element The g2sAck element contains a set of attributes that identify the message being acknowledged. A g2sAck is sent to acknowledge the receipt of a g2sBody. It is sent using the response mechanism provided by the message transport. The attributes of the g2sAck element include the EGM identifier, the host identifier, and the date and time that the g2sAck was sent. All of these attributes are required. Optionally, the g2sAck element may also contain attributes that identify a message-level error. Message-level errors prevent the processing of a message and imply that the contents of the g2sBody element could not be processed. Message-level errors (see Table 1.11) include malformed XML, inappropriate data types, message corruption, missing elements, missing attributes, and others. If a message-level error is generated, the commands contained within the g2sBody element MUST NOT be processed. In practice, it is anticipated that few, if any, message-level errors will occur. Because message-level errors may be reporting that all or part of a message was corrupted, the data contained within the g2sAck element may be unreliable. Specifically, the hostId and egmId may be unreliable. Thus, the recipient of a g2sAck element MUST check for an error code before doing any other processing. If an error code is present, the recipient MUST assume that any other data contained in the g2sAck element may be corrupt and MUST NOT rely on the data for any subsequent processing. The recipient MUST rely on application-level resend logic to recover from errors reported in the g2sAck element. Before processing any commands in a message, both the host and the EGM MUST validate the hostId and egmId contained in the g2sBody. A host or EGM that detects an incorrect hostId or egmId MAY indicate the error in a g2sAck; if the host does not indicate the error in a g2sAck then the host should generate a log entry; if the EGM does not indicate the error in a g2sAck then the EGM MUST generate at least one error event for the message. If the hostId and/or egmId for a message are undecipherable or syntactically invalid, the recipient MUST still construct a valid g2sAck. In this case, if the hostId attribute is undecipherable or syntactically invalid, the recipient MUST set the hostId attribute of the g2sAck to 0 (zero) and the errorCode to G2S_MSX001. If the egmId attribute is undecipherable or syntactically invalid, the recipient MUST: • Set the egmId attribute of the g2sAck to G2S_undecipherable. • Unless the errorCode G2S_MSX001 is required, the recipient MUST set the errorCode to G2S_MSX002. While the EGM is trying to establish communications—that is, the communications device is in the opening state, the EGM will retry the commsOnLine command until a commsOnLineAck is received from the host. During this period, until the host has established communications to the EGM, the host MUST set the errorCode of the g2sAck to G2S_MSX003 Communications Not Online. While in this state, the host MUST NOT process any commands received from the EGM except the commsOnLine command. At the applicationlevel, the host MUST discard commands until the commsOnLine command is successfully processed and communications from the host to the EGM have been established—that is, a g2sAck has been received to a message containing the commsOnLineAck command. Note that before sending a g2sAck, both the host and the EGM MUST validate the hostId and egmId for the message, either by inspecting the g2sBody or through mechanisms provided by the transport. If the hostId attribute is incorrect, the recipient MUST set the errorCode to G2S_MSX001. If the egmId attribute is incorrect, the recipient MUST set the errorCode to G2S_MSX002, unless the errorCode G2S_MSX001 is required. Hosts MUST also verify that communications have been established to the EGM prior to sending a g2sAck. However, the host is not expected to open the g2sMessage to check for a commsOnLine command before Page 18 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 1 g2sMessage setting the errorCode G2S_MSX003 Communications Not Online. As noted above, until the host receives a g2sAck to a g2sMessage containing the commsOnLineAck command, the host MUST continue to respond to the EGM with the G2S_MSX003 errorCode. The receipt of a g2sAck by the host implies that full two-way communications have been established. Even though XML parsing errors and other errors related to the structure of the g2sBody can be reported as a message-level error, such errors that are detected within the g2sBody can also be reported as application-level errors on a command-by-command basis. If the implementer chooses to report such errors at the applicationlevel and any or all of the contents of the g2sBody is indecipherable and, thus, the commands cannot be processed, then event G2S_APE001 At Least One Syntax/Semantic Command Error MUST be generated by the EGM. If the originator of a message containing a g2sBody has not received the g2sAck message within a configurable time period, the originator of the message MUST resend the message. The originator of a message MUST NOT discard the message until it has been acknowledged by the recipient. A default value of 30 seconds is recommended for the configurable time period. However, other fixed values and sliding-window strategies may be used. For the purposes of the G2S protocol, it is assumed that, if a g2sAck has not been received within the configurable time period, there was a communications failure. The originator of the message may have to reestablish communications. The method used to re-establish communications may vary depending on the underlying transport and may involve resending messages over an existing connection. Whenever an EGM drops or establishes a communications connection, it is required to record the event and notify the appropriate host systems. Host systems are not necessarily under the same requirement, but it is recommended that host systems create log entries whenever a communications connection is dropped or established. When forming the g2sAck element, the hostId of the g2sAck element MUST be set to one of the following: a. hostId of the g2sBody element. b. hostId as provided by a transport mechanism. c. substitute value specified for a hostId that is indecipherable or syntactically invalid. the egmId of the g2sAck element MUST be set to one of the following: a. egmId of the g2sBody element. b. egmId as provided by a transport mechanism. c. substitute value specified for an egmId that is indecipherable or syntactically invalid. . gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 19 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 Table 1.3 g2sAck Attributes Attribute Restrictions Description hostId type: deviceId use: required Host identifier assigned by the gaming network administrator. egmId type: egmId use: required EGM identifier assigned by the manufacturer. dateTimeSent type: dateTime use: required Actual date and time that the message was sent. errorCode type: errorCode use: optional default: G2S_none Error code if a message-level error occurs; otherwise, set to G2S_none. errorText type: errorText use: optional default: <empty> Optional text message that can be supplied when the errorCode is not set to G2S_none. The errorCode attribute MUST have the value G2S_none unless a message-level error is being reported. The errorText attribute MUST be set to <empty> unless the errorCode attribute has a value other than G2S_none. The errorText attribute is used to convey additional information regarding an error condition. The following example highlights the attributes of the g2sAck element when a message is successfully received: <g2sAck hostId = "1" egmId = "GSA_12345" dateTimeSent = "2005-12-10T10:54:27.321-05:00" /> The following example highlights the attributes of the g2sAck element when an error occurs during the processing of a message: <g2sAck hostId = "1" egmId = "GSA_12345" dateTimeSent = "2005-12-10T10:54:27.321-05:00" errorCode = "G2S_MSX002" errorText = "Incorrect egmId specified." /> 1.18.3 Point-to-Point Class-Level Elements A single g2sBody element may contain multiple application-level commands. Each application-level command is contained within a class-level element that contains a standard set of attributes that direct the processing of the application-level command. All classes use the same set of class-level attributes. The name of the class is used as the element name for the class-level element, for example handpay, meters, cabinet, etc. Thus, the name of the class-level element directs the command to the appropriate class. Additional attributes within the class-level element direct the application-level command to the appropriate device. Each application-level command is atomic. Commands are not grouped into transactions. No transaction support is implied. Each command is processed independently of all other commands. The processing order for commands is at the discretion of the receiver of the commands. See Section 1.18.5 for additional ordering restrictions on the contents of g2sBody elements. If a g2sMessage passes validation of the XML schemas, but does not meet the syntax and semantic requirements specified in this document, then the errors SHOULD be detected at the application-level on a command-by-command basis. When such an error is detected in a request command and a more precise error code is not defined, a response MUST be generated with the error code G2S_APX009 Command Contained At Least One Syntax/Semantic Error. When such an error is detected by a host in a non-request command, the Page 20 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 host should generate a log entry. When such an error is detected by an EGM in a non-request command, the EGM MUST generate the event G2S_APE001 At Least One Syntax/Semantic Command Error, unless a more precise event is defined. 1.18.3.1 Command Identification Attributes The standard set of class-level attributes starts with a set of attributes used to route, identify and sequence commands. These attributes include the device affected by the command, the date/time that the command was originated and the command identifier of the command. The name of the class-level element identifies the device class. The device identifier is a unique identifier within the device class. The device identifier is assigned by the EGM. The command identifier is assigned by the originator of a command. It is used to uniquely identify an individual command and to sequence commands originating from a host or EGM across a single communications channel. Each communications channel MUST use its own sequence. The EGM MUST use a separate sequence with each host. Likewise, a host MUST use a separate sequence with each EGM. The command identifier MUST be a monotonically-increasing sequence starting at 1 (one) that can be used to determine the order of commands. Hosts and EGMs are not required to persist the counters used to generate command identifiers across connections. For EGMs, the commsOnLine command implies that the counters may have been reset. However, a reset is not required. For hosts, the commsOnlineAck implies that the counters have been reset. Likewise, a reset is not required. Table 1.4 Standard Point-to-Point Command Identification Attributes Attribute Restrictions Description deviceId type: deviceId use: required Device identifier assigned to an instance of a device within a class by the EGM. dateTime type: dateTime use: required Date and time that a command was originated. commandId type: commandId use: required Unique command identifier assigned by the originator of a command. 1.18.3.2 Command Handling Attributes The next set of class-level attributes is used to direct the handling of an application-level command. This set of attributes includes the session type, session identifier, a session retry indicator, the time-to-live value, and session continuation indicator. The session type indicates how the recipient should process the command. There are three possible methods: request, response or notification. As noted above, a request requires that the recipient send the prescribed application-level response. An application-level response MUST NOT be sent for a notification. The session identifier is an application-level identifier assigned by the originator of a request. The recipient of a request MUST include the session identifier of the request in its response. The originator of a request may choose any method it prefers to determine the value of the session identifier. It is anticipated that the originator of a request will use the session identifier to determine the context of a response. This can be especially important if there is an error during the processing of the application-level command. In practice, the application-level transaction identifier is frequently used as the session identifier. The originator of a notification may also set a session identifier, but it is not required. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 21 G2S™ Message Protocol v1.0.3 Chapter 1 g2sMessage The originator of a request may also set a time-to-live value. If the recipient of a request does not start to process the command within the prescribed time period, the recipient MUST respond with error code G2S_APX011 Time-to-live Expired indicating that the time-to-live expired. The time-to-live period is calculated from the dateTime value contained in the request. When the value of 0 (zero) is set for the time-tolive, the command MUST NOT be expired by the recipient – an unlimited time-to-live is implied. Time-to-live has no meaning with notifications and responses. A value of 0 (zero) MUST be used. It is anticipated that EGM manufacturers and system providers will determine appropriate time-to-live values based on experience with the G2S or other protocols. In some sections of this document, specific time-to-live values are recommended. However, in most cases, the time-to-live value is left for the implementer to determine. When in doubt, a time-to-live value of 30 seconds should be appropriate. Certain classes contain specific application logic that must be executed if the EGM is not communicating with the owner of a device within that class—that is, the owner is offline. This logic may be based upon the state of the communications device associated with the owner. Alternatively, the logic may be based upon the receipt of application-level responses to specific requests originated by the device. In this case, in addition to the time-tolive period, a specific class may use a no-response period. If a device is originating requests but is not receiving responses and this condition persists beyond the no-response period then the device may invoke its offline application logic, possibly disabling itself. To be effective, the no-response period must extend beyond the time-to-live-period so that multiple request retries can be attempted before the device declares the owner offline. The session continuation indicator is used when a host or EGM is unable to include the complete contents of a response or notification in a single command. In this case, the host or EGM may break the response to a request or notification into multiple commands. Each individual command in the multi-part command series MUST be semantically and logically complete. The recipient MUST be able to process each command as if the command were not part of a multi-part command series. All commands in a multi-part response or notification MUST be sent as a contiguous series of commands using a continuous series of command identifiers. The recipient of a multi-part command series may assume that the response or notification is complete if (1) the session continuation indicator contained within a command is set to false, (2) the command is not the correct response to the request, or (3) there is a break in the command identifier sequence. When responses and notifications are broken into multiple commands, the session continuation indicator for all commands except the last command of the multi-part command series MUST be set to true. If a command is not part of a multi-part command series or a command is the last command of a multi-part command series then the session continuation indicator MUST be set to false. In addition, the session identifier of each command in a multi-part command series MUST use the same session identifier. The session type MUST be set to G2S_response or G2S_notification, as appropriate. Multi-part command series MUST NOT be used with requests. The session retry indicator is used to alert the recipient of a command that the command may be a duplicate. The recipient may use this indicator as part of it application logic to prevent duplicate processing of the same logical transaction. However, it should not be used as the only method of duplicate detection. Appropriate application-level logic MUST be used at all times. When an EGM retries an event, the EGM MUST set the session retry indicator to true in the command containing the event. The session retry indicator alerts the host that the affected data sets contained in the command reflect the current values of the affected data sets rather than the values at the time the events were generated. If the recipient detects that it has already processed a logical transaction, it MUST construct the same logical response to the command and set the session retry indicator to true in that response. If the logical transaction Page 22 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 has not been processed, then the recipient MUST process the command, set the session retry indicator to false in its response. The requestor MUST only set the retry indicator to true when a command is being retried because an application-level response has not been received. This can occur when a time-to-live expires or during the restart/recovery process. Session retry indicators may be used with requests, responses and notifications. Table 1.5 Standard Point-to-Point Command Handling Attributes Attribute Restrictions Description sessionType type: sessionTypes use: optional default: G2S_request Type of command: request, response or notification. sessionId type: sessionId use: optional default: 0 Session identifier assigned by the requestor and returned by the responder. sessionRetry type: boolean use: optional default: false Indicates that the command may be a logically duplicate command. sessionMore type: boolean use: optional default: false Indicates whether additional commands in a multicommand response will follow. timeToLive type: timeToLive use: optional default: 30000 Number of milliseconds from the time a command was originated before it should be ignored. 1.18.3.3 Error Attributes Optionally, the class-level element of a response may contain additional attributes that identify an applicationlevel error. These attributes include an error code and a free-form text field. Protocol-wide application-specific error codes are included at the end of this chapter. Class-specific error codes are included with each class description or, if an error code is applicable to multiple classes, in Appendix A. The errorCode attribute MUST have the value G2S_none unless an application-level error is being reported. The errorText attribute MUST be set to <empty> unless the errorCode attribute has a value other than G2S_none. The errorText attribute is used to convey additional information regarding an error condition. The presence of an error code indicates that the recipient of a request was not able to successfully process the request. Thus, the recipient will not be able to construct the prescribed application-level response to the request. Therefore, when an error is being reported, the recipient MUST NOT include the prescribed application-level response element in its response. Only the class-level element should be included in the response. It is anticipated that not all EGMs and hosts will support all message classes and commands. Thus, it is possible during normal operations to encounter classes and commands that are not supported by an implementation. The protocol provides two error codes that MUST be used to report these conditions. If a class is not supported, the recipient of a request MUST respond with error G2S_APX007 Class Not Supported. If a command is not supported or a required command sub-element is not present, the recipient of a request MUST respond with error code G2S_APX008 Command Not Supported. The recipient MUST be prepared to receive these errors and adjust its processing accordingly. If a new version of the protocol is released that has been extended by adding additional attributes to commands or if manufacturer-specific extensions are implemented using namespaces, it is possible that an implementation may encounter unexpected attributes within a command which are not supported by the gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 23 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 implementation. While an implementation MUST support all required and optional attributes within the version of the protocol and command set that it supports, an implementation MUST ignore any unexpected and, thus, unsupported attributes that it encounters. Table 1.6 Standard Point-to-Point Error Attributes Attribute Restrictions Description errorCode type: errorCode use: optional default: G2S_none Error code if an application-level error occurs; otherwise set to G2S_none. errorText type: egmMessage use: optional default: <empty> Optional text message that can be supplied when the errorCode is not set to G2S_none. 1.18.4 Command Retry The timeToLive value indicates how long the recipient has to process a command. If the recipient has not started to process a command within the specified time frame—that is, dateTime plus timeToLive—then the recipient should abort the command and send error G2S_APX011 Time-to-live Expired. If the recipient has started to process a command within the specified time frame, it should execute the command to completion and send the prescribed response. The timeToLive value should only be checked prior to executing a command. If the originator of a request has not received a response within the specified time frame, the originator may, at its option, retry a command. Each time a command is retried, a new commandId MUST be assigned, the dateTime MUST be set to the current time, and the sessionRetry indicator MUST be set to true. The sessionRetry indicator MUST NOT be set to true in the original request. 1.18.5 Processing Order Commands MUST be sent in commandId order. When multiple commands are contained in a single g2sBody, the commands MUST be organized in ascending commandId order within the g2sBody – the lowest commandId appearing within the first class-level element. This requirement is designed to help expedite the processing of commands by not requiring that the recipient sort and order commands prior to processing. Sorting and ordering is the originator’s responsibility. In general, the commandId order should represent the natural order that commands occurred and the natural order that they should be processed. The recipient may process commands contained within its queue of unprocessed commands in any order it chooses. However, it is anticipated that both EGMs and hosts will normally process commands in commandId order. The only time that this may not be true is when a command cannot be processed because a critical resource is temporarily unavailable, for example a note acceptor is in the process of accepting a note. While the protocol allows this behavior, before adopting it, implementers MUST make sure processing a specific command out of order will not jeopardize the integrity of an application. 1.18.6 Class-Level Command Examples: Standard Notification The following example highlights the contents of the class-level element for a standard notification: <anyClass deviceId = "0" dateTime = "2004-02-27T13:47:31.321-05:00" commandId = "2000" sessionType = "G2S_notification" > <anyCommand /> </anyClass> Page 24 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1.18.7 Chapter 1 g2sMessage Class-Level Command Examples: Standard Request The following example highlights the contents of the class-level element for a standard request: <anyClass deviceId = "0" dateTime = "2004-02-27T13:47:31.321-05:00" commandId = "2001" sessionType = "G2S_request" sessionId = "1001" timeToLive = "30000" > <anyCommand /> </anyClass> 1.18.8 Class-Level Command Examples: Standard Response The following example highlights the contents of the class-level element for a standard response: <anyClass deviceId = "0" dateTime = "2004-02-27T13:47:31.432-05:00" commandId = "3001" sessionType = "G2S_response" sessionId = "1001" > <anyCommand /> </anyClass> 1.18.9 Class-Level Command Example: Response Reporting Error The following example highlights the contents of the class-level element for a response that is reporting an error: <anyClass deviceId = "0" dateTime = "2004-02-27T13:47:31.432-05:00" commandId = "3001" sessionType = "G2S_response" sessionId = "1001" errorCode = "G2S_APX008" errorText = "Command not supported." /> In the above examples, the anyClass and anyCommand elements are not actual G2S elements. They are used as examples to demonstrate how all commands are constructed and operate within the G2S protocol. 1.18.10 Standard Error Handling The G2S protocol supports error handling at two levels: the message level and the application level. Message-level error handling, see Section 1.18.10.1: Designed to support on-going communications between the EGM and host, assuring that messages are delivered. At the message level, resend logic is employed; identical copies of commands are resent. Application-level error handling, see Section 1.18.10.2: Designed to coordinate and facilitate the execution of logical transactions. At the application level, retry logic is employed; logical transactions are retried as new commands. It is anticipated that the G2S protocol will be implemented in multi-processor, multi-threaded environments. In such environments, it is possible that a response to a command may reach the EGM (or host) before the g2sAck to the original message that contained the command. Such responses MUST be considered valid responses regardless of the state of the message that contained the original request. Receiving a response to a command before receiving the g2sAck to the g2sMessage that contained the command is not an error. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 25 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.18.10.1 Error Handling – Message Level At the message level, the following error handling process should be followed to manage time-outs and message resends (X and Y refer to either EGMs or hosts). Normal Message Flow This is the normal flow of messages when there is no interruption in communications. 1. X sends a message containing a command to Y. 2. Y receives the message from X. 3. Y places the command in its queue of unprocessed commands. 4. Y sends a message acknowledgement to X. 5. X receives the acknowledgement from Y. 6. X clears the command from its queue of unsent commands. HOST EGM Message Sent Command included in message removed from unsent command queue Message Acknowledged Command included in message placed in unprocessed command queue Figure 1.2 Message-Level Error Handling: Normal Message Flow Message-level errors that are found in the g2sBody, as well as errors that occur during the parsing of a message, are reported using this normal message flow through the errorCode attribute within the message acknowledgement. This type of error would include commands missing required attributes, a message containing malformed XML, etc. Page 26 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 Message Not Received by Y This is the flow of messages when there has been an interruption in communications causing a message to not be received. 1. X sends a message containing a command to Y. 2. X does not receive an acknowledgement from Y within 30 seconds. 3. X resends the message to Y updating the dateTimeSent. 4. Y receives the message from X. 5. Y places the command in its queue of unprocessed commands. 6. Y sends a message acknowledgement to X. 7. X receives the acknowledgement from Y. 8. X clears the command from its queue of unsent commands. HOST EGM Message Sent No Acknowledgement received < 30 seconds Resend Message Update dateTimeSent Remove command in message from unsent command queue Acknowledge Message Place command in message in unprocessed command queue Figure 1.3 Message-Level Error Handling: Message Not Received gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 27 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 Acknowledgement Not Received by X This is the flow of messages when there has been an interruption in communications causing an acknowledgement to not be received. 1. X sends a message containing a command to Y. 2. Y receives the message from X. 3. Y places the command in its queue of unprocessed commands. 4. Y sends a message acknowledgement to X. 5. X does not receive the acknowledgement within 30 seconds. 6. X resends the message to Y updating the dateTimeSent. 7. Y receives the message from X. 8. Y places the command in its queue of unprocessed commands. 9. Y sends a message acknowledgement to X. 10. X receives the acknowledgement from Y. 11. X clears the command from its queue of unsent commands. HOST EGM Message Sent Acknowledge Message Command in message placed in unprocessed commands queue Acknowledgement NOT Received at HOST <30 seconds Resend Message Update dateTimeSent Clear command in message from unsent command queue Acknowledge Message Command in message placed in unprocessed commands queue Figure 1.4 Message-Level Error Handling: Acknowledgement Not Received In this case, the same command was placed on the queue of unprocessed commands twice. Application-level logic is used to detect and respond to such duplicate commands. Page 28 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.18.10.2 Error Handling – Application Level At the application level, the following error handling process should be followed to manage time-outs and command retries. Normal Command Flow This is the normal flow of command processing for a request-response pair. 1. Y receives a request command from X. 2. Y places the command in its queue of unprocessed commands. 3. Y removes the command from the queue of unprocessed commands. 4. Y verifies that the command has not expired. 5. Y verifies that the logical transaction has not been processed. 6. Y processes the command, records the transaction in its log, and places the response on its queue of unsent commands. 7. Y sends the response to X. HOST EGM Command Request Place command in unprocessed command queue Remove command from unprocessed command queue Verify command has not expired Verify logical transaction has not been processed Process command Command Response Record transaction in Log Place response in unsent command queue Figure 1.5 Application-Level Error Handling: Normal Message Flow Application-level errors may occur during the execution of a command. For example, an EGM may be trying to redeem an expired voucher. These types of errors are reported under normal command flow via the errorCode attribute of the class-level element in the prescribed response. It is possible that syntactic or semantic errors may occur in response commands. If such errors do occur and, thus, responses can not be processed, it is expected that host servers will record such commands in their exception logs. A special event, G2S_MSE001 At Least One Syntax/Semantic Command Error, has been provided for EGMs to report the receipt of a response that can not be processed due to syntactic or semantic errors. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 29 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 Expired Command Flow This is the flow of command processing for a request-response pair when a command expires before the request has been processed and the originator of the request retries the command. 1. Y receives a request command from X. 2. Y places the command in its queue of unprocessed commands. 3. Y removes the command from the queue of unprocessed commands. 4. Y determines that the command has expired. 5. Y places a "time-to-live expired" error response on its queue of unsent commands. 6. Y sends the response to X. 7. X determines that Y has not responded to the request. 8. X resends the request command to Y updating the commandId, dateTime, and sessionRetry indicator. 9. Y places the command in its queue of unprocessed commands. 10. Y removes the command from the queue of unprocessed commands. 11. Y verifies that the command has not expired. 12. Y verifies that the logical transaction has not been processed. 13. Y processes the command, records the transaction in its log, and places the response on its queue of unsent commands. 14. Y sends the response to X. See also Figure 1.6. Page 30 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 HOST EGM Command Request Place the command in the unprocessed commands queue Remove command from the unprocessed commands queue Determine command has EXPIRED Command Response Determine NO RESPONSE to command request Resend Command Request Update commandId, dateTime, sessionRetry indicator Place “time-to-live” error response in unsent command queue Place command in unprocessed command queue Remove command from unprocessed command queue Verify command has not expired Verify logical transaction has not been processed Process command Record transaction in Log Command Response Place response in unsent command queue Figure 1.6 Expired Command Flow gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 31 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 Duplicate Command Flow This is the flow of command processing for a request-response pair when the request is processed by the recipient but the response is not received by the originator within the specified time-to-live period. In this case, by checking class-specific transaction logs, the recipient of the request determines that the transaction has already been processed. 1. Y receives a request command from X. 2. Y places the command in its queue of unprocessed commands. 3. Y removes the command from the queue of unprocessed commands. 4. Y verifies that the command has not expired. 5. Y verifies that the logical transaction has not been processed. 6. Y processes the command, records the transaction in its log, and places the response on its queue of unsent commands. 7. X determines that Y has not responded to the command. 8. X resends the request command to Y updating the commandId, dateTime, and sessionRetry indicator. 9. Y places the command in its queue of unprocessed commands. 10. Y removes the command from the queue of unprocessed commands. 11. Y verifies that the command has not expired. 12. Y examines the transaction log and determines the logical transaction has already been processed. 13. Y uses the data contained in the transaction log to generate a second identical response to the command, setting the sessionRetry indicator of the response to true. 14. Y sends the response to X. See also Figure 1.7. Page 32 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 HOST EGM Command Request Place command in unprocessed command queue Remove command from unprocessed command queue Verify command is not expired Verify logical transaction has not been processed Determine NO RESPONSE to command request Process command Record event in transaction log Resend Command Request Update commandId, dateTime, sessionRetry indicator Place response in unsent commands queue Place command in unprocessed command queue Remove command from unprocessed command queue Verify command is not expired Determines logical transaction has already been processed Command Response Use data in Transaction Log to generate second identical response to the command Set sessionRetry indicator for response Record event in transaction log Figure 1.7 Duplicate Command Flow gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 33 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.18.11 Command Queues It is expected that, for each host, an EGM will maintain two command queues: a queue of inbound commands from a host and a queue of outbound commands to a host. It is also expected that host systems will maintain similar queues of commands. In both cases, the G2S protocol does not require that these queues be maintained in persistent memory. In case of a failure that causes the queues to be lost, the protocol has been designed so that, during the recovery process, critical commands can be reconstructed by the EGM from data that has been persisted at the class level. Recovery is performed at the application level on a class-by-class basis using transaction logs and other data persisted by the classes. Whenever communications is established or interrupted, an EGM is required to report an event. The EGM MUST generate a G2S_CME122 Comms Transport Down event when it determines that communications have failed. It MUST generate a G2S_CME121 Comms Transport Up event when it determines that communications have been restored. It MUST generate a G2S_CME102 Comms Outbound Overflow event when it determines that no additional commands can be placed on the queue of outbound commands. These events MUST be processed and, as appropriate, passed to the event handlers for further processing. If the queue of inbound commands is full, the recipient of a message MUST respond to the originator of the message with error G2S_MSX006 Inbound Command Queue Full in its g2sAck response. After receiving such an error, the originator of the original message MUST wait until its normal resend timer has expired and then resend a new message. The commands contained within the original message MUST NOT be discarded. The commands MUST be included in subsequent messages. If the inbound queue of a communications device for an EGM becomes full, the EGM MUST generate a event. If the inbound queue and outbound queue are both full, the EGM MUST assume that a communications failure has occurred. At that time, the EGM MUST restart the affected communications device by transitioning it to the closing state. G2S_CME104 Comms Inbound Overflow A host may utilize the keepAlive command to test the communications channels between the host and an EGM. By default, a keepAlive command is not sent. The keepAlive interval can be modified on a host-byhost basis. A host may also choose to send keepAlive commands to an EGM. A host may send these commands at any frequency that it chooses. See Chapter 2 for more information on these communications class events and commands. 1.18.12 Communications States Each communications device contains five attributes that are used to describe its current status: egmEnabled, hostEnabled, outboundOverflow, inboundOverflow and commsState. These attributes are contained in the commsStatus command within the communications class. The transport layer is responsible for delivering commands to/from a host. While there is an interrelationship between the transport layer and the communications device, within the G2S protocol they are viewed as independent activities. For convenience, the status of the transport mechanism is reflected in the transportState attribute of the commsStatus command. The value of this attribute is managed independently of the communications device itself. It is used to trigger transport-related events that are reported through the communications device. 1.18.12.1 Status Attributes The egmEnabled attribute indicates whether the communications device can accept and receive messages from the host. For this attribute to be set to true, both the inbound and outbound command queues for the host MUST be ready to accept application-level commands. If the queues are not ready to accept application-level commands then no communications can take place and the egmEnabled attribute MUST be set to false. Page 34 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 1 g2sMessage The hostEnabled attribute indicates whether EGM-originated requests should be placed in the outbound queue to the host. When the attribute is set to false, the EGM MUST only place responses to host-originated requests in the outbound queue. The only exception to this rule are the commsOnLine and commsDisabled commands. When required, the EGM MUST always place commsOnLine and commsDisabled commands in the outbound queues. The outboundOverflow attribute indicates whether the outbound queue is full, preventing additional commands from being added to the queue. When the attribute is set to true, the EGM cannot place any additional commands on the outbound queue. The inboundOverflow attribute indicates whether the inbound queue is full, preventing additional commands from being added to the queue. When the attribute is set to true, the EGM cannot place any additional commands on the inbound queue. The commsState attribute identifies the current state of the communications device: closed, onLine, overflow or closing. 1.18.12.2 opening, sync, Communications State Descriptions The communications device is in the closed state if its inbound and outbound queues are not ready to accept application-level commands, i.e. the egmEnabled attribute is set to false. While in this state, no inbound or outbound communications can take place. The device enters this state when the EGM restarts. It will also transition to this state from the closing state. Once the communications device has been initialized (as described above), the EGM MUST generate event G2S_CME002 Comms Enabled by EGM and then transition to the opening state. When entering the opening state, the EGM MUST place a commsOnLine request in the outbound queue. The communications device is in the opening state until it has received a commsOnLineAck response to a commsOnLine request. While in this state, the EGM MUST not place any commands, other than commsOnLine commands, in the outbound queue. Periodically, the EGM MUST retry the commsOnLine request. After receiving a commsOnLineAck response, the EGM MUST generate event G2S_CME100 Comms Established and then transition to the sync state. The communications device is in the sync state until it has received a setCommsState request from the host with the enable attribute set to true. While in this state, the host has an opportunity to query the device structure of the EGM and set its subscriptions before normal communications resume. When entering this state, the EGM MUST place a commsDisabled request in the outbound queue. A commsDisabledAck response is required from the host. While in this state, the EGM MUST place responses to host-originated requests in the outbound queues. The EGM MUST NOT place any EGM-originated requests, other than commsDisabled requests, in the outbound queues. Periodically, the EGM MUST retry the commsDisabled request. After receiving a setCommsState request from the host with the enabled attribute set to true, the EGM MUST generate event G2S_CME004 Comms Enabled by Host and then transition to the onLine state. The communications device is in the onLine state while the egmEnabled and hostEnabled attributes are set to true and the overflow attribute is set to false. While in this state full bi-directional communications may take place. While in this state, the EGM MUST place all EGM-originated requests as well as responses to hostoriginated requests in the outbound queue. The communications device is in the overflow state if its outbound queue becomes full. While in this state, the EGM is unable to place any commands in the outbound queue. Critical events and transactions will be persisted within individual classes and will be recovered by the normal retry mechanism once the overflow condition is cleared. When entering this state, the EGM MUST generate event G2S_CME102 Comms Outbound Overflow. Once the outbound queue is cleared, the EGM MUST generate event G2S_CME103 Comms Outbound Overflow Cleared, and then transition to the onLine state. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 35 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 The communications will enter the closing state whenever it is necessary to restart communications with the host. This can happen when there is a configuration change, when error G2S_MSX003 Communications Not Online is sent to the EGM by the host, etc. The communications device remains in the closing state until it has received a commsClosingAck response to a commsClosing request or it has been in the closing state for 30 seconds, whichever comes first. While in this state, the EGM is trying to notify the host that it will be closing the communications device. While in this state, the EGM MUST place responses to host-originated requests in the outbound queues. The EGM MUST NOT place any EGM-originated requests in the outbound queues. After receiving the commsClosingAck response to the commsClosing request or it has been 30 seconds since entering the closing state, whichever comes first, the EGM MUST generate event G2S_CME001 Comms Disabled by EGM, and then transition to the closed state. See Chapter 2 for more information on these communications class events and commands. 1.19 Multicast Format The g2sMulticast element contains a set of attributes that identify the sender, the intended receivers and the date/time of a message. It also contains the application-level commands contained in class-level sub-elements. There is no message-level acknowledgement for multicast messages. Ignoring the attributes for a moment, the following example highlights the structure of a G2S multicast message: <g2sMessage> <g2sMulticast> <anyClassMulticast> <anyCommand /> </anyClass> <anyClass> <anyCommand /> </anyClassMulticast> </g2sMulticast> </g2sMessage> // Message Level // Class Level // Application Level // Class Level // Application Level In the above examples, anyClassMulticast and anyCommand are not actual G2S elements. They are used as an example to demonstrate how messages are constructed within the G2S protocol. The anyClassMulticast element represents the standard class-level element used for command routing, with "Multicast" appended to indicate that multicast processing is required. The anyCommand element represents an application-level classspecific function. Multicast application-level commands are always constructed in this way. When the multicast format is used, commands are not directed at a single device within a single EGM. Instead, commands are directed at a multicast group identifier (or, more simply, multicast identifier). As described previously, in Section 1.17, one or more devices may be joined to a multicast group. All of the commands within a multicast message are passed to all of the devices joined to a multicast group. At the application-level, reference values contained within the commands, e.g. progressive identifier and progressive level, may be used by a device to identify which commands are relevant to that device. Such filtering is done at the application level, not the message level. Multicast messages may be sent over the same transport as point-to-point messages. Alternatively, a multicast transport may be used. Multicast transports may be configured locally at the EGM or remotely by a configuration server. A multicast transport is activated when the first device is joined to a multicast group and it is deactivated when the last device is unjoined — that is, removed — from a multicast group. Commands within the communications class are used to join devices to multicast groups. At the time a host makes such a request, the host must specify the multicast identifier that it intends to use as well as other transport-related communications and security parameters. To avoid duplicates, when constructing multicast identifiers, host systems MUST follow the G2S naming conventions for unique identifiers (see Section 1.11 on unique identifiers). Page 36 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 See Chapter 2 for information on multicast configuration and operation in the communications class. 1.19.1 g2sMulticast Element The g2sMulticast element contains a set of attributes that identify the multicast message. These attributes include the host identifier, the multicast identifier and the date and time that the message was sent. All of these attributes are required. Table 1.7 g2sMulticast Attributes Attribute Restrictions Description hostId type: deviceId use: required Host identifier assigned by the gaming network administrator. multicastId type: multicastId use: required Multicast identifier assigned by the host. dateTimeSent type: dateTime use: required Actual date and time that the message was sent. The following example highlights the attributes of the g2sMulticast element: <g2sMulticast hostId = "1" multicastId = "GSA_Progressive" dateTimeSent = "2005-12-10T10:54:27.123-05:00" > The g2sMulticast element also contains the application-level commands included in the message. A single g2sMulticast element may contain multiple application-level commands. Like the class-level elements used with g2sBody, there is also a standard set of class-level attributes that directs the processing of multicast application-level commands. However, these attributes do not identify the specific device to which an application-level command should be directed. All commands within a multicast message are passed to all devices joined to a multicast group. The EGM MAY use reference values within an application-level command to identify the set of devices affected by the command. For example, an EGM must use the progressive identifier and progressive level within a progressive update command to identify the progressive devices that should receive the update. 1.19.2 Multicast Class-Level Attributes A single g2sMulticast element may contain multiple application-level commands. Each application-level command is contained within a class-level element that contains a standard set of attributes that direct the processing of the application-level command. All classes use the same set of class-level attributes. The name of the class plus the "Multicast" designator is used as the element name for the class-level element, e.g. progressiveMulticast, bonusMulticast, etc. Thus, the name of the class-level element identifies the class to which the command belongs and specifies that multicast processing is required. Each application-level command is atomic, meaning that commands are not grouped into transactions. No transaction support is implied. Each command is processed independently of all other commands. The processing order for commands is at the discretion of the receiver of the commands. See Section 1.19.2.2 below for additional ordering restrictions on the contents of g2sMulticast elements. 1.19.2.1 Command Identification Attributes The standard set of class-level attributes starts with a set of attributes used to identify and sequence commands. These attributes include the date/time that the command was originated and the command identifier of the command. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 37 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 The command identifier is assigned by the originator of a command. It is used to uniquely identify an individual command and to sequence commands originating from a host. Each multicast group MUST use its own sequence. The command identifier MUST be a monotonically-increasing sequence that can be used to determine the order of commands. Table 1.8 Standard Multicast Command Identification Attributes Attribute Restrictions Description dateTime type: dateTime use: required Date and time that a command was originated. commandId type: commandId use: required Unique command identifier assigned by the originator of a command. 1.19.2.2 Processing Order Commands MUST be sent in commandId order. When multiple commands are contained in a single g2sMulticast message, the commands MUST be organized in ascending commandId order within the g2sMulticast message – the lowest commandId appearing within the first command element. This requirement is designed to help expedite the processing of commands by not requiring that the recipient sort and order commands prior to processing. Sorting and ordering is the originator’s responsibility. In general, the commandId order should represent the natural order that commands occurred and the natural order that they should be processed. The recipient may process commands contained within its queue of unprocessed commands in any order it chooses. However, it is anticipated that EGMs will normally process commands in commandId order. The only time that this may not be true is when a command cannot be processed because a critical resource is temporarily unavailable. While the protocol allows this behavior, before adopting it, implementers MUST make sure processing a specific command out of order will not jeopardize the integrity of an application. 1.19.3 Multicast Example The following example highlights the contents of a complete multicast message: <g2sMulticast hostId = "1" multicastId = "GSA_Progressive" dateTimeSent = "2005-12-10T10:54:27.123-05:00" > <progressiveMulticast dateTime = "2004-02-27T13:47:31.321-05:00" commandId = "2002" > <setProgressiveValue> <setLevelValue progId = "17" levelId = "1" progValueAmt = "123450000" progValueText = "" progValueSeq = "100" /> <setLevelValue progId = "18" levelId = "2" progValueAmt = "25000000" progValueText = "" progValueSeq = "101" /> <setLevelValue progId = "19" levelId = "3" progValueAmt = "1000000" progValueText = "" progValueSeq = "102" /> </setProgressiveValue> </progressiveMulticast> </g2sMulticast> Page 38 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1.20 Chapter 1 g2sMessage EGM Restart, Recovery & Activation The processes of restarting an EGM, recovering transactions, and then activating game play are complex and interrelated processes. This section discusses each process, their interrelationships, and their effect on host communications. Further information on this subject can be found in the chapters about the commConfig, optionConfig and communications classes. 1.20.1 EGM Restart When an EGM restarts after an outage, the EGM must decide whether to use its default configuration or its last-known configuration. The default configuration is typically burned into the EGM’s software or it is contained in a special configuration file prepared by the manufacturer. During normal operations, operators may change the configuration of the EGM to meet their specific needs. To the extent that the configuration contains options that are specified or manipulated by the G2S protocol, the EGM MUST store this last-known configuration in persistent memory. There is no requirement that the EGM persist configuration options that are not specified or manipulated by the G2S protocol. The option whether to use the last-known configuration or the default configuration is set on a device-bydevice basis. The useDefaultConfig attribute of each device’s configuration is used for this purpose. If the attribute is set to true then the default configuration for the device is used when the EGM restarts. If the attribute is set to false then the last-known configuration for the device is used. The EGM configuration includes the list of registered hosts for the EGM as well as device-owner assignments. The communications queues used by the EGM to send and receive commands from a host are dependent on this configuration. If the configuration changes then the communications queues may no longer be valid and the contents of the queues may be meaningless. Thus, whenever the list of registered hosts or the device-owner assignments change, the EGM MUST clear its communications queues (except as noted below), re-establish communications, and recover incomplete transactions for any host affected by the changes. The EGM MUST send a commsOnLine command to each affected host when this condition occurs. The protocol does not require or expect that communications queues will be persisted. This is simply an implementation option. If the EGM does persist its communications queues, then the EGM MUST verify that its registered hosts and device-owner assignments are consistent with the persisted communications queues. If not, as noted above, the EGM MUST clear its communications queues and recover incomplete transactions for any affected hosts. 1.20.2 EGM Recovery To comply with jurisdictional requirements, an EGM must maintain certain critical transactions in persistent storage until they are transmitted to a host. In many classes, such as voucher, WAT, progressive, bonus, handpay and player, the G2S protocol specifies the exact contents and processes used to maintain the logs. In classes that support multiple devices, such as progressive and bonus, the EGM MUST maintain a single log for all devices within the class. Each log entry may contain one or more attributes that indicate whether the owner of the device acknowledged a specific phase of a transaction. The recovery process uses these attributes to determine which commands an EGM should retry to complete the transactions. During the recovery process, if a transaction has not been acknowledged, the EGM MUST retry the commands necessary to complete the transaction. The recovery process for all devices MUST start as soon as possible after an EGM restarts, after a device is reenabled after being disabled, and after the owner of a device has been reassigned. It is possible that an EGM may restart with its default configuration or with an out-of-date configuration. Thus, it is possible that, upon restart, commands may be directed at a host that does not support a particular application. If a host receives such commands, it should record the commands in an exception log. The host MUST NOT send the gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 39 G2S™ Message Protocol v1.0.3 Chapter 1 g2sMessage prescribed response to a command for an application that it does not support. The EGM MUST be forced to retry the commands until its configuration has been updated to direct the commands at the correct host. In general, when a log becomes full, the EGM MUST discard the oldest entry in the log. An EGM MUST NOT discard an entry that has not been acknowledged. Thus, if the oldest entry in a log is an unacknowledged entry, the EGM MUST NOT discard the entry and the EGM MUST NOT initiate any more transactions for the affected device. In this situation, the EGM MUST disable the affected device. Depending on the EGM’s configuration, this may cause the EGM itself to be disabled from play. Other special handling, e.g. overwriting the oldest transaction, MAY be specified on a class-by-class basis. When this is the case, the class description will include a discussion of the special handling. 1.20.3 EGM Activation Before an EGM can be played, a minimum number of devices must be enabled. The list of devices that are required before an EGM can be played will vary based on jurisdictional and operator needs. If the optionConfig class is being used, the requiredForPlay attribute of each device indicates whether the device MUST be functioning and enabled before the EGM can be played. All devices that have the requiredForPlay attribute set to true MUST be enabled and functioning before an EGM can be played. If at any time, any of the devices is disabled or not functioning, the EGM MUST invoke its disable logic, possibly stopping game play and cashing out the player. An EGM determines whether a device is functioning by running a self-test of the device. As long as the device is functioning properly and can perform the functions required by the EGM, the EGM MUST set the egmEnabled attribute of the device’s status to true. This attribute is used to tell the host that the device is available and ready for use. The host uses the setClassState command to tell the EGM whether the host wants a device to be enabled. This command controls the hostEnabled attribute of the device’s status. If the requiredForPlay attribute has been set for a device, both the egmEnabled and hostEnabled attributes for the device MUST be set to true before the EGM can be played. If at any time, the egmEnabled or hostEnabled attribute of a device becomes false and the requiredForPlay attribute for the device is set to true, the EGM MUST invoke its disable logic. For the purposes of this discussion, all devices within the meters and gat classes are always considered both egmEnabled and hostEnabled and, thus, do not affect whether an EGM can be played. The egmEnabled, hostEnabled, and requiredForPlay attributes are not used with those classes. Similar to other classes, the setClassState command appears within the deviceConfig, commConfig and optionConfig classes. However, the behavior expected in these classes is different than in other classes. In the deviceConfig, commConfig and optionConfig classes, like other classes, the setClassState command manipulates the hostEnabled attribute of the device status. However, when the hostEnabled attribute is set to false, the EGM MUST invoke its disable logic, regardless of the state of any other device. An EGM can always be disabled by manipulating this attribute. The requiredForPlay attribute is not used with the deviceConfig, commConfig and optionConfig classes. When an EGM restarts, the EGM MUST run a self-test of each device and set each device’s egmEnabled attribute appropriately. After the EGM has run a self-test of each device, based on its configuration, the EGM MUST set the hostEnabled attributes for each device. Once the egmEnabled and hostEnabled attributes have been set, the EGM MUST evaluate which devices are requiredForPlay and whether those devices are egmEnabled and hostEnabled. If all devices that are requiredForPlay are both egmEnabled and hostEnabled, the EGM may resume game play. If the optionConfig class is being used, the restartStatus attribute of each device indicates whether the device should be enabled or disabled when the EGM restarts and, thus, controls the initial value of the hostEnabled attribute. When an EGM restarts, the restartStatus tells the EGM whether the device should be hostEnabled. Page 40 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 Prior to an EGM restarting, a host may have locked or disabled a device. As described above, upon restart, the hostEnabled attribute of a device MUST be set based on the restartStatus for the device. The hostLocked attribute MUST be set to false. All host locks are cleared upon restart. 1.20.4 EGM Deactivation If, at any time, one of the devices that are requiredForPlay is no longer egmEnabled and hostEnabled, the EGM MUST invoke its disable logic and disable game play. If a game is in progress, the EGM MUST complete the game before the EGM is disabled. When an EGM is disabled, typically, the EGM will be required to cash-out the player, not accept any additional buy-ins, and not commence any new games. EGM configuration options indicate whether the EGM can use WAT, vouchers, notes, coins and/or handpays to cash-out the player. Before attempting to use a device for a cash-out, the EGM MUST check to make sure the device is still enabled. The recommended cash-out sequence is WAT, voucher, note, coin, and then handpay. If a required device is not available or the normal cash-out controls prohibit the use of a device, the EGM MUST NOT use the device to cash-out the player. 1.20.5 Affects Of Disabling Devices The following table identifies the affects of disabling certain devices. Table 1.9 Effect of Disabling Devices Device Effect Of Disabling Device cabinet Player-interface devices and peripherals not covered in other classes are disabled; effectively stops all activity at the EGM. game play Individual game is disabled; game cannot be played. coin acceptor Coin acceptor is disabled; coins cannot be accepted. hopper Hopper is disabled; coins cannot be dispensed. note acceptor Note acceptor is disabled; notes cannot be accepted, voucher transactions may be limited. note dispenser Note dispenser is disabled; notes cannot be dispensed. printer Printer is disabled; voucher and WAT transactions may be limited. handpay Remote key-offs are disabled; only local key-offs are permitted. progressive Games associated with the progressive are disabled and cannot be played. bonus EGM is not participating in bonus activity; optionally, game play may be disabled; status MUST be clearly displayed to the player. player Player tracking functionality is disabled; status MUST be clearly displayed to the player. voucher Voucher functionality is disabled. Note that for enabled voucher devices, functionality may be constrained if the printer or note acceptor is disabled. WAT WAT functionality is disabled. Note that for enabled WAT devices, functionality may be constrained if the printer is disabled. device config EGM is disabled from play; all other classes are effectively disabled. option config EGM is disabled from play; all other classes are effectively disabled. comm config EGM is disabled from play; all other classes are effectively disabled. communications EGM-originated requests and notifications will not be placed in the outbound queues; host originated commands will be processed and responses added to the outbound queue. event handler The eventHandler device is disabled; no events will be added to the event log or the outbound queue. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 41 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.20.6 Restart Sequence The following sequence demonstrates the various tasks in the restart/recovery process for an EGM. Other sequences are possible. 1. The EGM runs a self-test of all devices setting the egmEnabled attribute of each device. 2. The EGM loads its restart configuration (last-known or default depending on the value of the useDefaultConfig attribute) from persistent memory. 3. The EGM sets the hostEnabled attribute of each device based on the restartStatus attributes of the configuration. 4. The EGM initializes the inbound and outbound communications queues for each host, setting the communications status to G2S_opening. 5. The EGM places a commsOnLine command in the outbound queue of each host. 6. For each host, the EGM sends a message containing the commsOnLine command, waiting for a commsOnLineAck response from the host. 7. For each host, after the EGM receives the commsOnLineAck response from the host, the EGM sets the communications status for the host to G2S_sync. 8. For each host, after the host has set it subscriptions, the host sends a setCommsState command to the EGM and the EGM responds with a commsStatus command, setting the communications status to G2S_onLine. 9. The EGM recovers any unacknowledged events from its logs, generating the appropriate commands for the host. 10. The EGM recovers any incomplete transactions from its logs, generating the appropriate commands for the host. 11. If all requiredForPlay devices are egmEnabled and hostEnabled, the EGM commences game play. See also Figure 1.8. Page 42 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 HOST EGM Run self test on all devices, set egmEnabled attribute for each device Load restart configuration from persistent memory Set hostEnabled attribute for each device based on restartStatus attributes in configuration Send commsOnLine command Send commsOnlineAck response Initialize inbound and outbound communications queues for each host, set communications status to offLine Place commsOnLine command in outbound queue of each HOST Set HOST communication status to G2S_sync Send setCommsState command Send commsStatus response Set HOST communication status to G2S_online Recover unacknowledged events from logs, generate appropriate commands for HOST Recover incomplete transactions from logs, generate appropriate commands for HOST If ALL requiredForPlay devices are egmEnabled and hostEnabled, commence play Figure 1.8 EGM Restart Sequence Periodically, the EGM will retry unacknowledged events and incomplete transactions, placing appropriate commands in the outbound communications queues of each host with the communications status set to G2S_onLine. The EGM will not place such commands in the outbound communications queue if the communications status is not G2S_onLine. When restarting, the EGM will apply the event subscriptions contained in its initial configuration to new events generated by the EGM, placing appropriate commands in the outbound communications queue of each onLine host. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 43 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.21 Persistent Memory The G2S protocol requires that an EGM maintain certain critical protocol-related data in persistent memory including meters, transaction logs and configuration data. If persistent memory fails or is reset by the operator, certain critical information may be lost. If this happens, the EGM MUST notify all affected hosts. For this reason, the commsOnLine command contains a series of attributes that indicates whether persistent memory may have been compromised. The EGM MUST set the deviceReset attribute to true if the device structure of the EGM has been reset—that is, devices may have been renumbered. The EGM MUST set the deviceChanged attribute to true if one or more devices have been added or removed from the EGM. The EGM MUST set the subscriptionLost attribute to true if the meter or event subscriptions of the host have been lost. The EGM MUST set the metersReset attribute to true if the meters for one or more devices have been reset. The EGM MUST also set these attributes to true when it first initiates communications with a host. If the EGM has no record of ever communicating with a host then these attributes MUST be set to true in the initial commsOnLine command to the host. This would be the case any time a new host is added to the EGM or the transport location of a host is changed. The EGM MUST keep these attributes set to true until the affected host responds to the commsOnLine with a commsOnLineAck response. The commsOnlineAck response acknowledges that the host is aware that persistent memory may have been compromised. When a host receives a commsOnLine command with the deviceReset attribute set to true, the host MUST assume that the device identifiers, transaction identifiers, event identifiers, meters, transaction logs and configuration data of the EGM may have been compromised. For this reason, it may be simplest for a host to create a new instance of the EGM for tracking and reporting purposes. After sending the commsOnLineAck response to the commsOnLine command, a host may query the EGM to determine the current state of its devices. A host may also set its meter and event subscriptions. The EGM does not start the restart/recovery process for a host until setCommsState command with the enabled attribute set to true has been received. This gives the host an opportunity to interrogate the EGM and make any critical changes before commencing normal communications. Page 44 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1.22 Namespaces and Protocol Extensions 1.22.1 Namespaces Chapter 1 g2sMessage The G2S schema has a target namespace defined that includes a version number. In an effort to provide backward compatibility, whenever something is added or changed the new or modified element will exist within a new versioned namespace, and all unmodified items will still reside within the base target namespace. If, in a future release, backward compatibility is not required, the major number of the version in the target namespace will be incremented and all the elements will fall under a new target namespace. 1.22.2 1.22.2.1 Protocol Extensions Introduction It is possible that a manufacturer has requirements that are not met by the G2S specifications. There are four main places the protocol can be extended, and this document is meant to provide examples for each. The four points of extension are as follows: 1. New classes can be added. 2. New commands can be added to existing classes. 3. New attributes can be added to existing commands. 4. New values can be added to enumerations. When adding classes, commands, attributes or enumerations, it is imperative that the new items belong to a unique manufacturer namespace. The only constraint on this namespace is that it does not clash with any existing namespaces. When adding values to enumerations the 3-character GSA assigned identifier must be used as a prefix to the new value, for example IGT_myEnumValue. There is a limitation of XSD 1.0 in that if you allow an alternate namespace at the element level then all other namespaces will come through. Currently there is not a fix for this problem. It will be fixed in XSD 1.1. However, a work-around is to incorporate a preprocessing filter to eliminate any unintended namespaces. It is important to note that this does not affect alternate namespaces at the attribute level where XSD filtering works as expected. It is the intent of the G2S protocol to allow class and command elements from namespaces other than the G2S target namespace to pass through to the application level. Typically, an application will respond with an error when such elements are encountered – G2S_APX007 Class Not Supported or G2S_APX008 Command Not Supported, as appropriate. For this reason, the G2S schemas have been constructed to allow class and command elements from namespaces other than the G2S target namespace to bypass schema validation tests. For all intents and purposes, this means that those elements from other namespaces are not validated against any schema and are simply passed as raw text to the application. In fact, given the limitations of XSD 1.0, it is not possible to construct a valid set of schemas that will validate messages against the G2S target namespace plus other known namespaces and still allow elements from unknown namespaces to bypass schema validation tests. For this reason, if schema validation of elements from other known namespaces is desired and application-level processing of elements from unknown namespaces is desired (i.e. pre-processing filters are not used), those elements MUST be validated in a second pass following initial validation against the G2S target namespace. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 45 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.22.2.2 Adding a New Class A new class can be added to the GSA specification by manufacturers as long as they adhere to a couple of simple rules: the class must be contained within a unique namespace, and the base of the new class must derive from the G2S defined baseClass. The following diagram illustrates a class that defines two commands: In this example the target namespace for the schema defining the class is defined as "http://www.MyCompany.com" thus ensuring uniqueness. The following XML sample shows what a command from this class will look like: <g2s:g2sMessage xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:g2s = "http://g2s.gamingstandards.com" xmlns:myco = "http://www.MyCompany.com" > <g2s:g2sBody g2s:hostId = "1" g2s:egmId = "GSA_12345" g2s:dateTimeSent = "2007-03-12T10:44:00-05:00" > <myco:MyClass g2s:deviceId = "1" g2s:dateTime = "2001-12-17T09:30:47-05:00" g2s:commandId = "1" g2s:sessionType = "G2S_request" g2s:sessionId = "0" g2s:sessionRetry = "false" g2s:sessionMore = "false" g2s:timeToLive = "30000" > <myco:awardMoney myco:amount = "100000000" /> </myco:MyClass> </g2s:g2sBody> </g2s:g2sMessage> If the GSA decides to adopt this class and make it part of the standard, the new namespace will be dropped in favor of the GSA namespace. Page 46 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1.22.2.3 Chapter 1 g2sMessage Adding Commands to Existing Classes In much the same way as adding a new class, a new command can be added to an existing class. The new command must exist within a unique namespace. If you are using code generators, you may need to modify the schema for the class you are extending in order to include the new method. The following is an example of a command that is added using a manufacturer extension: <g2s:g2sMessage xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:g2s = "http://g2s.gamingstandards.com" xmlns:myco = "http://www.MyCompany.com" > <g2s:g2sBody g2s:hostId = "1" g2s:egmId = "GSA_12345" g2s:dateTimeSent = "2007-03-12T10:44:00-05:00" > <g2s:eventHandler g2s:deviceId = "1" g2s:dateTime = "2001-12-17T09:30:47-05:00" g2s:commandId = "1" g2s:sessionType = "G2S_request" g2s:sessionId = "0" g2s:sessionRetry = "false" g2s:sessionMore = "false" g2s:timeToLive = "30000" g2s:errorCode = "AAA_A" g2s:errorText="String" > <myco:getLastEvent myco:deviceClass = "G2S_communications" myco:deviceId = "-1" /> </g2s:eventHandler> </g2s:g2sBody> </g2s:g2sMessage> If it is decided that this command should be added to the core G2S classes it will be incorporated directly into the G2S schemas and the unique namespace will no longer be required. 1.22.2.4 Adding Attributes to Commands Like the previous two examples, a new attribute must be within its own namespace. If you are using code generators, once again it may be necessary to modify the existing G2S schemas to include the new attribute. The following is an example of an attribute that has been added to a command using a manufacturer extension: <g2s:g2sMessage xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:g2s = "http://g2s.gamingstandards.com" xmlns:myco = "http://www.MyCompany.com" > <g2s:g2sBody g2s:hostId = "1" g2s:egmId = "GSA_12345" g2s:dateTimeSent = "2007-03-12T10:44:00-05:00" > <g2s:eventHandler g2s:deviceId = "1" g2s:dateTime = "2001-12-17T09:30:47-05:00" g2s:commandId = "1" g2s:sessionType = "G2S_request" g2s:sessionId = "0" g2s:sessionRetry = "false" g2s:sessionMore = "false" g2s:timeToLive = "30000" g2s:errorCode = "AAA_A" g2s:errorText = "String" > <g2s:setEventHandlerState g2s:enable = "true" g2s:disableText = "String" myco:shutdown = "true" /> </g2s:eventHandler> </g2s:g2sBody> </g2s:g2sMessage> As with new commands, new attributes may become part of the standard. If this is the case, it will be included in the main schemas and the manufacturer namespace will no longer be needed. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 47 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.22.2.5 Adding Items to Enumerations When adding items to an enumeration the manufacturer must follow the syntactic rules set forth by the GSA. The format for an enumeration item is the 3-character manufacturer identifier followed by an underscore, followed by the enumeration name. If you are using code generators, the new enumeration items should be added in a separate namespace and then integrated with the G2S schemas. The following is an example of a message with a manufacturer defined item passed in an enumeration: <g2s:g2sMessage xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:g2s = "http://g2s.gamingstandards.com" xmlns:myco = "http://www.MyCompany.com" > <g2s:g2sBody g2s:hostId = "1" g2s:egmId = "GSA_12345" g2s:dateTimeSent = "2007-03-12T10:44:00-05:00" > <g2s:cabinet g2s:deviceId = "1" g2s:dateTime = "2001-12-17T09:30:47-05:00" g2s:commandId = "1" g2s:sessionType = "G2S_request" g2s:sessionId = "0" g2s:sessionRetry = "false" g2s:sessionMore = "false" g2s:timeToLive = "30000" g2s:errorCode = "AAA_A" g2s:errorText = "String" > <g2s:cabinetProfile g2s:machineNum = "0" g2s:machineId = "String" g2s:currencyId = "Str" g2s:reportDenomId = "99999999" g2s:localeId = "String" g2s:areaId = "String" g2s:zoneId = "String" g2s:bankId = "String" g2s:egmPosition = "String" g2s:machineLoc = "String" g2s:cabinetStyle = "ABC_mini" /> </g2s:cabinet> </g2s:g2sBody> </g2s:g2sMessage> Like the rest of the extensions, this enumeration member may be added to the standard; if it is, the prefix will be changed to the standard G2S_ and the item will become part of the core schemas. Page 48 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.23 Data Types The following table lists the data types specific to the g2sMessage, g2sBody and g2sAck elements. See A for additional global data types. Table 1.10 Data Types Specific to the g2sMessage, g2sBody and g2sAck Elements Data Type Restrictions Description sessionTypes type: string enumerations: G2S_request G2S_response G2S_notification Command type. errorCode type: uniqueIdentifier10 minLen: 10 maxLen: 10 Error code. errorText type: string minLen: 0 maxLen: 256 Error text. commandId type: long minIncl: 1 Command identifier. sessionId type: long minIncl: 0 Session identifier. timeToLive type: milliseconds minIncl: 0 Time to live duration in milliseconds. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 49 Chapter 1 g2sMessage G2S™ Message Protocol v1.0.3 1.24 Error Codes The following table lists the message-level error codes for the G2S protocol: Table 1.11 Message-Level Error Codes for G2S Protocol Error Code Suggested Error Text G2S_MSX001 Incorrect hostId Specified G2S_MSX002 Incorrect egmId Specified G2S_MSX003 Communications Not Online G2S_MSX004 Incomplete/Malformed XML G2S_MSX005 Invalid Data Type Encountered G2S_MSX006 Inbound Command Queue Full G2S_MSX007 Commands Not In commandId Order The following table lists the application-level error codes common to all classes within the G2S protocol (See also Appendix A for global error codes): Table 1.12 Application-Level Error Codes Common to All Classes within the G2S Protocol Error Code Suggested Error Text (Notes) G2S_APX001 Invalid Host Identifier G2S_APX002 Invalid EGM Identifier G2S_APX003 Invalid Device Identifier G2S_APX004 Incomplete/Malformed XML G2S_APX005 Invalid Data Type Encountered G2S_APX006 Invalid sessionType Specified G2S_APX007 Class Not Supported G2S_APX008 Command Not Supported G2S_APX009 Command Contained At Least One Syntax/Semantic Error G2S_APX010 Command Restricted To Owner G2S_APX011 Time-to-live Expired G2S_APX012 Command Restricted To Owner and Guests G2S_APX013 Command Not In commandId Order G2S_APX999 (Undefined Error - Error Text is Used to Describe the Error Condition)* * Page 50 Implementers must make every effort to use defined error codes where available. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 1.25 Chapter 1 g2sMessage Event Codes The following table lists events that are common to all classes of commands within the G2S protocol: Table 1.13 Application-Level Event Codes Common to All G2S Classes Event Code Event Description G2S_APE001 At Least One Syntax/Semantic Command Error G2S_APE002 Invalid sessionId Received In Response 1.25.1 G2S_APE001 At Least One Syntax/Semantic Command Error There are no device, meter, log changes or related commands associated with this event. 1.25.2 G2S_APE002 Invalid sessionId Received In Response There are no device, meter, log changes or related commands associated with this event. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 51 G2S™ Message Protocol v1.0.3 Page 52 Chapter 1 g2sMessage gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 2 communications Class 2.1 Introduction Chapter 2 communications Class The communications class encompasses a set of messages used to monitor and control communications between the EGM and host systems. The communications class is a multi-device class. An EGM may support communications to more than one host. The host associated with a particular communications device is the owner of that device. Other hosts may be configured as guests and may subscribe to the communications events of the device. Inactive devices may be exposed through the commConfig class. A communications device is created to manage the communications between an EGM and a single host. The EGM learns which hosts it will communicate with through configuration information. This configuration information provides a set of hostIds and the EGM creates a device for each host using the hostId as the deviceId. A deviceId of 0 (zero) is reserved for the class level commands. The hostIds are assigned by the operator, either locally at each EGM’s administrative interface or centrally at the configuration server. Commands within the communications class can be used to determine the full list of hosts communicating with an EGM. These commands can also be used to get the descriptions of all the devices on the EGM. The communications device manages two communication services: point-to-point and multicast. The pointto-point service is the primary means for configuration control, transactions, information exchanges, and event reporting. The multicast service is used by a host to send messages to a plurality of EGMs. The configuration of an EGM may be changed locally by an administrative person or the EGM itself, or it may be changed remotely by host or administrator. The current point-to-point communications will be closed and restarted whenever a configuration change occurs. As part of restarting the communications, the EGM will provide an indication of what has changed. This is described further in sections 2.3 Point-to-Point Communications and 2.11 commsOnLine Command. 2.2 Sending, Resending and commandIds Each communications device in the EGM MUST provide its own commandId to label the outgoing commands to the owner host of the communications class. The owner host MUST provide its own commandId for labeling commands to the communications device in the EGM. The communications device starting commandId value MUST be communicated to the owner host in the commsOnLine command. The owner host starting commandId value MUST be communicated in the commsOnLineAck command. The commandId value MUST be a monotonically-increasing sequence starting at 1 (one). Each command MUST be labeled with the current commandId when it is queued for sending. Because the commandId MUST be monotonically increasing as commands are sent, if a command is resent, the commandId MUST be set to the current commandId value. In other words, the resent command MUST be assigned a new commandId. Hosts and EGMs MAY persist the counters used to generate command identifiers across connections. For EGMs, the commsOnLine command implies that the counters may have been reset. However, a reset is not required. See Chapter 1 for more information on sending, resending, and commandIds. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 53 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.3 Point-to-Point Communications Point-to-Point communications revolves around the concept of an association between a communications device and an owner host. As long as an association has been established and is active, a communications device and owner host MAY exchange messages, including requests, responses, notifications and events. The following state diagram models the expected behavior of a communications device at the EGM. The text that follows describes the states and lists the required behavior. Page 54 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 EGM Restart K J closed closing commsClosing A I opening E H commsOnLine B sync E G H commsDisabled C onLine D G H E F overflow D G H A B C D Queues initialized. egmEnabled = true. Event: Comms Enabled By EGM. commsOnLineAck received. Event: Comms Established. setCommsState = true received. hostEnabled = true. Event: Comms Enabled By Host. setCommsState = false received. hostEnabled = false. Event: Comms Disabled By Host. E F G H L Outbound queue overflow. outboundOverflow = true. Event: Comms Outbound Overflow. Outbound overflow cleared. outboundOverflow = false. Event: Comms Outbound Overflow Cleared. Comms Not Established error. Event: Comms Not Established. Configuration change. Event: Config Change. I J K L hostEnabled = false. commsClosingAck or 30 seconds expired. egmEnabled = false. overflow = false. Event: Comms Disabled By EGM. hostEnabled = false. egmEnabled = false. overflow = false. Inbound Queue Overflow. inboundOverflow=true. Event: Comms Inbound Queue Overflow Figure 2.1 State Diagram: Expected Behavior of EGM Communications Device gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 55 G2S™ Message Protocol v1.0.3 2.3.1 Chapter 2 communications Class Association Attributes Each communications device contains five attributes that are used to describe the current status of the pointto-point association: egmEnabled, hostEnabled, outboundOverflow, inboundOverflow and commsState. These attributes are conveyed in the commsStatus command. The egmEnabled attribute indicates whether the communications device can send messages to and receive messages from the host. For this attribute to be set to true, both the inbound and outbound command queues associated with the host MUST be ready to accept application-level commands. If the queues are not ready to accept application-level commands then no communications can take place and the egmEnabled attribute MUST be set to false. The hostEnabled attribute indicates whether EGM-originated requests should be placed in the outbound queue to the host. When the attribute is set to false, the EGM MUST only place responses to host-originated requests in the outbound queue. The only exceptions to this rule are the commsOnLine and commsDisabled commands. When required, the EGM MUST always place commsOnLine and commsDisabled commands in the outbound queues. The outboundOverflow attribute indicates whether the outbound queue is full, preventing additional commands from being added to the queue. When the attribute is set to true, the EGM cannot place any additional commands on the outbound queue. The inboundOverflow attribute indicates whether the inbound queue is full thereby preventing commands from the host from being added to the queue. When the attribute is set to true, the inbound queue is full. When the attribute is set to false, incoming commands can be queued. The commsState attribute identifies the current state of the communications device: closed, sync, onLine, overflow or closing. 2.3.2 opening, closed State The communications device is in the closed state if its inbound and outbound queues are not ready to accept application-level commands, i.e. the egmEnabled attribute is set to false. When entering this state, the EGM MUST set the egmEnabled, hostEnabled, inboundOverflow and attributes to false and rebuild or re-initialize its queues. outboundOverflow While in this state, no inbound or outbound communications can take place. The device enters this state when the EGM restarts. It will also transition to this state from the closing state. After the communications device has been initialized (as described above), the EGM MUST set the egmEnabled attribute of the communications device to true, generate a G2S_CME002 Comms Enabled event, and then transition to the opening state. Page 56 by EGM gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.3.3 opening State When entering the opening state, the EGM MUST place a commsOnLine request in the outbound queue. The communications device is in the opening state until it has received a commsOnLineAck response to a commsOnLine request. The host MUST send a commsOnLineAck response to a commsOnLine request before the device can transition to the sync state. While in the opening state: • The EGM is attempting to establish initial two-way communications with the host. • The EGM MUST not place any commands, other than commsOnLine commands, in the outbound queue. Periodically, the EGM MUST retry the commsOnLine request. The frequency of retries may be set locally at the EGM or remotely through a configuration server. The frequency MUST NOT be less than 1 (one) second. A default value of 30 seconds is recommended. • If the EGM receives a G2S_MSX003 Communications Not Online error from the host, the EGM MUST generate a G2S_CME101 Comms Not Established event and remain in the opening state. A G2S_MSX003 Communications Not Online error is an acceptable response from a host because the commsOnLine request that has been sent may have not been processed at the application level before the g2sAck containing the G2S_MSX003 error code was sent. • If the configuration of a device is changed and the host is an owner or guest of the device, the EGM MUST transition to the closing state. The appropriate "configuration changed" event will have been generated by the affected device. • If the EGM encounters an overflow condition in its outbound queue, the EGM MUST set the outboundOverflow attribute of the communications device to true, generate a G2S_CME102 Comms Outbound Overflow event, and then transition to the closing state. • If the EGM encounters an overflow condition in its inbound queue, the EGM MUST set the inboundOverflow attribute of the communications device to true, generate a G2S_CME104 Comms Inbound Overflow event, and then remain in the opening state. • If an inbound overflow condition subsides while the communications device is in the opening state, the EGM MUST set the inboundOverflow attribute of the communications device to false, generate a G2S_CME105 Comms Inbound Overflow Cleared event, and then remain in the opening state. After receiving a commsOnLineAck response, the EGM MUST generate a G2S_CME100 event and then transition to the sync state. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Comms Established Page 57 G2S™ Message Protocol v1.0.3 2.3.4 Chapter 2 communications Class sync State The communications device is in the sync state until it has received a setCommsState request from the host with the enable attribute set to true. While in the sync state, the host has an opportunity to query the device structure of the EGM and set its subscriptions before normal communications resume. The commsOnLine command provides indications of changes related to device structure, subscriptions and meters that MAY assist in guiding the sync state dialog. When entering the sync state, the EGM MUST place a commsDisabled request in the outbound queue. A commsDisabledAck response is required from the host. Both the commsOnLineAck and commsDisabledAck responses contain a syncTimer attribute that controls the frequency of commsDisabled requests while the device is in the sync state. The host may manipulate the syncTimer to control the pace of commsDisabled requests from the EGM. The frequency MUST NOT be less than 15 seconds. A default value of 30 seconds is recommended. While in the sync state: • The EGM MUST place responses to host-originated requests in the outbound queues. The EGM MUST NOT place any EGM-originated requests, other than commsDisabled requests, in the outbound queues. At the frequency specified in the syncTimer attribute, the EGM MUST retry the commsDisabled request. • If the EGM receives a G2S_MSX003 Communications Not Online error from the host, the EGM MUST generate a G2S_CME101 Comms Not Established event and then transition to the closing state. • If the configuration of a device is changed and the host is an owner or guest of the device, the EGM MUST transition to the closing state. The appropriate "configuration changed" event will have been generated by the affected device. • If the EGM encounters an overflow condition in its outbound queue, the EGM MUST set the outboundOverflow attribute of the communications device to true, generate a G2S_CME102 Comms Outbound Overflow event, and then transition to the closing state. • If the EGM encounters an overflow condition in its inbound queue, the EGM MUST set the inboundOverflow attribute of the communications device to true, generate a G2S_CME104 Comms Inbound Overflow event, and then remain in the sync state. • If an inbound overflow condition subsides while the communications device is in the sync state, the EGM MUST set the inboundOverflow attribute of the communications device to false, generate a G2S_CME105 Comms Inbound Overflow Cleared event, and then remain in the sync state. After receiving a setCommsState request from the host with the enabled attribute set to true, the EGM MUST generate a G2S_CME004 Comms Enabled by Host event, set the hostEnabled attribute of the communications device to true, place the commsStatus response to the setCommsState request in the outbound queue, and then transition to the onLine state. Page 58 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 2.3.5 Chapter 2 communications Class onLine State The communications device is in the onLine state while the egmEnabled and hostEnabled attributes are set to true and the outboundOverflow attribute is set to false. While in this state, the EGM is not restricted in any way. The EGM can send any messages, including requests, responses and notifications. When entering the onLine state, the EGM MUST recover any unacknowledged transactions or events for the host. The normal retry mechanism of the eventHandler and other devices is sufficient to meet this requirement. No special handling is required within the communications class. While in the onLine state: • The EGM MUST place all EGM-originated requests as well as responses to host-originated requests in the outbound queue. • If the EGM receives a G2S_MSX003 Communications Not Online error from the host, the EGM MUST generate a G2S_CME101 Comms Not Established event and then transition to the closing state. • If the configuration of a device is changed and the host is an owner or guest of the device, the EGM MUST transition to the closing state. The appropriate "configuration changed" event will have been generated by the affected device. • If the EGM encounters an overflow condition in its inbound queue, the EGM MUST set the inboundOverflow attribute of the communications device to true, generate a G2S_CME104 Comms Inbound Overflow event, and then remain in the online state. • If an inbound overflow condition subsides while the communications device is in the onLine state, the EGM MUST set the inboundOverflow attribute of the communications device to false, generate a G2S_CME105 Comms Inbound Overflow Cleared event, and then remain in the online state. • If the EGM encounters an overflow condition in its outbound queue, the EGM MUST set the outboundOverflow attribute of the communications device to true, generate a G2S_CME102 Comms Outbound Overflow event, and then transition to the overflow state. • If the EGM receives a setCommsState request with the enable attribute set to false, the EGM MUST set the hostEnabled attribute of the communications device to false, generate a G2S_CME003 Comms Disabled by Host event, place the commsStatus response to the setCommsState request in the outbound queue, and then transition to the sync state. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 59 G2S™ Message Protocol v1.0.3 2.3.6 Chapter 2 communications Class overflow State The communications device is in the overflow state if its outbound queue becomes full. While in this state, the EGM is unable to place any commands in the outbound queue. Critical events and transactions will be persisted within individual classes and will be recovered by the normal retry mechanism once the overflow condition is cleared. When entering the overflow state, the EGM MUST set the outboundOverflow attribute of the communications device to true and generate a G2S_CME102 Comms Outbound Overflow event. While in the overflow state: • If the EGM receives a G2S_MSX003 Communications Not Online error from the host, the EGM MUST generate a G2S_CME101 Comms Not Established event and then transition to the closing state. • If the configuration of a device is changed and the host is an owner or guest of the device, the EGM MUST transition to the closing state. The appropriate "configuration changed" event will have been generated by the affected device. • If the EGM receives a setCommsState request with the enable attribute set to false, the EGM MUST set the hostEnabled attribute of the communications device to false, generate a G2S_CME003 Comms Disabled by Host event and then transition to the closing state. • If the EGM encounters an overflow condition in its inbound queue, the EGM MUST set the inboundOverflow attribute of the communications device to true, generate a G2S_CME104 Comms Inbound Overflow event, and then transition to the closing state. After the outbound queue is cleared, the EGM MUST set the outboundOverflow attribute of the communications device to false, generate a G2S_CME103 Comms Outbound Overflow Cleared event, and then transition to the onLine state. 2.3.7 closing State The communications device is in the closing state until it has received a commsClosingAck response to a commsClosing request or it has been in the closing state for 30 seconds, whichever comes first. While in this state, the EGM is trying to notify the host that it will be closing the communications device. When entering the closing state, the EGM MUST set the hostEnabled attribute of the communications device to false and place a commsClosing request in the outbound queue when possible. While in the closing state, until the commsClosingAck is processed by the EGM or 30 seconds expire, whichever comes first, the EGM MUST continue to send commands that have been placed in the outbound command queue. The EGM MUST NOT place any EGM-originated requests in the outbound queues. All EGM-originated requests, events and notifications should be logged where necessary and marked as unsent or unacknowledged. Recovery actions associated with the logs and unsent or unacknowledged messages is described in Chapter 1. After receiving the commsClosingAck response to the commsClosing request or it has been 30 seconds since entering the closing state, whichever comes first, the EGM MUST set the egmEnabled attribute of the communications device to false, generate a G2S_CME001 Comms Disabled by EGM event, and then transition to the closed state. Page 60 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 2.3.8 Chapter 2 communications Class Transport Events The transport protocol, which is used to deliver messages between the EGM and the host, may generate events that can be reported through the communications device. This is simply a reporting mechanism. It does not directly affect the state of the communications device described above. To support some jurisdictional requirements that an EGM must be disabled if communications are lost, there is a transportState attribute in the commsStatus command. There are three possible values: G2S_hostUnreachable, G2S_transportUp and G2S_transportDown. When the state of this attribute changes, the EGM MUST generate an appropriate event: G2S_CME120 Comms Host Unreachable, G2S_CME121 Comms Transport Up or G2S_CME122 Comms Transport Down. If the configuration of the EGM indicates that it must disable itself whenever communications are lost and if the transportState is G2S_hostUnreachable or G2S_transportDown, then the EGM MUST disable itself. In such a case, the EGM MUST set the cabinetState to G2S_transportDisabled and execute its standard disable logic. 2.3.9 Lost Communications Regulatory or operational requirements may specify that an EGM report and/or disable when communications is lost between the EGM and one or more of the hosts with which it has a communication association. A no-response timer is used to trigger the recognition and reporting of a host-unreachable condition. The value of the timer is in the noResponseTimer attribute of the communications device profile. The requiredForPlay attribute controls whether the EGM should disable itself if a host-unreachable condition exists. The displayCommFault attribute controls whether the EGM should display a communications fault message if a host-unreachable condition exists. Each time the no-response timer indicates a timeout, a G2S_CME120 Comms Host Unreachable event is generated and the host-unreachable condition is reported to the EGM disable logic. This feature is turned off by setting the noResponseTimer to 0 (zero). If the communications device is required for play and if the communication device state is opening and a hostunreachable condition exists, the G2S_CME120 Comms Host Unreachable event is generated, the EGM is disabled, and the communications device remains in the opening state because the EGM is attempting to establish a communications association with the required host. A fault message may or may not be displayed. If the communications device is required for play and if the communication device state is sync, onLine or overflow, and a host-unreachable condition exists, the G2S_CME120 Comms Host Unreachable event is generated, the EGM is disabled, and the communications device transitions to the closing state. The EGM will close its current association and then attempt to open a new association. A fault message may or may not be displayed. The no-response timer is not operational in the closing or closed states. The no-response timer may be operational in the opening, sync, onLine and overflow states. In the opening state, the commsOnLine command should be sent multiple times before the response timer expires. This is achieved by setting the noResponseTimer value to 5-10 times the timeToLive. In the sync state, the commsDisabled command should be sent multiple times before the response timer expires. This is achieved by setting the noResponseTimer value to 5-10 times the syncTimer. In the onLine state, the keepAlive command should be sent multiple times before the response timer expires. This is achieved by setting the noResponseTimer value to 5-10 times the timeToLive. In the overflow state, commands are queued for sending and resending. The noResponseTimer value should be set to 5-10 times the timeToLive. The host-unreachable condition is cleared when the communications device receives a commsOnLineAck command and generates a G2S_CME100 Comms Established event. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 61 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 The EGM disable condition from the communications class is cleared when the communications device processes a setCommsState with enable= "true". This occurs as part of the transition from sync to onLine. 2.4 Multicast Service In the current G2S view of multicast, only hosts will be multicasting information. Devices within EGMs will be the targets of the multicasts. For example, a progressive host may multicast to a progressive device within an EGM. The G2S commands are designed to be independent of the multicast transport being used. The multicast service is best effort. No acknowledgement will be sent by the receiving device. The multicast service is described in terms of multicast message, multicast stream, multicast group and multicast identifier. Multicast stream: A collection of multicast messages. Multicast messages: Sent by multicast hosts to members of a multicast group. Multicast group: Each member (device) of a multicast group is bound to a multicast stream. Multicast identifier: A label for the multicast group, multicast stream, and associated multicast messages. (See also Section 2.4.1.) An EGM MUST be configured to receive multicast messages from a particular host. This configuration information MUST be persisted. Each communications device contains an mcastAllowed attribute that is used to record whether multicast is allowed (true) or not allowed (false). The value of this attribute is conveyed from an EGM to a host via the commStatus command. Each communication device within the class MUST be separately configured. Configuration MAY be accomplished through an automatic or manual configuration procedure. In the case of automatic configuration, the EGM MUST get configuration settings from a communications configuration (commConfig) host. The automatic configuration procedure is described in the commConfig class. In the case of manual configuration of an EGM, the mcastAllowed attribute MUST be exposed to the operator via a user interface. Control messaging for joining, leaving and other management of a multicast group MUST be accomplished over the point-to-point association between a communications device and the owner host. The communications device controls the binding of other devices within the EGM, owned by that host, to multicast streams. This binding is essentially subscription information for the multicast group and MUST be persisted. The subscription information includes the multicast identifier, requesting host identifier, transport designator, and EGM device designator. Only the owner host of the communications device can cause devices owned by that host to join or leave a multicast stream. Guest hosts are permitted to get multicast events and general status information, such as members lists (see Section 2.4.5), but guest hosts MUST NOT cause devices to join or leave multicast streams. The multicast service MAY use any multicast transport standardized by GSA. The normal sequence to join a multicast stream is (see Figure 2.2): 1. Configure the communications device for multicast. This need only be done once. 2. The owner host sends a joinMcast request with the multicast identifier, transport designator, and designator of device within the EGM to join to the multicast stream. The EGM responds with a joinMcastAck. 3. The EGM receives multicast messages from the multicast transport and forwards them to the proper device(s) within the EGM. A single multicast message MUST be distributed to all members of the multicast stream. Page 62 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 See also Section 2.4.2, Joining a Multicast Group. To leave a multicast stream, the owner host sends a leaveMcast request with the multicast identifier and designator of the device. This causes the device to be removed from the multicast stream. The EGM responds with a leaveMcastAck. See also Section 2.4.4, Leaving a Multicast Group. COMM CONFIG HOST MULTICAST HOST EGM setCommChange ( allowMulticast = “true” ) STEP 1 commChangeStatus ( allowMulticast = “true” ) joinMcast STEP 2 joinMcastAck Multicast message 1 STEP 3 Multicast message 2 Multicast message 3 . . . Multicast message N leaveMcast STEP 4 leaveMcastAck Figure 2.2 Multicast Sequence Diagram 2.4.1 Multicast Identifiers A multicast host MUST be configured to use multicast. Part of the configuration process is to assign a multicastId and map it to a set of transport parameters called the multicastLocation. The multicastId MUST be unique across the gaming network. The multicastId MUST follow the G2S naming convention for unique identifiers (see chapter 1). The multicastLocation is a set of parameters used by the multicast transport to attach to a multicast stream. These parameters are not of interest to the communications device and are simply passed from the multicast host to the multicast transport in the EGM. These parameters are defined in the multicast transport specification. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 63 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 The multicastIds for a host can be configured manually or automatically. Manual configuration requires that a system operator enter the information through a user interface local to the host. Only the multicast group information needed by a host is actually entered at configuration time. The operator must ensure that all multicastIds are unique across a system. Manual configuration works well when the number of multicast groups is small or they change infrequently. Automatic configuration of multicast group identifiers requires that a multicast host request a multicast identifier from a source of configuration information, for example, a configuration host. This is outside the scope of G2S. 2.4.2 Joining a Multicast Group In order to cause an EGM device to join a multicast stream, the owner host MUST send a joinMcast request to the communications device. The joinMcast request MUST contain the multicastId, multicastLocation, deviceClass, and deviceId. The multicastLocation is the multicast address or other multicast transport-specific parameters used to attach to a multicast stream. The deviceClass and deviceId designate which device in the EGM MUST be bound to the multicast stream. The communications device MUST add the device to the multicast group. If the multicast group does not already exist, then a new multicast group MUST be created using the multicastLocation to attach to the multicast stream. The EGM MUST respond with a joinMcastAck and generate a G2S_CME110 Join Multicast Group event upon successfully adding the device to the multicast group. The multicast group subscription information is: hostId, deviceClass, deviceId, multicastId and These MUST be persisted for each existing multicast group at the EGM. multicastLocation. If the host is not the owner of the communications device, then the EGM MUST respond with a G2S_CMX003 error. Host Not Owner If the communications device is not configured for multicast, then the EGM MUST respond with a error. G2S_CMX004 Device Not Configured For Multicast If the multicastId is not unique, then the EGM MUST respond with a G2S_CMX005 Not Unique MulticastId error. The multicastId MUST be unique across the system. The EGM MUST maintain a mapping between multicastId and multicastLocation in order to perform this check. This error occurs when a multicast group has already been established and a new joinMcast is received with the multicastLocation value different than that used to establish the multicast group. If the specified device does not exist, the EGM MUST respond with an G2S_CMX008 error. Invalid Multicast DeviceId If the multicast transport reports a failure to join the multicast stream specified by the multicastLocation, then the EGM MUST respond with an G2S_CMX006 Multicast Service Not Established error. The communications device is acting as a pass-through between the multicast transport and the multicast host. 2.4.3 Receiving a Multicast Message The multicast message contains several parameters that MUST be checked by the EGM. A multicast message contains the hostId and the multicastId (see Chapter 1 for the multicast message format). The hostId MUST be used to verify that the multicast message is coming from the multicast host that created the multicast group on the EGM. The communications device MUST keep a mapping of multicastId to hostId. The multicastId MUST be used to verify that the message belongs to an established multicast group of the host. The communications device MUST keep a mapping of multicastId to deviceClass/deviceId. Page 64 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 2 communications Class After the hostId and multicastID have been validated, the multicast message must be distributed to all devices that are members of the multicast group. A multicast message that has an invalid multicastId or hostId MUST be discarded and the communications device MUST generate a G2S_CME112 Multicast Message Error event. An event is generated instead of an error message using g2sAck because multicast uses a different transport and messages are not acknowledged. 2.4.4 Leaving a Multicast Group To cause an EGM device to leave a multicast stream, the owner host MUST send a leaveMcast request to the communications device. The leaveMcast request MUST contain the multicastId, deviceClass, and deviceId. The deviceClass and deviceId designate which device MUST leave the multicast group. The communications device MUST remove the device from the multicast group. The EGM MUST respond with a leaveMcastAck and generate a G2S_CME111 Leave Multicast Group event upon successfully removing the device to the multicast group. If the multicast group is empty as a result of removing the device, then the communications device MUST remove the multicast group. No indication of an empty multicast group is sent to the host. A host MAY request a list of the current multicast groups to verify whether a multicast group has members or does no exist (is empty). If the host is not the owner of the communications device, then the EGM MUST respond with a G2S_CMX003 Host Not Owner error. If the communications device is not configured for multicast, then the EGM MUST respond with a error. G2S_CMX004 Device Not Configured For Multicast If the multicastId is not for a valid multicast group, the EGM MUST respond with a G2S_CMX007 No Multicast Group error. If the specified device does not exist, the EGM MUST respond with an G2S_CMX008 error. Invalid Multicast deviceId 2.4.5 Getting a List of Multicast Groups, getMcastList To request a list of the multicast groups and members of a communications device, the host sends a getMcastList command. The host can only request the list for a single communications device. If a host wants more than one list, it MUST request each one separately. An EGM MUST respond to the getMcastList command with a mcastList command which includes the multicastIds and members of every multicast group established by the communications device. An empty message indicates that the communications device has no multicast groups. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 65 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.4.6 Multicast Message Security The multicast message stream will use various technologies in order to provide message integrity, authentication and confidentiality. The owner host MUST identify to the communications device the security technology it is using, e.g., encryption algorithm and key, authentication algorithm and key, etc. This is transport specific and not of interest to the communications device. However, because the communications device acts as a conduit between the multicast host and the multicast transport in the EGM, the communications device MUST pass security parameters from the multicast host to the multicast transport. The securityParams attribute of the joinMcast and mcastUpdateKey are used to convey the security information. All messages used to manage the multicast message stream security settings MUST be sent over a secure pointto-point communication association that provides integrity, authentication and confidentiality. The owner host MUST send an mcastKeyUpdate command containing the multicastId and securityParams in order to update the security settings. The EGM MUST respond with a mcastKeyAck and generate a G2S_CME113 Security Parameters Updated event upon successfully updating the security parameters. If the host is not the owner of the communications device, then the EGM MUST respond with a G2S_CMX003 Host Not Owner error. If the communications device is not configured for multicast, then the EGM MUST respond with a error. G2S_CMX004 Device Not Configured for Multicast If the multicastId is not for a valid multicast group, the EGM MUST respond with a G2S_CMX007 No Multicast Group error. If a number of consecutive multicast messages are not successfully received using the current security parameters, a communications device MAY notify the host by sending a getMcastKeyUpdate containing the multicastId of the affected multicast group. The owner host MUST respond with an mcastKeyUpdate command containing the multicastId and securityParams in order to update the security settings. The communications device MUST generate a G2S_CME113 Security Parameters Updated event upon successfully updating the security parameters. If the communications device cannot update the security parameters, it MUST return an G2S_CMX010 error. Invalid Security Parameters Page 66 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.5 Request-Response Pairs The following tables organize the commands contained within the communications class into requestresponse pairs: Table 2.1 Commands Originated by EGM Request Response commsOnLine commsOnLineAck commsDisabled commsDisabledAck commsClosing commsClosingAck getMcastKeyUpdate mcastKeyUpdate keepAlive keepAliveAck Table 2.2 Commands Originated by Host Request Response Owner Guest getCommsProfile commsProfile Yes Yes setCommsState commsStatus Yes No getCommsStatus commsStatus Yes Yes getDescriptor descriptorList Yes Yes joinMcast joinMcastAck Yes No leaveMcast leaveMcastAck Yes No getMcastList mcastList Yes Yes mcastKeyUpdate mcastKeyAck Yes No setKeepAlive setKeepAliveAck Yes No keepAlive keepAliveAck Yes Yes gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 67 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.6 setCommsState Command This command is used by a host to enable or disable communications with an EGM. When disabled, the EGM MUST NOT queue any EGM-originated requests to the host until re-enabled. The EGM MUST respond to host-originated requests. See Chapter 1 for more information. Only the owner of the device can execute this command. A commsStatus command is sent in response to the setCommsState command. Table 2.3 setCommsState Attributes Attribute Restrictions Description enable type: boolean use: optional default: true Indicates whether communications should be enabled or disabled. (true = enabled, false = disabled). disableText type: textMessage use: optional default: <empty> Optional message to display while the device is disabled. 2.7 getCommsStatus Command This command is used by a host to request the current status of the communications between an EGM and a host. A commsStatus command is sent in response to the getCommsStatus command. There are no additional attributes or elements for this command. Page 68 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.8 commsStatus Command This command is used by an EGM to report the current status of the communications device. The commsStatus command is sent in response to the setCommsState and getCommsStatus commands. The g2sProtocol attribute indicates whether the owner host and EGM are using the G2S protocol to communicate. Because only G2S hosts may own a communications device, the g2sProtocol attribute MUST always be set to true. See Section 1.7 for more information. The commsState attribute identifies the current state of the communications device: G2S_closed, G2S_opening, G2S_sync, G2S_onLine, G2S_overflow or G2S_closing. The transportState attribute identifies the current state of the underlying transport: hostUnreachable, transportUp, or transportDown. The state of the transport is reported to the communications device through a local API. The requirements of the API are documented in the transport specification. The mcastAllowed attribute identifies whether the communications device is able to join multicast groups. This is controlled through manual or automatic configuration. The commConfig option used to set the mcastAllowed attribute is allowMulticast. Table 2.4 commsStatus Attributes Attribute Restrictions Description configurationId type: configurationId use: optional default: 0 Configuration identifier set by the host. hostEnabled type: boolean use: optional default: true Indicates whether communications have been enabled or disabled by the host. (true = enabled, false = disabled). egmEnabled type: boolean use: optional default: true Indicates whether communications have been enabled or disabled by the EGM. (true = enabled, false = disabled). outboundOverflow type: boolean use: optional default: false Indicates whether the outbound queue of the device is in the overflow state. (true / false). inboundOverflow type: boolean use: optional default: false Indicates whether the inbound queue of the device is in the overflow state. g2sProtocol type: boolean use: optional default: true Indicates whether the EGM and owner host are using the G2S protocol for communications. commsState type: commsStates use: required Indicates the current state of communications. transportState type: transportStates use: required Indicates the current state of the transport. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 69 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.9 getCommsProfile Command This command is used by a host to request the current communications profile from an EGM. The communications profile contains the protocol-related configuration option selections for the communications device. A commsProfile command is sent in response to the getCommsProfile command. The getCommsProfile element has no additional attributes or elements. 2.10 commsProfile Command This command is used by an EGM to report the current profile of a communications device. The communications profile contains the protocol-related configuration option selections for the communications device. The configuration options can be set locally at the EGM or remotely via a configuration server using commands within the commConfig class (see Chapter 8). The commsProfile command is sent in response to a getCommsProfile command. Table 2.5 commsProfile Attributes Attribute Restrictions Description configurationId* type: configurationId use: optional default: 0 Last configuration identifier set by a G2S host; set to 0 (zero) when configuration changes are made by hosts other than G2S hosts. useDefaultConfig* type: boolean use: optional default: false Indicates whether the default configuration for the device MUST be used when the EGM restarts. requiredForPlay* type: boolean use: optional default: false Indicates whether the EGM MUST be disabled if either egmEnabled or hostEnabled is set to false. timeToLive* type: timeToLive use: optional default: 30000 Time-to-live value for requests originated by the device. noResponseTimer* type: milliseconds use: optional default: 300000 The no response value used to determine whether an EGM has lost communications with a host. allowMulticast* type: boolean use: optional default: true Indicates whether the device is enabled to join multicast groups (true = enabled/ false = disabled). displayCommFault* type: boolean use: optional default: false Indicates whether a communications fault message should be displayed if the communications channel is unavailable. * Page 70 Standard configuration option. Configured using setCommChange command of the commConfig class. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.11 commsOnLine Command The commsOnLine establishes the association between EGM and host. It allows the EGM to tell the host the communications address of the EGM and whether the EGM has compromised its persistent memory since the last association was terminated. An EGM MUST only send commsOnLine commands to the owner of the communications device. To maintain order, a host MUST never use the hostId of another host in its requests. An EGM detecting an improper hostId in a request will return a G2S_MSX001 Incorrect hostId Specified error. The EGM controls which version of the G2S protocol will be used. A host MUST accept the EGM’s request or reject the commsOnline. The EGM requests the G2S protocol version to be used by contacting the host using a URI specific to the G2S protocol version. In other words, each version of the protocol will have its own unique URI. If a host does not support a version of the protocol, then the underlying transport will report a host unreachable condition. The EGM MAY continue to try establishing an association using other versions of the protocol on subsequent commsOnLine attempts. The egmLocation provides the communications address of the EGM so that the host can establish communications to the EGM. When the EGM establishes an association with the owner host, it uses the deviceReset, deviceChanged, subscriptionLost and metersReset attributes to provide guidance on what may have changed since the last commsOnLine command. The EGM MUST set the deviceReset attribute to true if the device structure of the EGM has been reset, i.e., the devices within the EGM may have been renumbered. This implies that the subscriptions set by the host may no longer reference the correct devices. A host should review the EGM device structure and reset meter and event subscriptions if necessary. The EGM MUST set the deviceChanged attribute to true if one or more devices have been added to or removed from the EGM. A host should review the EGM device structure and set meter and event subscriptions if necessary. The EGM MUST set the subscriptionLost attribute to true if the meter or event subscriptions of the host have been lost. A host should review the EGM device structure and set meter and event subscriptions if necessary. The EGM MUST set the metersReset attribute to true if the meters for one or more devices have been reset. A host should review the EGM meters and update the host database if necessary. Table 2.6 commsOnLine Attributes (Sheet 1 of 2) Attribute Restrictions Description equipmentType type: equipmentTypes use: optional default: G2S_egm Conveys the type of equipment currently using the G2S protocol. egmLocation type: transportLocation use: required URI or other identifier used to send requests to the EGM. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 71 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 Table 2.6 commsOnLine Attributes (Sheet 2 of 2) Attribute Restrictions Description deviceReset type: boolean use: optional default: false Indicates whether the device structure of the EGM has been reset since the last commsOnLine command. Always set to true when a new communications device is added to the EGM. deviceChanged type: boolean use: optional default: false Indicates whether one or more devices have been added to or removed from the EGM. subscriptionLost type: boolean use: optional default: false Indicates whether meter or event subscriptions of the host have been lost. metersReset type: boolean use: optional default: false Indicates whether the meters for one or more devices have been reset. 2.12 commsOnLineAck Command A owner host MUST respond to a commsOnLine with a commsOnLineAck. The commsOnLineAck completes the opening of the association and ensures that the EGM and host can communicate with each other. Upon receipt of the commsOnLineAck command, the EGM MUST set the deviceReset, deviceChanged, and metersReset attributes to false. subscriptionLost The commsOnLineAck command marks the transition into the sync state (see Section 2.3.4). While in sync state, the EGM periodically sends a commsDisabled command to remind the owner host that the EGM is still in the sync state. The syncTimer attribute conveys the timer value. Whenever the timer expires, another commsDisabled command MUST be sent and the timer reset to the syncTimer value. The recommended value is 30 seconds. Table 2.7 commsOnLineAck Attributes Attribute Restrictions Description syncTimer type: syncTimer use: optional default: 30000 The interval of time between sending commsDisabled requests in the sync state. Recommended value is 30 seconds. Value MUST NOT be less than 15 seconds. Page 72 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.13 commsDisabled Command During the sync phase, an EGM MUST periodically send a commsDisabled request to notify the owner host that the communications device is still in the sync phase. This continues until the EGM receives from the host a setCommsState request with the enable attribute set to true. The commsDisabled element has no additional attributes. 2.14 commsDisabledAck Command An owner host MUST respond to a commsDisabled command with a commsDisabledAck command. The commsDisabledAck ensures that the EGM and host can communicate with each other. While in sync state, the EGM periodically sends a commsDisabled command to remind the owner host that the EGM is still in the sync state. The syncTimer attribute conveys the timer value. Whenever the timer expires, the EGM MUST send a commsDisabled command and the timer reset to the syncTimer value. The recommended value is 30 seconds. The owner host MAY use the syncTimer attribute to change the timer value with any commsDisabledAck. Table 2.8 commsDisabledAck Attributes Attribute Restrictions Description syncTimer type: syncTimer use: optional default: 30000 The interval of time between sending commsDisabled requests in the sync state. Recommended value is 30 seconds. Value MUST NOT be less than 15 seconds. 2.15 commsClosing Command The EGM MUST notify the owner host that it is closing the existing association. The commsClosing command is sent to the host in an attempt to gracefully close. Table 2.9 commsClosing Attributes Attribute Restrictions Description reason type: egmMessage use: optional default: <empty> Reason for closing. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 73 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.16 commsClosingAck Command The owner host MUST acknowledge a commsClosing request. The commsClosingAck element has no additional attributes. 2.17 getDescriptor Command This command is used by a host system to request a list of device identifiers with descriptive information about the devices from an EGM. The EGM responds by sending a descriptorList command. The wildcard convention G2S_all can be used with the deviceClass attribute to request all classes. The wildcard convention -1 can be used with the deviceId attribute to request all devices. Device class names are not case-sensitive. It is anticipated that this command will be used to discover the devices contained within an EGM. Only active devices are returned in the descriptorList command. Other inactive devices, i.e. devices that were not activated and assigned to owners during configuration, are not reported in the descriptorList command. Table 2.10 getDescriptor Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class to select. The wildcard convention G2S_all can be used to select all classes. deviceId type: deviceId use: required Specific device to select. The wildcard convention -1 can be used to select all devices with the selected classes. includeOwners type: boolean use: optional default: true Indicates whether devices owned by the host specified in the deviceId of the class element should be included. includeGuests type: boolean use: optional default: true Indicates whether devices should be included where the host specified in the deviceId of the class element is a guest. includeConfigs type: boolean use: optional default: true Indicates whether devices should be included where the host specified in the deviceId of the class element is the configurator of the device. includeOthers type: boolean use: optional default: true Indicates whether devices should be included where the host specified in the deviceId of the class element is neither an owner nor a guest. Page 74 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.18 descriptorList Command This command is sent by the EGM in response to a getDescriptor command from a host. The descriptorList element contains the current device descriptors for the selected classes and devices. The device descriptor information includes vendor, product, and serial number information about a device. This set of information was designed to be compatible with the data available from USB devices as specified by the GDS committee of the GSA. For consistency, all EGM manufacturers should get a vendorId from the USB Implementers Forum, http://www.usb.org/developers/vendor/. In addition, for both USB and non-USB devices, it is recommended that vendors follow the guidelines set by the USB standards board for producing product identifiers, release numbers, and so on. For non-USB devices, manufacturers should attempt to provide meaningful information in the relevant attributes. The descriptorList element contains no attributes. Table 2.11 descriptorList Elements Element Restrictions Description descriptor minOcc: 0 Contains descriptor information about a specific device. See Table 2.12. maxOcc: ∞ Table 2.12 descriptor Attributes ( (Sheet 1 of 2) Attribute Restrictions Description deviceClass type: deviceClass use: required Device class. deviceId type: deviceId use: required Specific device within the class. deviceActive type: boolean use: required Indicates whether the device is active (true) or inactive (false). configurationId type: configurationId use: optional default: 0 Configuration identifier set by the configuration host. hostEnabled type: boolean use: optional default: true Indicates whether the device has been enabled or disabled by the host. (true = enabled, false = disabled). egmEnabled type: boolean use: optional default: true Indicates whether the device has been enabled or disabled by the EGM. (true = enabled, false = disabled). egmLocked type: boolean use: optional default: false Indicates whether the EGM has been locked by the device. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 75 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 Table 2.12 descriptor Attributes ( (Sheet 2 of 2) Attribute Restrictions Description hostLocked type: boolean use: optional default: false Indicates whether the EGM has been locked by the host. ownerId type: deviceId use: optional default: 0 Device identifier (from the communications class) of the host that owns the device. The value 0 (zero) indicates that the device is owned by the EGM. configId type: deviceId use: optional default: 0 Device identifier of the host that configures the device. The value of 0 (zero) indicates that the device can only be configured manually at the EGM. deviceOwner type: boolean use: optional default: false Indicates whether the host specified in the deviceId of the class element is the owner of the device. deviceGuest type: boolean use: optional default: false Indicates whether the host specified in the deviceId of the class element is a guest of the device. deviceConfig type: boolean use: optional default: false Indicates whether the host specified in the deviceId of the class element is the configurator of the device. vendorId type: descriptorText use: optional default: <empty> USB vendor identifier. productId type: descriptorText use: optional default: <empty> Product identifier. releaseNum type: descriptorText use: optional default: <empty> Release number. vendorName type: descriptorText use: optional default: <empty> Vendor name. productName type: descriptorText use: optional default: <empty> Product name. serialNum type: descriptorText use: optional default: <empty> Serial number. Page 76 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.19 joinMcast Command This command is used by a host to request that the specified device of the specified class be joined to a multicast group. The host MUST own this device. Execution of the command will cause the EGM to receive the multicast messages for the multicast group and forward them to the appropriate device. The multicast group subscription information is: hostId, deviceClass, deviceId, multicastId and multicastLocation. These MUST be persisted for each existing multicast group at the EGM. hostId is from the class-level header. Only the owner of the device can execute this command. A joinMcastAck command is sent in response to the joinMcast command. Table 2.13 joinMcast Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Indicates the class associated with the device to be joined. deviceId type: deviceId use: required Indicates the device within the class that is to join the multicast group. multicastId type: multicastId use: required Multicast identifier. multicastLocation type: transportLocation use: required Multicast address or other transport-specific parameters used to open a multicast listener. securityParams type: securityParams use: optional default: <empty> Security-specific parameters used by the multicast transport. The format is defined by the transport. 2.20 joinMcastAck Command This command is used by an EGM to acknowledge the receipt and processing of a joinMcast command from the owner host. There are no additional attributes or elements for this command. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 77 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.21 leaveMcast Command This command is used by a host to request that the specified device of the specified class be removed from a multicast group. The host MUST own this device. Execution of the command will cause the EGM to stop forwarding the multicast messages to specified device. Only the owner of the device can execute this command. A leaveMcastAck command is sent in response to the leaveMcast command. If the multicast group is empty as a result of removing the device, the communications device MUST remove the multicast group. No indication of an empty multicast group is sent to the host. A host MAY request a list of the current multicast groups to verify whether a multicast group has members or does no exist (is empty). Table 2.14 leaveMcast Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Indicates the class of the leaving device. deviceId type: deviceId use: required Indicates the device within the class that is to leave the multicast group. multicastId type: multicastId use: required Multicast identifier of multicast stream from which device should be removed. 2.22 leaveMcastAck Command This command is used by an EGM to acknowledge the receipt and processing of a leaveMcast command from the owner host. There are no additional attributes or elements for this command. Page 78 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.23 mcastKeyUpdate Command This command is used by a host to request that security parameters for the multicast transport be updated. Execution of the command will cause the security parameters to be passed to the multicast transport. In the case where the multicast transport cannot update the security parameters, a G2S_CMX010 Invalid Security Parameters error will be returned. Only the owner of the device can execute this command. An mcastKeyUpdateAck command is sent in response to the mcastKeyUpdate command. The mcastKeyUpdate may also serve as a response to a getMcastKeyUpdate sent by an EGM to request new security parameters. In that case, an mcastKeyUpdateAck is not sent by the EGM. Table 2.15 mcastKeyUpdate Attributes Attribute Restrictions Description multicastId type: multicastId use: required Multicast identifier. securityParams type: securityParams use: optional default: <empty> Security-specific parameters used by the multicast transport. The format is defined by the transport. 2.24 mcastKeyAck Command This command is used by an EGM to acknowledge the receipt and processing of a mcastKeyUpdate command from the owner host. There are no additional attributes or elements for this command. 2.25 getMcastKeyUpdate Command This command is used by an EGM to request a new set of keys for a single multicast group. The owner host responds with a mcastKeyUpdate message. Table 2.16 getMcastKeyUpdate Attributes Attribute Restrictions Description multicastId type: multicastId use: required Multicast identifier. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 79 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.26 getMcastList Command This command is used by a host to request the list of multicast groups associated with a communications device. There are no additional attributes or elements for this command. 2.27 mcastList Command This command is sent by an EGM in response to a getMcastList command from a host. The mcastList element contains the members of the multicast groups at this EGM. A list with no members indicates that the specified communications device is not currently joined to any multicast groups. The mcastList element contains no attributes. Table 2.17 mcastList Elements Element Restrictions Description member minOcc: 0 Contains information about a specific member. See Table 2.18. maxOcc: ∞ Table 2.18 member Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class of the multicast participant. deviceId type: deviceId use: required Device identifier of the multicast participant. multicastId type: multicastId use: required A unique string of up to 32 characters of the form X_Y, where x is the GSA assigned identifier, followed by the underscore character, followed by Y which is a unique identifier assigned by the operator. multicastLocation type: transportLocation use: required Multicast address or other transport-specific parameters used to open a multicast listener. Page 80 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.28 setKeepAlive Command This command is used to alter the frequency of the keepAlive command sent from an EGM to an owner host system. The frequency can be set to 0 (zero) indicating that the EGM MUST NOT send keepAlive commands to the host. The default for the EGM is 0 (zero). When a communications device comes up, it defaults to having the keepAlive function turned off. A host will turn the keepAlive function on at its discretion. The interval value MUST be persisted. A keepAlive command is sent to confirm that the new interval has been set. This command will only be executed by the EGM if it is sent from the owner of the communications device. Only the owner of the device can execute this command. A setKeepAliveAck command is sent in response to the setKeepAlive command. The EGM MUST respond with an G2S_CMX001 Invalid Interval Specified error message if the keepAlive timer does not support the interval specified. Table 2.19 setKeepAlive Attributes Attribute Restrictions Description interval type: keepAliveTimer use: optional default: 0 New keepAlive interval in milliseconds. A value of 0 (zero) implies keepAlive commands MUST NOT be sent. Negative values are not allowed. Less than 5 (five) seconds is not recommended. 2.29 setKeepAliveAck Command An EGM MUST send a setKeepAliveAck to the sending host in order to acknowledge a received setKeepAlive command. A host never sends a setKeepAliveAck. The setKeepAliveAck element has no additional attributes. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 81 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.30 keepAlive Command During normal operations, the keepAlive command is used to test the communications channels for lost communications. The command may be used by both the EGM and host systems. The keepAlive command MUST be sent by an EGM if the queue of commands waiting to be sent is empty and no messages have been sent for the prescribed interval. The owner host may alter the frequency of the keepAlive command using the setKeepAlive command. The host MAY send the keepAlive command whenever it wants. The EGM has no expectations about when keepAlive commands will come from a host. They are primarily used by a host to check whether application messaging is still available. The required response to the keepAlive command is the keepAliveAck command. The keepAlive element has no additional attributes. 2.31 keepAliveAck Command The keepAlive command MUST be acknowledged by the receiving host or EGM using the keepAliveAck command. The keepAliveAck element has no additional attributes. Page 82 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.32 Data Types The following table lists the data types specific to the communications class. Table 2.20 communications Class Data Types Data Type Restrictions Description commsStates type: string enumerations: G2S_closed G2S_opening G2S_sync G2S_onLine G2S_overflow G2S_closing Set of states for communications. transportStates type: extensibleList Set of states for the underlying transport. See Section 2.32.1. equipmentTypes type: extensibleList Type of equipment. See Section 2.32.2. syncTimer type: milliseconds minIncl: 15000 Communications synchronization timer, in milliseconds. securityParams type: string minLen: 0 maxLen: 256 Security parameters defined by the multicast transport. keepAliveTimer type: milliseconds Keep-alive timer, in milliseconds. descriptorText type: string maxLen: 32 Descriptor text data type. 2.32.1 Reserved transportStates Enumerations Table 2.21 Enumerations for the transportStates Data Type Enumeration Description G2S_hostUnreachable Host is unreachable. G2S_transportUp Transport is up. G2S_transportDown Transport is down. 2.32.2 Reserved equipmentTypes Enumerations Table 2.22 Enumerations for the equipmentTypes Data Type Enumeration Description G2S_egm Electronic Gaming Machine gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 83 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.33 Error Codes The following table lists the error codes for the communications class: Table 2.23 communications Class Error Codes Error Code Suggested Error Text G2S_CMX001 Invalid Interval Specified G2S_CMX002 Unsupported G2S Version G2S_CMX003 Host Not Owner G2S_CMX004 Device Not Configured For Multicast G2S_CMX005 Not Unique multicastId G2S_CMX006 Multicast Service Not Established G2S_CMX007 No Multicast Group G2S_CMX008 Invalid Multicast deviceId G2S_CMX009 Invalid Comms deviceId G2S_CMX010 Invalid Security Parameters Page 84 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.34 Event Codes The following table summarizes the events that may be generated by devices within the communications class. Full event descriptions follow the table. Table 2.24 communications Class Event Codes (CM = communications) Affected Device Logs, Meters, Statuses Event Code and Event Title CM G2S_CME001 Comms Disabled by EGM S G2S_CME002 Comms Enabled by EGM S G2S_CME003 Comms Disabled by Host S G2S_CME004 Comms Enabled by Host S G2S_CME005 Comms Configuration Change by Host S G2S_CME006 Comms Configuration Change by EGM S G2S_CME099 Comms All Faults Cleared G2S_CME100 Comms Established S G2S_CME101 Comms Not Established S G2S_CME102 Comms Outbound Overflow S G2S_CME103 Comms Outbound Overflow Cleared S G2S_CME104 Comms Inbound Overflow S G2S_CME105 Comms Inbound Overflow Cleared S G2S_CME110 Join Multicast Group G2S_CME111 Leave Multicast Group G2S_CME112 Multicast Message Error G2S_CME113 Security Parameters Updated G2S_CME120 Comms Host Unreachable S G2S_CME121 Comms Transport Up S G2S_CME122 Comms Transport Down S The following table lists the elements contained within the communications class which may be included as affected data with events: Table 2.25 Elements Included With Events Affected Data Element Device Status commsStatus gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 85 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.34.1 evaluate(state) The egmEnabled and egmState attributes are both determined from multiple factors. If all of the faults for a device have been cleared then the egmEnabled attribute for the device can be set to true. If any one fault still exists then the egmEnabled attribute MUST be set to false. Thus, after a fault is cleared, the EGM MUST evaluate all of the attributes that contribute to the state of the egmEnabled attribute. If anyone of them shows a fault then the egmEnabled attribute MUST remain false. This is communicated in the following documentation by using the convention "evaluate(device.egmEnabled)". Likewise, the egmState attribute of the cabinetStatus reflects the aggregate state of all devices in the EGM. If the requiredForPlay attribute in the profile of a device is set to true then if either the egmEnabled or hostEnabled attribute of the device is set to false, the egmState MUST reflect that the EGM is disabled. Similarly, if the egmLocked or hostLocked attribute of a device is set to true then the egmState MUST reflect that the EGM is locked out. If any one device is in such a state then the egmState MUST reflect that the EGM is disabled or locked out, as appropriate. Thus, after a device has been enabled or a lockout has been cleared, the EGM MUST evaluate the state of all active devices within the EGM to determine the proper value of the egmState attribute. At the same time, the deviceClass and deviceId attributes of the cabinetStatus MUST be updated to reflect the appropriate device. This is communicated in the following documentation by using the convention "evaluate(cabinet.egmState)". 2.34.2 G2S_CME001 Comms Disabled by EGM The communications device generates this event if it moves to the closed state. Table 2.26 G2S_CME001 Device, Meter, Log Changes, and Related Commands Details Device State Changes egmEnabled = "false" commsStatus = "G2S_closed" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands None. 2.34.3 G2S_CME002 Comms Enabled by EGM The communications device generates this event when the communications device has been initialized. Table 2.27 G2S_CME002 Device, Meter, Log Changes, and Related Commands Details Device State Changes egmEnabled = "true" commsStatus = "G2S_opening" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands None. Page 86 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.34.4 G2S_CME003 Comms Disabled by Host This event is generated by the communications device when a host causes it to go to the sync state. Table 2.28 G2S_CME003 Device, Meter, Log Changes, and Related Commands Details Device State Changes hostEnabled = "false" commsStatus = "G2S_sync" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands Host sent setCommsState with enable 2.34.5 = "false". G2S_CME004 Comms Enabled by Host This event is generated by the communications device when it moves from the sync state to onLine. Table 2.29 G2S_CME004 Device, Meter, Log Changes, and Related Commands Details Device State Changes hostEnabled = "true" commsStatus = "G2S_onLine" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands Host sent setCommsState with enable 2.34.6 = "true". G2S_CME005 Comms Configuration Change by Host This event is generated whenever the configuration of the communications device is changed by the owner host. Table 2.30 G2S_CME005 Device, Meter, Log Changes, and Related Commands Details Device State Changes If a device descriptor or the host table has been reconfigured—that is, changed in any way—then hostEnabled = "false" commsStatus = "G2S_closing" evaluate(cabinet.egmState) Else remain in the same state. Meter State Changes None. Log State Changes None. Related Commands The owner host uses commands from the commConfig class to change the EGM configuration. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 87 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.34.7 G2S_CME006 Comms Configuration Change by EGM This event is generated whenever the configuration of the communications device is changed by activity at the EGM. Table 2.31 G2S_CME006 Device, Meter, Log Changes, and Related Commands Details Device State Changes If a device descriptor or the host table has been reconfigured—that is, changed in any way—then: hostEnabled = "false" commsStatus = "G2S_closing" evaluate(cabinet.egmState) Else remain in the same state. Meter State Changes None. Log State Changes None. Related Commands None. 2.34.8 G2S_CME099 Comms All Faults Cleared Use not currently defined by GSA. This event may be used as part of a manufacturer extension. 2.34.9 G2S_CME100 Comms Established This event is generated by the communications device when the commsOnlineAck is received. The device moves to the sync state. Table 2.32 G2S_CME100 Device, Meter, Log Changes, and Related Commands Details Device State Changes commsState = "G2S_sync". Meter State Changes None. Log State Changes None. Related Commands commsOnLineAck Page 88 is received, commsDisabled is sent to the owner. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.34.10 G2S_CME101 Comms Not Established The communications device generates this event when it receives a G2S_MSX003 Communications Not Online error code in a g2sAck. Table 2.33 G2S_CME101 Device, Meter, Log Changes, and Related Commands Details Device State Changes There is no change in device state if the communications device is in the closed, opening or closing state. If the communications device is in the sync, online or overflow state, then the following device state changes occur: hostEnabled = "false" commsStatus = "G2S_closing" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands None. 2.34.11 G2S_CME102 Comms Outbound Overflow This event is generated by the communications device whenever the outbound queue is in an overflow state and the EGM can no longer queue messages for the host. Table 2.34 G2S_CME102 Device, Meter, Log Changes, and Related Commands Details Device State Changes outboundOverflow = "true". If currently in open state, then commsStatus = "G2S_overflow". Else if currently in the opening or sync state, then the following device state changes should occur: hostEnabled = "false" commsStatus = "G2S_closing" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 89 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.34.12 G2S_CME103 Comms Outbound Overflow Cleared This event is generated by the communications device whenever the outbound queue has been cleared and can begin queueing messages for the host again. This can only be generated if the communications device is in the overflow state when the queue becomes cleared. Table 2.35 G2S_CME103 Device, Meter, Log Changes, and Related Commands Details Device State Changes outboundOverflow = "false". commsState = "G2S_onLine". Meter State Changes None. Log State Changes None. Related Commands None. 2.34.13 G2S_CME104 Comms Inbound Overflow This event is generated by the communications device whenever the inbound queue is in an overflow state and the EGM can no longer queue messages from the host. Table 2.36 G2S_CME104 Device, Meter, Log Changes, and Related Commands Details Device State Changes inboundOverflow = "true". If currently in the overflow state then the following device state changes should occur: hostEnabled = "false" commsStatus = "G2S_closing" evaluate(cabinet.egmState) Else remain in the current state. Meter State Changes None. Log State Changes None. Related Commands None. 2.34.14 G2S_CME105 Comms Inbound Overflow Cleared This event is generated by the communications device whenever the inbound queue has been cleared and the EGM can again begin queueing messages from the host. Table 2.37 G2S_CME105 Device, Meter, Log Changes, and Related Commands Details Device State Changes inboundOverflow = "false". Meter State Changes None. Log State Changes None. Related Commands None. Page 90 Remain in the current state. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.34.15 G2S_CME110 Join Multicast Group This event is generated whenever a new device joins a multicast group. Table 2.38 G2S_CME110 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands joinMcastAck 2.34.16 is sent to the owner host. G2S_CME111 Leave Multicast Group This event is generated whenever a device is removed from a multicast group. Table 2.39 G2S_CME111 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands leaveMcastAck 2.34.17 is sent to the owner host. G2S_CME112 Multicast Message Error This event is generated whenever a communications device has determined that it is not correctly receiving the messages from a multicast stream. Table 2.40 G2S_CME112 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands getMcastKeyUpdate is sent to the owner host. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 91 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.34.18 G2S_CME113 Security Parameters Updated This event is generated whenever the security parameters for a multicast group have been updated. Table 2.41 G2S_CME113 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands mcastKeyAck 2.34.19 is sent to the owner host. G2S_CME120 Comms Host Unreachable This event is generated when the EGM determines that the host is unreachable. Table 2.42 G2S_CME120 Device, Meter, Log Changes, and Related Commands Details Device State Changes transportState = "G2S_hostUnreachable". Meter State Changes None. Log State Changes None. Related Commands None. 2.34.20 G2S_CME121 Comms Transport Up This event is generated whenever the EGM transport reports that it is up. Table 2.43 G2S_CME121 Device, Meter, Log Changes, and Related Commands Details Device State Changes transportState = "G2S_transportUp". Meter State Changes None. Log State Changes None. Related Commands None. 2.34.21 G2S_CME122 Comms Transport Down This event is generated whenever the EGM transport reports that it is down. Table 2.44 G2S_CME122 Device, Meter, Log Changes, and Related Commands Details Device State Changes transportState = "G2S_transportDown". Meter State Changes None. Log State Changes None. Related Commands None. Page 92 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.35 Examples 2.35.1 Communication Status Command Sequence EGM HOST setCommsState commsStatus 2.35.1.1 setCommsState: Host to EGM The following example highlights the construction of a setCommsState command sent from a host to an EGM: <communications deviceId = "7" dateTime = "2004-03-02T11:01:27.432-05:00" commandId = "2001" sessionId = "1001" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <setCommsState enable = "false" /> </communications> 2.35.1.2 commsStatus: EGM Response to Host setCommsState The following example highlights the construction of a commsStatus command sent from an EGM to a host in response to a setCommsState command: <communications deviceId = "7" dateTime = "2004-03-02T11:01:27.543-05:00" commandId = "3001" sessionId = "1001" sessionType = "G2S_response" > <commsStatus hostEnabled = "false" egmEnabled = "true" outboundOverflow = "false" inboundOverflow = "false" g2sProtocol = "true" commsState = "G2S_sync" transportState = "G2S_transportUp" /> </communications> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 93 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.35.2 keepAlive Command Sequence EGM 2.35.2.1 HOST EGM HOST keepAlive setKeepAlive keepAliveAck setKeepAliveAck keepAlive: EGM to Host The following example highlights the construction of a keepAlive command sent from an EGM to a host: <communications deviceId = "7" dateTime = "2004-03-02T11:01:27.321-05:00" commandId = "3002" > sessionType = "G2S_request" sessionId = "1002" <keepAlive /> </communications> 2.35.2.2 keepAliveAck: Host to EGM The following example highlights the construction of a keepAliveAck command sent from an EGM to a host: <communications deviceId = "7" dateTime = "2004-03-02T11:01:27.821-05:00" commandId = "2002" > sessionType = "G2S_response" sessionId = "1002" <keepAliveAck /> </communications> 2.35.2.3 setKeepAlive: Host to EGM The following example highlights the construction of a setKeepAlive command sent from a host to an EGM: <communications deviceId = "7" dateTime = "2004-03-02T11:01:27.432-05:00" commandId = "2003" sessionId = "1003" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <setKeepAlive interval = "5000" /> </communications> Page 94 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.35.2.4 setKeepAliveAck: EGM Response to Host setKeepAlive The following example highlights the construction of a setKeepAliveAck command sent from an EGM to a host in response to a setKeepAlive command: <communications deviceId = "7" dateTime = "2004-03-02T11:01:27.543-05:00" commandId = "3003" sessionId = "1003" sessionType = "G2S_response" > <setKeepAliveAck /> </communications> 2.35.3 Descriptor Command Sequence EGM HOST getDescriptor descriptorList 2.35.3.1 getDescriptor: Host to EGM, Requesting Cabinet Descriptor The following example highlights the construction of a getDescriptor command sent from a host system to an EGM requesting the descriptor information for the cabinet: <communications deviceId = "7" dateTime = "2004-03-02T08:38:27.321-05:00" commandId = "2004" sessionType = "G2S_request" sessionId = "1004" timeToLive = "30000" > <getDescriptor deviceClass = "G2S_cabinet" deviceId = "-1" /> </communications> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 95 Chapter 2 communications Class G2S™ Message Protocol v1.0.3 2.35.3.2 descriptorList: EGM Response to Host The following example highlights the construction of a descriptorList command sent from an EGM to a host in response to a getDescriptor command: <communications deviceId = "7" dateTime = "2004-03-02T08:38:27.432-05:00" commandId = "3004" sessionType = "G2S_response" sessionId = "1004" > <descriptorList> <descriptor deviceClass = "G2S_cabinet" deviceId = "1" deviceActive = "true" hostEnabled = "true" egmEnabled = "true" ownerId = "3" deviceOwner = "false" deviceGuest = "true" vendorId = "GSA" productId = "abc123" releaseNum = "1.2.3" vendorName = "Gaming Standards Association" productName = "GSA Gaming Machine" serialNum = "12345678" /> </descriptorList> </communications> Page 96 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3 cabinet Class 3.1 Introduction The cabinet class includes commands and events related to the physical housing and security of the EGM as well as the commands to enable, disable and lock the EGM from play. Typically disable means that something is wrong and that the device should not be used. This is different than a lockout that freezes the machine. Typically an enable/disable feature should take the device out of service and, as directed by the configuration server, result in a cash-out. The lockout feature should freeze the game after any play sequence currently in process completes. The cabinet class also includes events related to components of the EGM that are not broken out into their own device classes, such as service buttons, lamps, video displays, and so on. The cabinet class includes commands and events related to the main processor board of the EGM and its ancillary components such as non-volatile memory. It also includes the commands to set the current date/time. The cabinet class is a single-device class. With the exception of class-level meters, the EGM MUST only expose one active cabinet device within the cabinet, eventHandler and meters classes. Other inactive devices within the cabinet class may be reported through the commConfig class. 3.2 Currencies, Locales and Floor Information Within the G2S protocol, each EGM has a base currency. All monetary meters in the EGM are expressed in terms of this currency. Items of value, such as notes and coins that are accepted or dispensed by the EGM may be expressed in other currencies. At the time the item of value is accepted or dispensed, the EGM translates the value of the item into the EGM base currency and records the translated value against its meters in the EGM base currency. The translated value appears on the credit and other meters. The EGM is not expected to maintain meters in more than one currency. The G2S protocol uses the set of codes defined by ISO-4217 to express currencies. In terms of the ISO-4217 standard, meters and denominations are expressed in one thousandths of the minor unit of the EGM base currency. For example, if the base currency is United States Dollars, then denominations would be expressed as millicents. Thus, when dealing with meters, denominations and other fields which describe things of value, there is typically an implied decimal place which is dependent on the EGM base currency. The ISO-4217 standard defines the number of implied decimal places when converting from the minor unit to the major unit of a currency. Because monetary meters are recorded in thousandths of the minor unit, there will always be a conversion applied to convert meter values to minor or major units of the currency. The following chart provides an example for US Dollars: Denomination One US Dollar ($1.00) 1/100 of a dollar or 1 cent 25 cents Thirty seven dollars and 43 cents 5.5 cents Meter Representation = 100000 = 1000 = 25000 = 3743000 = 5500 Along with a base currency, each EGM is configured with a locale identifier. The locale identifies the language and country of the EGM. By convention, the locale identifier is constructed as language_country_variant. The G2S protocol does not use the variant component, only language and country. ISO-639 defines language gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 97 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 codes. ISO-3166 defines country codes. For example, the locale identifier for English in the United States would be EN_US. Information about the location of an EGM on the slot floor is also provided. It includes the machine identifier, bank, area, zone and identification information as set by the operator either directly at the EGM or through the configuration class. 3.3 Disable, Lockout and Cabinet State Within the G2S protocol, a device may be disabled. In general, this means that the EGM cannot use the device. The EGM itself may disable a device because the device failed an internal test, lost connectivity, or some other reason. A host may disable a device to limit the options available to players, because of excessive error rates, or other reasons. A device is considered disabled if either the EGM or the host has disabled it. The exact behavior expected of a disabled device is addressed on a class-by-class basis. The setCabinetState command should be used when EGM disablement is expected to last indefinitely. For cases where the EGM should be disabled for a set period of time use setCabinetLockOut with its corresponding lockTimeOut attribute set accordingly. Through the optionConfig class, certain devices may be designated as requiredForPlay. Whenever such devices are disabled, the EGM MUST execute its disable logic, typically stopping game play and cashing out the player. The exact logic executed when the EGM is disabled is dependent on the EGM’s configuration. When the EGM is disabled, the egmState attribute of the cabinetStatus command is set to hostDisabled or egmDisabled, as appropriate. The deviceClass and deviceId of the cabinetStatus command identify the last device that caused the EGM-disabled condition. Within the G2S protocol, a device may lock out the EGM. In general, this means that the EGM, following the completion of the current game cycle, MUST NOT initiate any new games, accept any money in or dispense any money out (including transfers and vouchers). Essentially, the EGM is frozen. The application logic of a device or a host may lock out the EGM. When the EGM is locked out by a device, the egmState attribute of the cabinetStatus command is set to or G2S_hostLocked, as appropriate. The deviceClass and deviceId of the cabinetStatus command identify the first device that caused the EGM-locked condition. G2S_egmLocked If the lock is cleared and a second one exists, the cabinet class would still show a lock, with the deviceClass and deviceId being updated to indicate the device now causing the lock. If multiple locks are serially applied, for example, three in the order of the first for 1 (one) minute, the second for 2 (two) minutes, and the third for 3 (three) minutes, the lock state changes as follows: • after one minute, the locking device changes from the 1-minute device to the 2-minute device. • after two minutes, the locking device changes from the 2-minute to the 3-minute device, and • after three minutes the EGM is no longer locked. The lock duration is calculated from the dateTime of the cabinetStatus response to the setCabinetLockout request or other condition causing the EGM to be locked. If an EGM becomes disabled while it is locked, the lock condition MUST be resolved before the EGM enters the disabled state. If an EGM becomes locked while it is disabled, the disable condition MUST be resolved before the EGM enters the locked state. The current state MUST be resolved before the EGM transitions to the new state. As the disables and locks are resolved, the text associated with them is displayed (if possible). It is important to note that the egmState is determined by aggregating the states of all devices within the EGM, including the state of the cabinet itself—that is, the egmEnabled, hostEnabled and hostLocked Page 98 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 attributes of the cabinetStatus command. The state of the cabinet is only one factor in determining the state of the EGM that is reflected in the egmState attribute. The enableMoneyIn and enableMoneyOut attributes should be interpreted as controlling currency devices and player initiated funds transfers through voucher and WAT mechanisms. The attributes are intended for use in an orderly shut down of a casino, such as a cruise ship approaching port. They are not intended to effect transfers that resolve game play such as handpay, bonus or progressive payouts. 3.4 Cabinet Doors The cabinet class has three logical doors. The doors are defined in terms of the type of access that they provide. The physical structure of an EGM cabinet may provide more or less doors than defined here. It is up to the manufacturer of the EGM to determine which type of access is provided by a particular physical door and then to categorize it appropriately. The supported door types within the cabinet class are: logic door Accesses the main processor board and its ancillary components. Opening this door allows access to the game chips or other components related to game determination. auxiliary door Accesses auxiliary storage area associated with the EGM used to store fills or other items of value. Opening this door allows the fills or other items of value to be accessed or removed. cabinet door Accesses other EGM components not addressed above. Opening a single physical door may provide access to one or more logical areas. In this case, when a single door is opened, more than one type of door-open attribute may have to be set. Typically, if the logic door is open then the cabinet door is probably also open. Other classes, such as hopper, coinAcceptor, noteAcceptor and noteDispenser, also have logical doors which are reported in their respective classes. These logical doors are included in those classes to facilitate the reporting of the currency meters when the funds are accessed. (By including the door open meter in with the currency meters, when the door is opened, the meter set changes, and so can easily be included as associated data with the event.) See those classes for further details. 3.5 Meters A set of meters is associated with the cabinet class (see Section 5.25.3.9 in the meters class). These meters are used to report the value of each of the credit meters, historic game play counts, and counters that record the number of times each of the cabinet doors have been opened. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 99 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.6 Request-Response Pairs The following table organizes the commands contained within the cabinet class into request-response pairs: Table 3.1 Commands Originated by Host Request Response Owner Guest getCabinetStatus cabinetStatus Yes Yes getCabinetProfile cabinetProfile Yes Yes setCabinetState cabinetStatus Yes No setCabinetLockOut cabinetStatus Yes No setDateTime cabinetDateTime Yes No getDateTime cabinetDateTime Yes Yes resetProcessor resetStarted Yes No Page 100 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.7 setCabinetState Command This command is used by the host to set the state of the cabinet. It also provides granular control over major functions such as playability, money in, and money out. The host can disable the cabinet which effectively stops all processing of game play and money handling actions by the EGM. For all intents and purposes, disabling the cabinet is equivalent to disabling the EGM. The EGM must complete any game play currently under way before disablement. A disableText message is provided as a notice to the player, if the EGM is capable of message display. The EGM responds to a setCabinetState command with the cabinetStatus command, after taking the action specified by the host. If cash-out is indicated, the optionConfig class may specify whether cash-out must be by voucher, hopper or WAT. The EGM disable conditions persist until reset by a setCabinetState command with enable = "true". command should be used when EGM disablement is expected to last indefinitely. For cases where the EGM should be disabled for a set period of time, use the setCabinetLockOut command with its corresponding lockTimeOut attribute set accordingly. The setCabinetState Table 3.2 setCabinetState Attributes Attribute Restrictions Description enable type: boolean use: optional default: true Indicates whether the cabinet should be enabled or disabled. disableText type: textMessage use: optional default: <empty> Optional message to display while the device is disabled. enableGamePlay type: boolean use: optional default: true If set to false, indicates the EGM is to cease all game play after any operations that are in process cease, for example base games and bonus games. enableMoneyIn type: boolean use: optional default: true If set to false, indicates the EGM is to cease accepting money in after any operations that are in process cease. enableMoneyOut type: boolean use: optional default: true If set to false, indicates the EGM is to cease dispensing money out after any operations that are in process cease. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 101 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.8 getCabinetStatus Command This command is used by the host to request the current status of the cabinet from the EGM. The EGM sends a cabinetStatus command in response to the getCabinetStatus command. The getCabinetStatus command has no additional attributes or elements. 3.9 cabinetStatus Command This command is used by the EGM to send the current status of the cabinet components to a host system. The cabinetStatus includes the EGM’s state (enabled, disabled, locked), last game played and door status information. The cabinetStatus command is sent in response to the setCabinetState and getCabinetStatus commands. Table 3.3 cabinetStatus Attributes (Sheet 1 of 2) Attribute Restrictions Description This first set of attributes indicates the overall state of the cabinet device. configurationId type: configurationId use: optional default: 0 Configuration identifier set by the option configuration host. egmEnabled type: boolean use: optional default: true Indicates whether the cabinet has been enabled by the EGM. hostEnabled type: boolean use: optional default: true Indicates whether the cabinet has been enabled by the host. enableGamePlay type: boolean use: optional default: true Indicates if host has enabled game play. enableMoneyIn type: boolean use: optional default: true Indicates if host has enabled money in devices. enableMoneyOut type: boolean use: optional default: true Indicates if host has enabled money out devices. hostLocked type: boolean use: optional default: false Indicates whether the EGM has been locked by the host. The current state of the EGM is reflected in the egmState attribute. The deviceClass and deviceId attributes following it indicate which device is causing a disable or lock. The host can request device descriptors to discover which additional devices have been disabled or locked. egmState Page 102 type: egmStates use: required Indicates the current state of the EGM, enabled, disabled, locked, and so on. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 Table 3.3 cabinetStatus Attributes (Sheet 2 of 2) Attribute Restrictions Description deviceClass type: deviceClass use: required Device class causing the disabled or locked state; otherwise the gamePlay class. deviceId type: deviceId Use; required Device identifier causing the disabled or locked state; otherwise, deviceId of the last game played; if no games played then first active gamePlay device. The next set of attributes provides information relative to last game played. of the last game played; if no games played then set to 0. gamePlayId type: deviceId use: required deviceId themeId type: themeId use: required themeId of the last game played; if no games played then set to G2S_none. paytableId type: paytableId use: required paytableId denomId type: denomId use: required denomId of the last game played; if no games played then set to 0. maxWagerCredits type: int use: required minIncl: 1 Maximum bet of the last game played; if no games played then set to 1. of the last game played; if no games played then set to G2S_none. The final set of attributes provides information on the state of doors, buttons and hard meters associated with the cabinet. serviceLampOn type: boolean use: optional default: false Indicates whether the service lamp is on. logicDoorOpen type: boolean use: optional default: false Indicates whether a logic door is open. logicDoorDateTime type: dateTime use: optional default: <null> Gives the date and time of the last logic door opening. auxDoorOpen type: boolean use: optional default: false Indicates whether an auxiliary door is open. auxDoorDateTime type: dateTime use: optional default: <null> Gives the date and time of the last auxiliary door opening. cabinetDoorOpen type: boolean use: optional default: false Indicates whether a cabinet door is open. cabinetDoorDateTime type: dateTime use: optional default: <null> Gives the date and time of the last cabinet door opening. hardMetersDisconnected type: boolean use: optional default: false Indicates whether the hard meters have been disconnected. If not supported by the device then default to false. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 103 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.10 getCabinetProfile Command This command is used by the host to request the current profile of the cabinet from the EGM. The EGM sends a cabinetProfile command in response to the getCabinetProfile command. The getCabinetProfile command has no additional attributes or elements. 3.11 cabinetProfile Command This command is used by the EGM to report the current profile of the cabinet. The profile contains the protocol-related configuration option selections for the cabinet device. The configuration options can be set locally at the EGM or remotely via a configuration server using commands within the optionConfig class. The cabinetProfile includes the EGM’s base currency, locale, location, and so on. The cabinetProfile command is sent in response to the getCabinetProfile command. Table 3.4 cabinetProfile Attributes (Sheet 1 of 2) Attribute Restrictions Description configurationId * type: configurationId use: optional default: 0 Last configuration identifier set by a G2S host; set to 0 (zero) when configuration changes are made by hosts other than G2S hosts. restartStatus * type: boolean use: optional default: true Indicates the state of hostEnabled when the EGM restarts. useDefaultConfig * type: boolean use: optional default: false Indicates whether the default configuration for the device MUST be used when the EGM restarts. requiredForPlay * type: boolean use: optional default: false Indicates whether the EGM MUST be disabled if either egmEnabled or hostEnabled is set to false. machineNum * type: machineNum use: required Casino assigned number identifier for the EGM. machineId * type: machineId use: optional default: <empty> Site-assigned alphanumeric identifier for the EGM. currencyId * type: currencyId use: required Base currency of the EGM. reportDenomId * type: denomId use: required Property assigned denomination used for reporting. localeId * type: localeId use: required Locale identifier of the EGM. areaId * type: areaId use: optional default: <empty> Area identifier per operator’s property layout. Page 104 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 Table 3.4 cabinetProfile Attributes (Sheet 2 of 2) Attribute Restrictions Description zoneId * type: zoneId use: optional default: <empty> Zone identifier per operator’s property layout. bankId * type: bankId use: optional default: <empty> Bank identifier per operator’s property layout. egmPosition * type: egmPosition use: optional default: <empty> EGM position within the bank. machineLoc * type: machineLoc use: optional default: <empty> EGM physical location identifier. For example: zoneId+bankId+egmPosition; set by the operator. cabinetStyle * type: cabinetStyles use: required Cabinet style of the EGM. largeWinLimit * type: meterValue use: required Maximum win payable by the EGM. maxCreditMeter * type: meterValue use: required Maximum value permitted on the credit meter. maxHopperPayOut * type: meterValue use: required Maximum value that can be paid from the hopper before a handpay, voucher, or WAT transaction is required. splitPayOut * type: boolean use: required When maxHopperPayOut is reached, indicates whether the maxHopperPayOut amount should be paid from the hopper. idleTimePeriod * type: milliseconds use: required Amount of time, in milliseconds, with a 0 (zero) credit meter and no player input before an EGM is considered idle. timeZoneOffset* * type: string use: required pattern: [+-]{1}[09]{2}[:]{1}[0-9]{2} The offset from Universal Coordinate Time (UCT) to local time that should be used when displaying date and time to a local user of the EGM; specified as ±HH:MM; changes caused by daylight savings time MUST be managed by the option configuration server. acceptNonCashAmts * type: acceptNonCashAmts use: optional default: G2S_acceptAlways Controls when an EGM MAY accept noncashable transfers to the EGM from any source. * Standard configuration option that MUST be included in the standard option configuration group – G2S_cabinetOptions – for devices within the cabinet class. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 105 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.12 setCabinetLockOut Command This command is used by the host to freeze the EGM—that is, no money in or out, and no game play (after the game currently in process ends). Only the owner of the device can execute this command. The cabinetStatus command is sent in response to setCabinetLockOut command. While the EGM is locked out, the message in the lockText attribute of this command MUST be displayed if the EGM has sufficient resources to do so. The setCabinetState command should be used when EGM disablement is expected to last indefinitely. For cases where the EGM should be disabled for a set period of time, use the setCabinetLockOut command with the lockTimeOut attribute set accordingly. Note that the lockout duration, defined in the lockTimeOut attribute, is calculated from the dateTime of the command that is sent in response to the setCabinetLockOut command. cabinetStatus Table 3.5 setCabinetLockOut Attributes Attribute Restrictions Description lockOut type: boolean use: optional default: false Indicate whether the EGM should be locked out from play. lockText type: textMessage use: optional default: <empty> Text message that should be displayed while the EGM is locked out. lockTimeOut type: lockTimeOut use: optional default: 1000 Maximum duration of the lock, in milliseconds. If a lock has not been removed within the specified time frame, the EGM should unlock itself. Page 106 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.13 setDateTime Command This command is used by a host to set the current date and time of an EGM. It is recommended that if the owner host detects that an EGM’s date and time are off by more than 5 (five) seconds, the host should attempt to reset the EGM’s date/time. Only the owner of the cabinet class may use this command. The cabinetDateTime command is sent in response the to setDateTime command. If the date/time was changed by more than 5 (five) seconds, the G2S_CBE315 be generated. Date/Time Changed event must NOTE: If an EGM is getting its date and time from an NTP server or other automated means, this command should not be used and, if the EGM does receive this command and is getting the date and time from an NTP server, the EGM MUST respond with error code G2S_CBX001 Command Ignored, Other Time Source in Use. Table 3.6 setDateTime Attributes Attribute Restrictions Description cabinetDateTime type: dateTime use: required Date and time to be used by EGM to immediately update its internal clock. 3.14 getDateTime Command This command is used by a host to request the current date and time of an EGM. The cabinetDateTime command is sent in response to the getDateTime command. The getDateTime command contains no additional attributes or elements. 3.15 cabinetDateTime Command This command is used by an EGM to send its current date/time to a host. The cabinetDateTime command is sent in response to the setDateTime and getDateTime commands. Table 3.7 cabinetDateTime Attributes Attribute Restrictions Description cabinetDateTime type: dateTime use: required Current date and time of the EGM. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 107 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.16 resetProcessor Command This command is intended to be used to recover from conditions where automatic recovery might not otherwise be possible. When implementing this command, the focus should be on resetting the EGM to the fullest extent practical. All other considerations (other than the integrity of critical data and required non-volatile information) should be secondary. This command is used by a host to initiate a cabinet reset of the EGM. Only the owner of the device may use this command. A resetStarted command is sent in response to the resetProcessor command. The resetProcessor command is an optional command that MAY be supported by the EGM. Before sending the resetProcessor command to the EGM, the host should first attempt to disable the EGM using the setCabinetState command. Regardless of the results of disabling the EGM, the host may send the resetProcessor command. When the EGM receives the resetProcessor command from the host, the EGM should perform the equivalent of a power cycle (power off and then power on) on the EGM and all its peripherals. Regardless of how the EGM manufacturer chooses to implement this functionality (such as hardware reset or an orderly shutdown and restart of software), the EGM manufacturer MUST ensure that all peripherals have been reset to the fullest extent practical. All required non-volatile memory MUST remain intact through this process. Prior to performing the command, the EGM MUST ensure the integrity of all critical data. resetProcessor The host should set a reasonable timeToLive on the resetProcessor command, giving the EGM enough time to perform a friendly shutdown (for example, allowing the player to finish game play and cash-out). The EGM MUST generate a G2S_CBE401 Cabinet Reset Started event before commencing the reset process. If the resetStarted response is sent, the event MUST be generated after the response. After completing the reset and restarting itself, the EGM must generate a G2S_CBE402 Remote Cabinet Reset event. There are no additional attributes or elements for this command. If the cabinet cannot perform a reset due to operational conditions, G2S_CBX002 should be sent. Page 108 Cannot Perform Reset error gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 3.17 Chapter 3 cabinet Class resetStarted Command This command is used by an EGM to report that it has initiated a cabinet reset. The resetStarted command is sent in response to a resetProcessor command. The resetStarted command is only required if the EGM supports the resetProcessor command. The EGM MUST send the resetStarted command when it determines that it is ready to perform the cabinet reset. After issuing the command, the EGM should close its communications queues (enter the G2S_closing state as defined within the communications class). When the communications queues are closed, the EGM may perform the cabinet reset. After sending the resetStarted command, the EGM MUST send a commsClosing command to each host to announce that communications will cease while the cabinet is reset. After resetting, the EGM MUST perform its normal restart/recovery sequence, sending commsOnLine commands to all registered hosts. There are no additional attributes or elements for this command. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 109 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.18 Data Types The following table lists the data types specific to the cabinet class: Table 3.8 cabinet Class Data Types Data Type Restrictions Description cabinetStyles type: extensibleList enumerations: Manufacturer-specific extensions to this enumeration list are permitted. See Section 3.18.1. egmStates type: string enumerations: Current state of the EGM. See Section 3.18.2. machineNum type: int minIncl: 0 Property-assigned EGM asset number. machineId type: string minLen: 0 maxLen: 8 Property-assigned EGM identifier. areaId type: string minLen: 0 maxLen: 8 Property-assigned area identifier, for physical site management purposes. zoneId type: string minLen: 0 maxLen: 8 Property-assigned zone identifier. bankId type: string minLen: 0 maxLen: 8 Property-assigned bank identifier within a zone. egmPosition type: string minLen: 0 maxLen: 8 Property-assigned EGM position within a bank. machineLoc type: string minLen: 0 maxLen: 16 Property-assigned machine location; composed of zone, bank and position. acceptNonCashAmts type: string enumerations: Controls when an EGM MAY accept non-cashable transfers. See Section 3.18.3. Page 110 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.18.1 Reserved cabinetStyles Data Type Enumerations Table 3.9 Reserved cabinetStyles Data Type Enumerations Enumeration Description G2S_slant Slant cabinet style. G2S_roundTop Round Top cabinet style. G2S_barTop Bar Top cabinet style. G2S_upRight Upright cabinet style. G2S_other Other cabinet style. G2S_unknown Unknown cabinet style. 3.18.2 egmStates Data Type Enumerations Table 3.10 egmStates Data Type Enumerations Enumeration Description G2S_transportDisabled EGM disabled by the transport layer. G2S_operatorDisabled EGM disabled via operator menu. G2S_hostDisabled EGM is disabled due to host. G2S_egmDisabled EGM disabled due to device failure or door open. G2S_enabled EGM enabled and available for play. G2S_operatorMode Operator menu active. G2S_demoMode Demo mode activated. G2S_auditMode Meters/audit mode active. G2S_operatorLocked EGM locked via operator menu. G2S_egmLocked EGM locked due to device action. G2S_hostLocked EGM locked due to host action. 3.18.3 acceptNonCashAmts Data Type Enumerations Table 3.11 acceptNonCashAmts Data Type Enumerations Enumeration Description G2S_acceptAlways Non-cashable credits MAY always be accepted even if the credit meter already has non-cashable credits on it. G2S_acceptSameExpiration Non-cashable credits MUST NOT be accepted if the credit meter already has non-cashable credits on it and the expirations are different. G2S_acceptNoMix Non-cashable credits MUST NOT be accepted if the credit meter already has non-cashable credits on it. G2S_acceptNever Non-cashable credits MUST NOT be accepted under any conditions. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 111 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.19 Error Codes The following table lists the error codes specific to the cabinet class: Table 3.12 cabinet Class Error Codes Error Code Suggested Error Text G2S_CBX001 Command Ignored, Other Time Source In Use G2S_CBX002 Cannot Perform Reset Page 112 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.20 Event Codes The following table summarizes the events that may be generated by devices within the cabinet class. A full description of each event follows the table. Table 3.13 cabinet Class Event Codes (Sheet 1 of 3) (CB = cabinet, GP = gamePlay, JP = handpay, CA = coinAcceptor, NA = noteAcceptor, HP = hopper, ND = noteDispenser, PT = printer, PG = progressive, BN = bonus, PR = player, VC = voucher, WT = WAT) Affected Device Logs, Meters, Statuses Event Code CB G2S_CBE001 EGM Disabled Cabinet S G2S_CBE002 EGM Enabled Cabinet S G2S_CBE003 Host Disabled Cabinet S G2S_CBE004 Host Enabled Cabinet S GP JP CA NA HP ND PT PG BN PR VC WT G2S_CBE005 Host Changed Cabinet Config G2S_CBE006 Operator Changed Cabinet Config G2S_CBE009 Host Locked Cabinet S G2S_CBE010 Host Unlocked Cabinet S G2S_CBE101 Host Disabled Game Play S G2S_CBE102 Host Enabled Game Play S G2S_CBE103 Host Disabled Money In S G2S_CBE104 Host Enabled Money In S G2S_CBE105 Host Disabled Money Out S G2S_CBE106 Host Enabled Money Out S G2S_CBE201 Comms Issue EGM Disabled S G2S_CBE202 EGM Disabled - Operator Menu S G2S_CBE203 Device Failure Disabled EGM S G2S_CBE204 Host Command Disabled EGM S gsa-p0075.003.01 Released: 2007/04/12 Page 113 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 Table 3.13 cabinet Class Event Codes (Sheet 2 of 3) (CB = cabinet, GP = gamePlay, JP = handpay, CA = coinAcceptor, NA = noteAcceptor, HP = hopper, ND = noteDispenser, PT = printer, PG = progressive, BN = bonus, PR = player, VC = voucher, WT = WAT) Affected Device Logs, Meters, Statuses Event Code CB G2S_CBE205 EGM Enabled and Playable S G2S_CBE206 Operator Menu Activated S G2S_CBE207 Demo Mode Activated S G2S_CBE208 Meters/Audit Mode Initiated S G2S_CBE209 EGM Locked - Operator Menu S G2S_CBE210 Device Action Locked EGM S G2S_CBE211 Host Action Locked EGM S G2S_CBE301 Service Lamp On S G2S_CBE302 Service Lamp Off S G2S_CBE303 Logic Door Open SM G2S_CBE304 Logic Door Closed G2S_CBE305 Auxiliary Door Open G2S_CBE306 Auxiliary Door Closed GP JP CA NA HP ND PT PG BN PR VC WT S SM S G2S_CBE307 Cabinet Door Open SM G2S_CBE308 Cabinet Door Closed SM G2S_CBE309 General Cabinet Tilt S G2S_CBE310 Video Display Error S G2S_CBE311 NVM Failure S G2S_CBE312 General Memory Failure S G2S_CBE313 Cabinet Tilt Cleared S gsa-p0075.003.01 Released: 2007/04/12 Page 114 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 Table 3.13 cabinet Class Event Codes (Sheet 3 of 3) (CB = cabinet, GP = gamePlay, JP = handpay, CA = coinAcceptor, NA = noteAcceptor, HP = hopper, ND = noteDispenser, PT = printer, PG = progressive, BN = bonus, PR = player, VC = voucher, WT = WAT) Affected Device Logs, Meters, Statuses Event Code CB G2S_CBE314 Game Combo Activated S G2S_CBE315 Date/Time Changed S GP JP CA NA HP ND PT PG BN PR VC WT G2S_CBE316 Cash-Out Button Pressed G2S_CBE317 Power Off - Logic Door Open M G2S_CBE318 Power Off - Auxiliary Door Open M G2S_CBE319 Power Off - Cabinet Door Open M G2S_CBE320 Operator Reset Cabinet G2S_CBE321 Life-To-Date Meters Reset LM LM LM LM LM LM LM LM LM LM LM LM LM G2S_CBE322 NVM Cleared LMS LMS LMS LMS LMS LMS LMS LMS LMS LMS LMS LMS LMS G2S_CBE323 Backup Battery Low G2S_CBE324 EGM Power Lost G2S_CBE325 EGM Power Up M G2S_CBE326 Hard Meters Disconnected S G2S_CBE327 Hard Meters Reconnected S G2S_CBE401 Cabinet Reset Started S G2S_CBE402 Remote Cabinet Reset S gsa-p0075.003.01 Released: 2007/04/12 Page 115 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 The following table lists the elements contained within the cabinet class which may be included as affected data with events: Table 3.14 Elements Included With Events Affected Data Element Device Status cabinetStatus 3.20.1 evaluate(state) The egmEnabled and egmState attributes are both determined from multiple factors. If all of the faults for a device have been cleared then the egmEnabled attribute for the device can be set to true. If any one fault still exists then the egmEnabled attribute MUST be set to false. Thus, after a fault is cleared, the EGM MUST evaluate all of the attributes that contribute to the state of the egmEnabled attribute. If anyone of them shows a fault then the egmEnabled attribute MUST remain false. This is communicated in the following documentation by using the convention "evaluate(cabinet.egmEnabled)". Likewise, the egmState attribute of the cabinetStatus reflects the aggregate state of all devices in the EGM. If the requiredForPlay attribute in the profile of a device is set to true then if either the egmEnabled or hostEnabled attribute of the device is set to false, the egmState MUST reflect that the EGM is disabled. Similarly, if the egmLocked or hostLocked attribute of a device is set to true then the egmState MUST reflect that the EGM is locked out. If any one device is in such a state then the egmState MUST reflect that the EGM is disabled or locked out, as appropriate. Thus, after a device has been enabled or a lockout has been cleared, the EGM MUST evaluate the state of all active devices within the EGM to determine the proper value of the egmState attribute. At the same time, the deviceClass and deviceId attributes of the cabinetStatus MUST be updated to reflect the appropriate device. This is communicated in the following documentation by using the convention "evaluate(cabinet.egmState)". 3.20.2 G2S_CBE001 EGM Disabled Cabinet This event is sent by the EGM whenever a device internal to the EGM has disabled the entire cabinet. All player accessible operations of the cabinet are disabled. Game play operations in process should complete. A message to the player should be displayed, similar to the message a host may display with the disableText attribute in the setCabinetState command. Credits and player points currently held on the cabinet may be disbursed if specified by the configuration class. Disablement due to a device failure should use the G2S_CBE203 Device Failure Disabled EGM event to report EGM disabled due to device failure. Table 3.15 G2S_CBE001 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmEnabled = "false". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. Page 116 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 3.20.3 Chapter 3 cabinet Class G2S_CBE002 EGM Enabled Cabinet The event is sent upon clearing of all locked or disabled conditions. All player accessible operations of the cabinet are enabled. This event is likely to be precipitated by a host enabling the cabinet or devices within the cabinet coming online. Commands such as setCabinetState are likely to result in this event being sent. Table 3.16 G2S_CBE002 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmEnabled = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 3.20.4 G2S_CBE003 Host Disabled Cabinet Processing for this event begins in response to the setCabinetState command from a host instructing the EGM to disable. Game play operations in process should complete. Credits and player points currently held on the cabinet are disbursed as directed by configuration settings. A message to the player is displayed as called out in disabledText of setCabinetState. As soon as all player accessible operations of the cabinet are disabled, this event is sent. The setCabinetState command is used by a host to set the state of the cabinet. As such it controls when this event occurs. Table 3.17 G2S_CBE003 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.hostEnabled = "false". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands setCabinetState. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 117 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.20.5 G2S_CBE004 Host Enabled Cabinet This event is sent after a disable condition initiated by the host is cleared and all player accessible operations of the cabinet are enabled. The setCabinetState command is used by a host to set the state of the cabinet. As such it controls when this event occurs. Table 3.18 G2S_CBE004 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.hostEnabled = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands setCabinetState. 3.20.6 G2S_CBE005 Host Changed Cabinet Config This event is sent if any of the options described in Section 3.11 cabinetProfile Command is changed by a host. Examples would be a change to bankId or idleTimePeriod. Table 3.19 G2S_CBE005 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands optionChangeStatus. 3.20.7 G2S_CBE006 Operator Changed Cabinet Config This event is sent if any of the options described in Section 3.11 cabinetProfile Command is changed by an operator. Examples would be a change to bankId or idleTimePeriod. The event should be sent once the option is committed to persistent data storage. There are no device state changes associated with this event directly; although for this event to be generated, the main door would most likely need to be opened and the operator menu on the EGM entered into. As such the EGM should be in the G2S_operatorMode state. Table 3.20 G2S_CBE006 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. Page 118 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 3.21 3.21.1 Chapter 3 cabinet Class Events: Resulting from setCabinetLockOut G2S_CBE009 Host Locked Cabinet Processing for this event begins in response to the setCabinetLockOut command from a host instructing the EGM to lockout. Game play operations in process should complete. Credits and player points currently held on the cabinet are disbursed as directed by configuration settings. All game play, money in and money out devices cease operation for the duration defined by lockTimeOut, and calculated from the dateTime of the cabinetStatus command that is sent in response to the setCabinetLockOut command. A message is provided to the player as defined by the lockText attribute in the setCabinetLockOut command. As soon as all player accessible operations of the cabinet are disabled, this event is sent. The setCabinetLockOut command is used by a host to lock the cabinet. As such it controls when this event occurs. Status is reported in cabinetStatus command. Table 3.21 G2S_CBE009 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.hostLocked = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands setCabinetLockOut. 3.21.2 G2S_CBE010 Host Unlocked Cabinet Processing for this event begins in response to the setCabinetLockOut command from a host instructing the EGM to clear the locked condition. Any lockTimeOut currently in process is cancelled. Game play operations may commence. As soon as all player accessible operations of the cabinet are enabled, this event is sent. The setCabinetLockOut command is used by a host to unlock the cabinet. As such it controls when this event occurs. Status is reported in cabinetStatus command. Table 3.22 G2S_CBE010 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.hostLocked = "false". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands setCabinetLockOut. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 119 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.22 3.22.1 Events: Resulting from setCabinetState G2S_CBE101 Host Disabled Game Play Processing for this event begins in response to the setCabinetState command from a host instructing the EGM to disable game play. All game play is halted, after any play action that is currently in progress completes. Game play cannot continue until an enabled condition is initiated locally or by the host. A message to the player is displayed as called out in the disabledText attribute of the setCabinetState command. Money in and out devices may be available for the player to cash out, as determined by configuration settings. As soon as all game play operations of the cabinet are disabled, this event is sent. The EGM remains in this state until a host or operator reverses it. The setCabinetState command is used by a host to set the state of the cabinet. As such it controls when this event occurs. Table 3.23 G2S_CBE101 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.enableGamePlay = "false". Meter State Changes None. Log State Changes None. Related Commands setCabinetState. 3.22.2 G2S_CBE102 Host Enabled Game Play Processing for this event begins in response to the setCabinetState command from a host instructing the EGM to enable game play. Companion to the G2S_CBE101 Host Disabled Game Play event. The setCabinetState command is used by a host to set the state of the cabinet. As such it controls when this event occurs. Table 3.24 G2S_CBE102 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.enableGamePlay = "true". Meter State Changes None. Log State Changes None. Related Commands setCabinetState. Page 120 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 3.22.3 Chapter 3 cabinet Class G2S_CBE103 Host Disabled Money In Processing for this event begins in response to the setCabinetState command from a host instructing the EGM to disable money input devices. Money acceptance functions of the EGM are disabled after any operation that is currently in process, and remain disabled until locally or remotely enabled. As soon as all money input devices of the EGM are disabled, this event is sent. The setCabinetState command is used by a host to set the state of the cabinet. As such it controls when this event occurs. Table 3.25 G2S_CBE103 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.enableMoneyIn = "false". Meter State Changes None. Log State Changes None. Related Commands setCabinetState. 3.22.4 G2S_CBE104 Host Enabled Money In Processing for this event begins in response to the setCabinetState command from a host instructing the EGM to enable money in devices. Companion to the G2S_CBE103 Host Disabled Money In event. The setCabinetState command is used by a host to set the state of the cabinet. As such it controls when this event occurs. Table 3.26 G2S_CBE104 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.enableMoneyIn = "true". Meter State Changes None. Log State Changes None. Related Commands setCabinetState. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 121 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.22.5 G2S_CBE105 Host Disabled Money Out Processing for this event begins in response to the setCabinetState command from a host instructing the EGM to disable money output devices. Money disbursement functions of the EGM are disabled after any payout operation that is currently in process, and remain disabled until locally or remotely enabled. As soon as all money output devices of the EGM are disabled, this event is sent. The setCabinetState command is used by a host to set the state of the cabinet. As such it controls when this event occurs. Table 3.27 G2S_CBE105 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.enableMoneyOut = "false". Meter State Changes None. Log State Changes None. Related Commands setCabinetState. 3.22.6 G2S_CBE106 Host Enabled Money Out Processing for this event begins in response to the setCabinetState command from a host instructing the EGM to enable money out devices. Companion to G2S_CBE105 Host Disabled Money Out. The setCabinetState command is used by a host to set the state of the cabinet. As such it controls when this event occurs. Table 3.28 G2S_CBE106 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.enableMoneyOut = "true". Meter State Changes None. Log State Changes None. Related Commands setCabinetState. Page 122 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.23 3.23.1 Events: Resulting from cabState Changes G2S_CBE201 Comms Issue EGM Disabled EGM is disabled due to an issue, transportDisabled, from the communications class. Processing for this event begins in response to the EGM detecting an issue related to message transport causing the EGM to disable. Game play operations that are in process should complete. Credits and player points currently held on the cabinet are disbursed as directed by configuration settings. A message to the player should be displayed similar to the disabledText of setCabinetState. As soon as all player accessible operations of the cabinet (money in, money out, game play) are disabled, this event is sent. Table 3.29 G2S_CBE201 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_transportDisabled". set to reflect device creating the disable condition cabinet.deviceId set to reflect device creating the disable condition. cabinet.deviceClass Meter State Changes None. Log State Changes None. Related Commands None. 3.23.2 G2S_CBE202 EGM Disabled - Operator Menu Processing for this event begins in response to operator action at the EGM menu. Game play operations that are in process should complete. Credits and player points currently held on the cabinet are disbursed as directed by configuration settings. A message to the player should be displayed similar to the disabledText of setCabinetState command. As soon as all player accessible operations of the cabinet (money in, money out, game play) are disabled, this event is sent. The disabled state is held until cleared by an operator at the EGM or by host command. Table 3.30 G2S_CBE202 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_operatorDisabled". = "G2S_cabinet". set to currently active cabinet device. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 123 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.23.3 G2S_CBE203 Device Failure Disabled EGM This event is sent by the EGM whenever a device internal to the EGM has a failure, disabling the entire cabinet. All player accessible operations of the cabinet are disabled. Game play operations in process should complete. A message to the player should be displayed, similar to the message a host may display with disableText. Credits and player points currently held on the cabinet may be disbursed if specified by the configuration class. Disablement due to other EGM reasons should use the G2S_CBE001 EGM Disabled Cabinet event to report EGM disabled. Table 3.31 G2S_CBE203 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_egmDisabled". set to reflect device creating the disable condition. set to reflect device creating the disable condition. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. 3.23.4 G2S_CBE204 Host Command Disabled EGM This event differs from the G2S_CBE003 Host Disabled Cabinet event in that the EGM is being disabled because of something that happened on the EGM as commanded by the host. For example, if the host tells the voucher class to disable and the EGM configuration requires the voucher class for EGM operation, then this event would be sent to indicate the EGM is disabled, not due to a direct host disable command but due to consequences of a command issued by the host. Table 3.32 G2S_CBE204 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_hostDisabled". set to reflect device creating the disable condition. set to reflect device creating the disable condition. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. Page 124 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.23.5 G2S_CBE205 EGM Enabled and Playable This event is sent after all disables, locks and tilts are cleared and the EGM is in a condition for play to commence. Table 3.33 G2S_CBE205 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_enabled". = "G2S_gamePlay". = Device identifier causing the disabled or locked state; otherwise, device identifier for the last game played; if no games played then the first active game play device. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. 3.23.6 G2S_CBE206 Operator Menu Activated This event is sent when the operator menu of an EGM is entered by action locally on the machine. It only affects the cabinet status. This event affects potentially all other devices in classes other than printer or player classes because entering this mode ceases all game play, money in and money out actions. All money in, money out and game play devices are rendered inoperable while in audit mode. No meters or logs are affected. Table 3.34 G2S_CBE206 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_operatorMode". = "G2S_cabinet". set to currently active cabinet device. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 125 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.23.7 G2S_CBE207 Demo Mode Activated This event is sent when the demo mode (or show mode or tournament mode) is initiated at the EGM. Typically these modes cease updating of game play meters. This event may also affect gamePlay class devices and meters because entering this mode ceases all game play metering. Table 3.35 G2S_CBE207 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_demoMode". = "G2S_cabinet". set to currently active cabinet device. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. 3.23.8 G2S_CBE208 Meters/Audit Mode Initiated This event is sent when the meters (or audit) mode is initiated at the EGM. This is the mode where you key the outside of the game with the main door closed to access a display of metering and game information. This event affects potentially all other devices in classes other than printer or player classes because entering this mode ceases all game play, money in and money out actions. All money in, money out and game play devices are rendered inoperable while in audit mode. Table 3.36 G2S_CBE208 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_auditMode". = "G2S_cabinet". set to currently active cabinet device. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. Page 126 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.23.9 G2S_CBE209 EGM Locked - Operator Menu This event is sent upon the EGM being locked locally by a person accessing the operator menu. This event affects potentially all other devices in classes other than printer or player classes since a lock ceases all game play, money in and money out actions. All money in, money out and game play devices are rendered inoperable for the duration defined by the EGM implementer. The duration is calculated from the dateTime of the cabinetStatus command that the EGM sends in response to the lockout. Table 3.37 G2S_CBE209 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_operatorLocked". = "G2S_cabinet". set to currently active cabinet device. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. 3.23.10 G2S_CBE210 Device Action Locked EGM This event is sent upon the EGM being locked by a device within the EGM. Text similar to that called out in lockText of the setCabinetLockOut command may be displayed to the patron, if possible. All money in, money out and game play devices are rendered inoperable for the duration defined by the EGM implementer. The lockout duration is calculated from the dateTime of the cabinetStatus command that the EGM sends in response to the lockout. Table 3.38 G2S_CBE210 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_egmLocked". set to reflect device creating the locked condition. set to reflect device creating the locked condition. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 127 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.23.11 G2S_CBE211 Host Action Locked EGM This event is sent upon the EGM being locked by a command from the host. The text called out in the lockText attribute of the setCabinetLockOut command is displayed to the patron, if possible. All money in, money out and game play devices are rendered inoperable for the time period called out in the lockTimeOut attribute of the setCabinetLockOut command. The lockout duration is calculated from the dateTime of the cabinetStatus command that the EGM sends in response to the lockout. Table 3.39 G2S_CBE211 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmState = "G2S_hostLocked". set to reflect device creating the disable condition. set to reflect device creating the disable condition. cabinet.deviceClass cabinet.deviceId Meter State Changes None. Log State Changes None. Related Commands None. Page 128 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 3.24 3.24.1 Chapter 3 cabinet Class Events: Resulting from cabinetStatus Changes G2S_CBE301 Service Lamp On This event is sent when the service lamp is activated. The event is also sent when the Service button is pressed, if the EGM is so provisioned. The EGM manufacturer should provide reasonable de-bouncing such that repeated pounding of the button by a patron does not result in multiple events to the host being sent. For example, one event sent every minute independent of the number of times the patron presses the button. Table 3.40 G2S_CBE301 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.serviceLampOn = "true". Meter State Changes None. Log State Changes None. Related Commands None. 3.24.2 G2S_CBE302 Service Lamp Off This event is sent when the service lamp is deactivated. The event is also sent when the Service button is pressed again after already being set on, if the EGM is so provisioned. The EGM manufacturer should provide reasonable de-bouncing such that repeated pounding of the button by a patron does not result in multiple events to the host being sent. For example, one event sent every minute independent of the number of times the patron presses the button. Table 3.41 G2S_CBE302 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.serviceLampOn = "false". Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 129 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.24.3 G2S_CBE303 Logic Door Open This event is sent when a logic door is opened. If the door is the first logic door to be opened, the egmEnabled attribute is set to false and logicDoorOpen attribute is set to true. Table 3.42 G2S_CBE303 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.logicDoorOpen = "true". cabinet.logicDoorDateTime = date/time of last logic door opening. cabinet.egmEnabled = "false". evaluate(cabinet.egmState). Meter State Changes The G2S_logicDoorOpenCnt meter is incremented by 1 (one). Log State Changes None. Related Commands None. 3.24.4 G2S_CBE304 Logic Door Closed This event is sent when a logic door is closed. If this is the last logic door to be closed, and no other doors, devices or hosts are holding the EGM in a disabled or locked condition, the egmEnabled attribute is set to true and the logicDoorOpen attribute may be set to false. Table 3.43 G2S_CBE304 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.logicDoorOpen = "false". evaluate(cabinet.egmEnabled). evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 3.24.5 G2S_CBE305 Auxiliary Door Open This event is sent when an auxiliary door is opened. If it is the first to be opened, egmEnabled is set to false and auxDoorOpen is set to true. Table 3.44 G2S_CBE305 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinetStatus.auxDoorOpen = "true". cabinetStatus.auxDoorDateTime = date/time of last auxiliary door opening. cabinetStatus.egmEnabled. evaluate(cabinet.egmState). Meter State Changes G2S_auxDoorOpenCnt Log State Changes None. Related Commands None. Page 130 meter is incremented by 1 (one). gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.24.6 G2S_CBE306 Auxiliary Door Closed This event is sent when an auxiliary door is closed; if the last auxiliary door to be closed and no other doors, devices or hosts are holding the EGM in a disabled or locked condition, egmEnabled and egmState may be set to indicate an enabled state, and auxiliaryDoorOpen set to false. Table 3.45 G2S_CBE306 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.auxiliaryDoorOpen = "false". evaluate(cabinet.egmEnabled). evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 3.24.7 G2S_CBE307 Cabinet Door Open This event is sent when a cabinet door is opened; and if the first door opened, cabinetDoorOpen is set to true and egmEnabled may be set to indicate a disabled condition. Table 3.46 G2S_CBE307 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.cabinetDoorOpen = "true". cabinet.cabinetDoorDateTime = cabinet.egmEnabled = "false". evaluate(cabinet.egmState). Meter State Changes G2S_cabinetDoorOpenCnt Log State Changes None. Related Commands None. 3.24.8 date/time of last cabinet door opening. meter is incremented by 1 (one). G2S_CBE308 Cabinet Door Closed This event is sent when a cabinet door is closed; and if the last cabinet door to be closed and no other doors, devices or hosts is holding the EGM in a disabled or locked condition, egmEnabled may be set to true and cabinetDoorOpen set to false. Table 3.47 G2S_CBE308 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.cabinetDoorOpen = "false". evaluate(cabinet.egmEnabled). evaluate(cabinet.egmState). Meter State Changes G2S_gamesSinceDoorClosedCnt Log State Changes None. Related Commands None. is set to 0 (zero). gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 131 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.24.9 G2S_CBE309 General Cabinet Tilt This event is sent if a tilt occurs that does not fit any of the pre-defined tilts (G2S_CBE301 through G2S_CBE312); and if this disables the EGM, egmEnabled is set to false. Table 3.48 G2S_CBE309 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmEnabled = "false" evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 3.24.10 G2S_CBE310 Video Display Error This event is sent when a problem with video displays is detected. This event may be used if the EGM can detect that a video cable is not plugged in. If this places the EGM in a disabled state, egmEnabled is set to false. Table 3.49 G2S_CBE310 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmEnabled = "false". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 3.24.11 G2S_CBE311 NVM Failure This event is sent when a problem with non-volatile RAM is detected. If this places the EGM in a disabled state, egmEnabled is set to false. Table 3.50 G2S_CBE311 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmEnabled = "false". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. Page 132 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 3.24.12 Chapter 3 cabinet Class G2S_CBE312 General Memory Failure This event is sent when a problem with any EGM memory is detected. If this places the EGM in a disabled state, egmEnabled is set to false. Table 3.51 G2S_CBE312 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmEnabled = "false". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 3.24.13 G2S_CBE313 Cabinet Tilt Cleared This event is sent after all tilts are cleared. Tilts include events G2S_CBE301 through G2S_CBE312. The EGM state is likely to be affected by this event as it may place the EGM in an enabled condition. Table 3.52 G2S_CBE313 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.egmEnabled = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 3.24.14 G2S_CBE314 Game Combo Activated This event will be sent after the player has committed to the selected game combination by placing a wager, thus activating the game combination. The gamePlayId, themeId, paytableId, denomId and maxWagerCredits are updated to reflect the current game in play. Table 3.53 G2S_CBE314 Device, Meter, Log Changes, and Related Commands Details Device State Changes = updated to reflect current game in play. = updated to reflect current game in play. cabinet.paytableId = updated to reflect current game in play. cabinet.denomId = updated to reflect current game in play. cabinet.maxWagerCredits = updated to reflect current game in play. evaluate(cabinet.egmState). cabinet.gamePlayId cabinet.themeId Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 133 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.24.15 G2S_CBE326 Hard Meters Disconnected This event is sent when the EGM detects that the hard meters (electro-mechanical meters) have been disconnected. This event is also sent when an EGM discovers that, upon power up, the hard meters have been disconnected. This event is only used to indicate hard meters have been disconnected and MUST NOT be sent if the EGM does not support hard meters. Table 3.54 G2S_CBE326 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.hardMetersDisconnected = "true". Meter State Changes None. Log State Changes None. Related Commands None. 3.24.16 G2S_CBE327 Hard Meters Reconnected This event is sent when an EGM detects that the hard meters have been reconnected after being previously disconnected. This event is not sent upon power up if the hard meters are found to be connected. This event MUST NOT be sent if the EGM does not support hard meters. Table 3.55 G2S_CBE327 Device, Meter, Log Changes, and Related Commands Details Device State Changes cabinet.hardMetersDisconnected = "false". Meter State Changes None. Log State Changes None. Related Commands None. Page 134 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 3.25 3.25.1 Chapter 3 cabinet Class Events: Resulting from setDateTime G2S_CBE315 Date/Time Changed This event is sent when the date and/or time is modified by either the host or locally at the operator menu if the date/time was changed by more than 5 (five) seconds. Typically this event would be precipitated by the host issuing a setDateTime command or the operator menu being active and the operator manually modifying the date or time settings of the EGM. Table 3.56 G2S_CBE315 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands setDateTime. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 135 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.26 3.26.1 Events: Resulting from cabinetReset G2S_CBE401 Cabinet Reset Started This event is sent in response to a resetStarted command, if the EGM supports remote reset. This event notifies hosts that the EGM is about to go through a reset, allowing them to prepare any pending transactions. If the resetStarted command is supported, the EGM should perform the equivalent of a power cycle on the EGM and all peripherals. The cabinet device state should return to whatever state it was in before the reset was initiated. The resetStarted command causes this event to be sent. The host should have tried to disable the EGM first using setDeviceState command. Non-volatile memory should be persisted and notation in NV Ram should be made that the reset was caused by the resetProcessor command so that G2S_CBE402 Remote Cabinet Reset can be sent. Table 3.57 G2S_CBE401 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands resetStarted. 3.26.2 G2S_CBE402 Remote Cabinet Reset This event is sent following a reset initiated by resetProcessor command. This event notifies hosts that the EGM has gone through a reset, allowing them to prepare any pending transactions. The cabinet device state should return to whatever state it was in before the reset was initiated. The EGM should send a commsClosing command to each host to announce that communications will cease while the cabinet is reset. After resetting, the EGM MUST perform its normal restart/recovery sequence, sending commsOnLine commands to all registered hosts. Table 3.58 G2S_CBE402 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. Page 136 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 3.27 3.27.1 Chapter 3 cabinet Class Events: Not Related to Commands G2S_CBE316 Cash-Out Button Pressed This event is sent when the EGM cash-out button is pressed. The EGM manufacturer should provide reasonable de-bouncing such that repeated pounding of the button by a patron does not result in multiple events to the host being sent. For example, one event sent every minute independent of the number of times the patron presses the button. Table 3.59 G2S_CBE316 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. 3.27.2 G2S_CBE317 Power Off - Logic Door Open This event is sent if the EGM is capable of detecting whether any logic door has been opened when EGM power has been removed. If host communications are available, this event is sent immediately. If host communications are down, the event is queued for transmission upon communications re-establishment. Table 3.60 G2S_CBE317 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. 3.27.3 G2S_CBE318 Power Off - Auxiliary Door Open This event is sent if the EGM is capable of detecting whether any auxiliary door has been opened when EGM power has been removed. If host communications are available, this event is sent immediately. If host communications are down, the event is queued for transmission upon communications re-establishment. Table 3.61 G2S_CBE318 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 137 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.27.4 G2S_CBE319 Power Off - Cabinet Door Open This event is sent if the EGM is capable of detecting whether any cabinet door has been opened when EGM power has been removed. If host communications are available, this event is sent immediately. If host communications are down, the event is queued for transmission upon communications re-establishment. Table 3.62 G2S_CBE319 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. 3.27.5 G2S_CBE320 Operator Reset Cabinet This event is sent following a reset initiated locally by the operator or the EGM. The EGM should return to the state it was in before the operator or internal device initiated the reset. Table 3.63 G2S_CBE320 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. 3.27.6 G2S_CBE321 Life-To-Date Meters Reset This event is sent when all meters are reset to 0 (zero). Reset of meters may be done independently of reset of the entire EGM and all its configuration parameters. Meters, status and logs in all classes are updated. Meters are set to 0 (zero) and logs are cleared. The G2S_CBE311 NVM Failure event may be paired with this event. Table 3.64 G2S_CBE321 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. Page 138 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.27.7 G2S_CBE322 NVM Cleared This event is sent when long-term memory is cleared. Typically called saferam, this memory may contain meters and game setup information. The entire device state is being cleared and reset to whatever initial factory settings may be. Virtually every state in the EGM can be expected to change. Meters, status and logs in all classes are updated. Meters are set to 0 (zero) and logs are cleared. The G2S_CBE321 Life-To-Date Meters Reset event may be paired with this event. Table 3.65 G2S_CBE322 Device, Meter, Log Changes, and Related Commands Details Device State Changes All device statuses are updated. Meter State Changes All meters are reset to initial conditions, typically 0 (zero). Log State Changes None. Related Commands None. 3.27.8 G2S_CBE323 Backup Battery Low This event is sent when a problem with a backup power supply is detected. Typically the backup battery on persistent storage and or on the clock has a sensing capability to indicate when the battery is getting low and needs replacement. Table 3.66 G2S_CBE323 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. 3.27.9 G2S_CBE324 EGM Power Lost This event is sent when power to the EGM is removed. No specific state changes are directly associated with this event being sent. A power loss may effect devices within the EGM (for example, the printer and note acceptor) and the host connections. Thus, the egmState within cabinetStatus should be updated to reflect the appropriate state if such can be done by the EGM under power loss. Table 3.67 G2S_CBE324 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 139 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.27.10 G2S_CBE325 EGM Power Up This event is sent when the EGM has powered up and established communications with hosts. No specific state changes are directly associated with this event being sent. Dependent upon host commands and the EGM’s various device states the cabinetStatus and egmState will need to be updated to reflect the EGM’s powered up state. Table 3.68 G2S_CBE325 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes G2S_gamesSincePowerResetCnt Log State Changes None. Related Commands None. Page 140 is set to 0 (zero). gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.28 Examples 3.28.1 Cabinet Status Command Sequences HOST 3.28.1.1 EGM HOST EGM HOST EGM getCabinetStatus setCabinetState setCabinetLockOut cabinetStatus cabinetStatus cabinetStatus getCabinetStatus Request: Host to EGM The following example highlights the construction of a getCabinetStatus command sent from a host to an EGM. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2002" sessionType = "G2S_request" sessionId = "1002" timeToLive = "30000" sessionRetry = "false" > <getCabinetStatus /> </cabinet> 3.28.1.2 cabinetStatus Response: EGM to Host The following example highlights the construction of a cabinetStatus command sent from an EGM to a host in response to the receipt of a getCabinetStatus command. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3002" sessionType = "G2S_response" sessionId = "1002" > <cabinetStatus egmEnabled = "true" hostEnabled = "true" hostLocked = "false" enableGamePlay = "true" enableMoneyIn = "true" enableMoneyOut = "true" egmState = "G2S_enabled" deviceClass = "G2S_gamePlay" deviceId = "4" gamePlayId = "4" themeId = "GSA_3" paytableId = "GSA_5" denomId = "1000" maxWagerCredits = "3" serviceLampOn = "false" logicDoorOpen = "false" logicDoorDateTime = "2003-03-01T13:23:27.432-07:00" auxDoorOpen = "false" auxDoorDateTime = "2003-03-01T13:23:27.432-09:00" cabinetDoorOpen = "false" cabinetDoorDateTime = "2003-03-01T13:23:27.432-12:00" /> </cabinet> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 141 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.28.1.3 setCabinetState Request: Host to EGM The following example highlights the construction of a setCabinetState command sent from a host to an EGM. In this case a disable is called for and responded to. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2003" sessionType = "G2S_request" sessionId = "1003" timeToLive = "30000" sessionRetry = "false" > <setCabinetState enable = "false" disableText = "The ship is approaching port, all game play is suspended. Please contact your host." /> </cabinet> 3.28.1.4 cabinetStatus Response: EGM to Host The following example highlights the construction of a cabinetStatus command sent from an EGM to a host in response to the receipt of a setCabinetState command. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3003" sessionType = "G2S_response" sessionId = "1003" > <cabinetStatus egmEnabled = "true" hostEnabled = "false" hostLocked = "false" enableGamePlay = "true" enableMoneyIn = "true" enableMoneyOut = "true" egmState = "G2S_hostDisabled" deviceClass = "G2S_cabinet" deviceId = "1" gamePlayId = "4" themeId = "GSA_3" paytableId = "GSA_5" denomId = "1000" maxWagerCredits = "3" serviceLampOn = "true" logicDoorOpen = "false" logicDoorDateTime = "2003-03-01T13:23:27.432-07:00" auxDoorOpen = "false" auxDoorDateTime = "2003-03-01T13:23:27.432-09:00" cabinetDoorOpen = "false" cabinetDoorDateTime = "2003-03-01T13:23:27.432-12:00" /> </cabinet> Page 142 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 3.28.1.5 Chapter 3 cabinet Class setCabinetLockOut Request: Host to EGM The following example highlights the construction of a setCabinetLockOut command sent from a host to an EGM. A 15-second lockout time is set. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2004" sessionType = "G2S_request" sessionId = "1004" timeToLive = "30000" sessionRetry = "false" > <setCabinetLockOut lockout = "true" lockText = "Your cashless transaction is being processed. Please wait." lockTimeOut = "15000" /> </cabinet> 3.28.1.6 cabinetStatus Response: EGM to Host The following example highlights the construction of a cabinetStatus command sent from an EGM to a host in response to the receipt of a setCabinetLockOut command. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3004" sessionType = "G2S_response" sessionId = "1004" > <cabinetStatus egmEnabled = "true" hostEnabled = "true" hostLocked = "true" enableGamePlay = "true" enableMoneyIn = "true" enableMoneyOut = "true" egmState = "G2S_hostLocked" deviceClass = "G2S_cabinet" deviceId = "1" gamePlayId = "4" themeId = "GSA_3" paytableId = "GSA_5" denomId = "1000" maxWagerCredits = "3" serviceLampOn = "true" logicDoorOpen = "false" logicDoorDateTime = "2003-03-01T13:23:27.432-07:00" auxDoorOpen = "false" auxDoorDateTime = "2003-03-01T13:23:27.432-09:00" cabinetDoorOpen = "false" cabinetDoorDateTime = "2003-03-01T13:23:27.432-12:00" /> </cabinet> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 143 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.28.2 Cabinet Profile Command Sequence HOST EGM getCabinetProfile cabinetProfile 3.28.2.1 getCabinetProfile Request: Host to EGM The following example highlights the construction of a getCabinetProfile command sent from a host to an EGM. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2001" sessionType = "G2S_request" sessionId = "1001" timeToLive = "30000" sessionRetry = "false" > <getCabinetProfile /> </cabinet> 3.28.2.2 cabinetProfile Response: EGM to Host The following example highlights the construction of a cabinetProfile command sent from an EGM to a host in response to the receipt of getCabinetProfile command. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3001" sessionType = "G2S_response" sessionId = "1001" > <cabinetProfile machineNum = "4040" machineId = "BAL777" currencyId = "USD" reportDenomId = "10000" localeId = "EN_US" areaId = "HR23" zoneId = "03" bankId = "17" egmPosition = "12" machineLoc = "031712" cabinetStyle = "G2S_upright" /> </cabinet> Page 144 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.28.3 Date/Time Command Sequences HOST 3.28.3.1 EGM HOST EGM setDateTime getDateTime cabinetDateTime cabinetDateTime setDateTime Request: Host to EGM The following example highlights the construction of a setDateTime command sent from a host to an EGM. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2005" sessionType = "G2S_request" sessionId = "1005" sessionRetry = "false" timeToLive = "30000" > <setDateTime cabinetDateTime = "2006-02-25T09:04:04.321-05:00" /> </cabinet> 3.28.3.2 cabinetDateTime Response: EGM to Host The following example highlights the construction of a cabinetDateTime command sent from an EGM to a host in response to the receipt of a setDateTime command. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3005" sessionType = "G2S_response" sessionId = "1005" > <cabinetDateTime cabinetDateTime = "2006-02-25T09:04:04.329-05:00"/> </cabinet> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 145 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.28.4 Processor Reset Command Sequence HOST EGM resetProcessor resetStarted 3.28.4.1 resetProcessor Request: Host to EGM The following example highlights the construction of a resetProcessor command sent from a host to an EGM. A 45 second time to live is set to give the EGM time to shut down peripherals. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2006" sessionType = "G2S_request" sessionId = "1006" sessionRetry = "false" timeToLive = "45000" > <resetProcessor /> </cabinet> 3.28.4.2 resetStarted Response: EGM to Host The following example highlights the construction of a resetStarted command sent from an EGM to a host in response to the receipt of a resetProcessor command. <cabinet deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3006" sessionType = "G2S_response" sessionId = "1006" > <resetStarted /> </cabinet> Page 146 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.29 Cabinet Device Option Configuration The following sections identify the G2S-specified configuration option selections for cabinet devices and provides examples of optionItem elements in Section 3.29.8. Configuration option selections are set using commands from the optionConfig class. The current configuration option selections for a cabinet device are reported via the cabinetProfile command. Further descriptions of the sub-parameters can be found under the cabinetProfile command. 3.29.1 Option Group Definitions optionGroupId optionGroupName 3.29.2 G2S_cabinetOptions G2S Cabinet Options G2S Protocol Option Definitions optionId G2S_protocolOptions securityLevel G2S_administrator minSelections 1 maxSelections 1 duplicates Duplicate Key Parameter Type n/a n/a Complex paramId 3.29.3 G2S_protocolParams paramName G2S Protocol Parameters paramHelp Standard G2S protocol parameters for cabinet devices G2S Protocol Option Sub-Parameter Definitions Table 3.69 G2S Protocol Option Sub-Parameter Definitions paramId paramName Example paramHelp G2S_configurationId Configuration Identifier 123456 ID assigned by the last successful G2S option configuration G2S_restartStatus Enabled on Restart True hostEnabled attribute status upon EGM restart G2S_useDefaultConfig Use Default Configuration False Use default configuration on restart G2S_requiredForPlay Required For Play True Device is required for game play gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 147 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.29.4 G2S Cabinet Profile Option Definitions optionId G2S_cabinetOptions securityLevel G2S_attendant minSelections 1 maxSelections 1 duplicates Duplicate Key Parameter Type paramId 3.29.5 n/a n/a Complex G2S_cabinetParams paramName Cabinet Parameters paramHelp Casino specific parameters for the EGM G2S Cabinet Profile Sub-Parameter Definitions Table 3.70 G2S Cabinet Profile Sub-Parameter Definitions paramId paramName Example paramHelp G2S_machineNum Machine Number 1234 Property assigned machine number G2S_machineId Machine Id AB1234 Property assigned alphanumeric machine identifier G2S_currencyId Base Currency USD Base currency of the EGM G2S_reportDenomId Base Denomination 100000 G2S_localeId Locale EN_US Locale (language_country) of the EGM G2S_areaId Area Third Floor Property assigned area identifier G2S_zoneId Zone AA Property assigned zone identifier G2S_bankId Bank BB Property assigned bank identifier G2S_egmPosition Position 14 EGM location within the bank G2S_machineLoc Location AABB14 EGM physical location identifier G2S_cabinetStyle Cabinet Style G2S_slant EGM Cabinet Style G2S_idleTimePeriod Idle Time Period 240000 Timeout with 0 credits when EGM is considered idle G2S_timeZoneOffset Page 148 Time Zone Offset (for $1) (4 minutes) -05:00 Property assigned denomination used for reporting Time zone offset from UCT for this EGM gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.29.6 Cabinet Limit Option Definitions optionId G2S_cabinetLimits securityLevel G2S_operator minSelections 1 maxSelections 1 duplicates Duplicate Key Parameter Type paramId 3.29.7 n/a n/a Complex G2S_limitParams paramName Cabinet Limits paramHelp Settable Cabinet Limits for the EGM Cabinet Limit Sub-Parameter Definitions Table 3.71 Cabinet Limits Sub-Parameter Definitions paramId paramName Example paramHelp G2S_largeWinLimit Large Win Limit 119900000 ($1199) Maximum win payable by the EGM G2S_maxCreditMeter Credit Meter Maximum 300000000 ($3000) Maximum amount permitted on the credit meter G2S_maxHopperPayOut Max Hopper Payout 20000000 G2S_splitPayOut OK to Split Payouts True Split large payouts between hopper and other means G2S_acceptNonCashAmts Accept NonCashable Money G2S_acceptAlways Non-cashable transfers can be accepted by this EGM ($200) Maximum amount to pay from the hopper gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 149 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 3.29.8 Example optionItem Elements in optionList The following are examples of optionItem elements used by the EGM to describe its configurable options within the cabinet. These elements are sent by the EGM to the host in the optionList command. // G2S Protocol Options <optionItem optionId = "G2S_protocolOptions" securityLevel = "G2S_administrator" minSelections = "1" maxSelections = "1" > <optionParameters> <complexParameter paramId = "G2S_protocolParams" paramName = "G2S Protocol Parameters" paramHelp = "Standard G2S protocol parameters for cabinet devices" > <integerParameter paramId = "G2S_configurationId" paramName = "Configuration Identifier" paramHelp = "ID assigned by the last successful G2S option configuration" canModLocal = "false" canModRemote = "false" /> <booleanParameter paramId = "G2S_restartStatus" paramName = "Enabled on Restart" paramHelp = "hostEnabled attribute status upon EGM restart" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_useDefaultConfig" paramName = "Use Default Configuration" paramHelp = "Use default configuration on restart" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_requiredForPlay" paramName = "Required For Play" paramHelp = "Device is required for game play" canModLocal = "true" canModRemote = "true" /> </complexParameter> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 123456 </integerValue> <booleanValue paramId = "G2S_restartStatus" > true </booleanValue> <booleanValue paramId = "G2S_useDefaultConfig" > false </booleanValue> <booleanValue paramId = "G2S_requiredForPlay" > true </booleanValue> </complexValue> </optionCurrentValues> <optionDefaultValues> <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 0 </integerValue> <booleanValue paramId = "G2S_restartStatus" > true </booleanValue> <booleanValue paramId = "G2S_useDefaultConfig" > false </booleanValue> <booleanValue paramId = "G2S_requiredForPlay" > true </booleanValue> </complexValue> </optionDefaultValues> </optionItem> // G2S Cabinet Profile Options <optionItem optionId = "G2S_cabinetOptions" securityLevel = "G2S_attendant" minSelections = "1" maxSelections = "1" > <optionParameters> <complexParameter paramId = "G2S_cabinetParams" paramName = "Cabinet Parameters" paramHelp = "Casino specific parameters for the EGM" > <integerParameter paramId = "G2S_machineNum" paramName = "Machine Number" Page 150 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 3 cabinet Class paramHelp = "Property assigned machine number" canModLocal = "true" canModRemote = "true" minIncl = "0" /> <stringParameter paramId = "G2S_machineId" paramName = "Machine Id" paramHelp = "Property assigned alphanumeric machine identifier" canModLocal = "true" canModRemote = "true" maxLen = "8" /> <stringParameter paramId = "G2S_currencyId" paramName = "Base Currency" paramHelp = "Base currency of the EGM" canModLocal = "true" canModRemote = "true" maxLen = "3" > <stringEnum> USD </stringEnum> </stringParameter> <integerParameter paramId = "G2S_reportDenomId" paramName = "Base Denomination" paramHelp = "Property assigned denomination used for reporting" canModLocal = "true" canModRemote = "true" minIncl = "0" /> <stringParameter paramId = "G2S_localeId" paramName = "Locale" paramHelp = "Locale (language_country) of the EGM" canModLocal = "true" canModRemote = "true" maxLen = "8" > <stringEnum> EN_US </stringEnum> </stringParameter> <stringParameter paramId = "G2S_areaId" paramName = "Area" paramHelp = "Property assigned area identifier" canModLocal = "true" canModRemote = "true" maxLen = "8" /> <stringParameter paramId = "G2S_zoneId" paramName = "Zone" paramHelp = "Property assigned zone identifier"" canModLocal = "true" canModRemote = "true" maxLen = "8" /> <stringParameter paramId = "G2S_bankId" paramName = "Bank" paramHelp = "Property assigned bank identifier"" canModLocal = "true" canModRemote = "true" maxLen = "8" /> <stringParameter paramId = "G2S_egmPosition" paramName = "Position" paramHelp = "EGM location within the bank" canModLocal = "true" canModRemote = "true" maxLen = "8" /> <stringParameter paramId = "G2S_machineLoc" paramName = "Location" paramHelp = "EGM physical location identifier" canModLocal = "true" canModRemote = "true" maxLen = "16" /> <stringParameter paramId = "G2S_cabinetStyle" paramName = "Cabinet Style" paramHelp = "EGM cabinet style" canModLocal = "true" gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 151 Chapter 3 cabinet Class G2S™ Message Protocol v1.0.3 canModRemote = "true" > <stringEnum> G2S_slant </stringEnum> <stringEnum> G2S_roundTop </stringEnum> <stringEnum> G2S_barTop </stringEnum> <stringEnum> G2S_upright </stringEnum> <stringEnum> G2S_other </stringEnum> <stringEnum> G2S_unknown </stringEnum> </stringParameter> <integerParameter paramId = "G2S_idleTimePeriod" paramName = "Idle Time Period" paramHelp = "Timeout with 0 credits when EGM is considered idle" canModLocal = "true" canModRemote = "true" minIncl = "0" /> <stringParameter paramId = "G2S_timeZoneOffset" paramName = "Time Zone Offset" paramHelp = "Time zone offset from UCT for this EGM" canModLocal = "true" canModRemote = "true" minLen = "6" maxLen = "6" /> </complexParameter> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_cabinetParams" > <integerValue paramId = "G2S_machineNum" > 1234 </integerValue> <stringValue paramId = "G2S_machineId" > AB1234 </stringValue> <stringValue paramId = "G2S_currencyId" > USD </stringValue> <integerValue paramId = "G2S_reportDenomId" > 100000 </integerValue> <stringValue paramId = "G2S_localeId" > EN_US </stringValue> <stringValue paramId = "G2S_areaId" > East </stringValue> <stringValue paramId = "G2S_zoneId" > AA </stringValue> <stringValue paramId = "G2S_bankId" > BB </stringValue> <stringValue paramId = "G2S_egmPosition" > 14 </stringValue> <stringValue paramId = "G2S_machineLoc" > AABB14 </stringValue> <stringValue paramId = "G2S_cabinetStyle" > G2S_upRight </stringValue> <integerValue paramId = "G2S_idleTimePeriod" > 240000 </integerValue> <stringValue paramId = "G2S_timeZoneOffset" > -05:00 </stringValue> </complexValue> </optionCurrentValues> <optionDefaultValues> <complexValue paramId = "G2S_cabinetParams" > <integerValue paramId = "G2S_machineNum" > </integerValue> <stringValue paramId = "G2S_machineId" > </stringValue> <stringValue paramId = "G2S_currencyId" > USD </stringValue> <integerValue paramId = "G2S_reportDenomId" > 100000 </integerValue> <stringValue paramId = "G2S_localeId" > EN_US </stringValue> <stringValue paramId = "G2S_areaId" > </stringValue> <stringValue paramId = "G2S_zoneId" > </stringValue> <stringValue paramId = "G2S_bankId" > </stringValue> <stringValue paramId = "G2S_egmPosition" > </stringValue> <stringValue paramId = "G2S_machineLoc" > </stringValue> <stringValue paramId = "G2S_cabinetStyle" > G2S_unknown </stringValue> <integerValue paramId = "G2S_idleTimePeriod" > 240000 </integerValue> <stringValue paramId = "G2S_timeZoneOffset" > +00:00 </stringValue> </complexValue> </optionDefaultValues> </optionItem> // G2S Cabinet Limit Options <optionItem optionId = "G2S_cabinetLimits" securityLevel = "G2S_operator" minSelections = "1" maxSelections = "1" > <optionParameters> <complexParameter paramId = "G2S_limitParams" paramName = "Cabinet Limits" paramHelp = "Settable Cabinet Limits for the EGM" > <integerParameter paramId = "G2S_largeWinLimit" paramName = "Large Win Limit" paramHelp = "Maximum win payable by the EGM" Page 152 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 3 cabinet Class canModLocal = "true" canModRemote = "true" minIncl = "0" /> <integerParameter paramId = "G2S_maxCreditMeter" paramName = "Credit Meter Maximum" paramHelp = "Maximum amount permitted on the credit meter" canModLocal = "true" canModRemote = "true" minIncl = "1" maxIncl = "999999" /> <integerParameter paramId = "G2S_maxHopperPayOut" paramName = "Max Hopper Payout" paramHelp = "Maximum amount to pay from the hopper" canModLocal = "true" canModRemote = "true" minIncl = "0" maxIncl = "999999" /> <booleanParameter paramId = "G2S_splitPayOut" paramName = "OK to Split Payouts" paramHelp = "Split large payouts between hopper and other means" canModLocal = "true" canModRemote = "true" /> <stringParameter paramId = "G2S_acceptNonCashAmts" paramName = "Accept Non-Cashable Money" paramHelp = "Non-cashable transfers can be accepted by this EGM" canModLocal = "true" canModRemote = "true" /> </complexParameter> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_limitParams" > <integerValue paramId = "G2S_largeWinLimit" > 119999 </integerValue> <integerValue paramId = "G2S_maxCreditMeter" > 999999 </integerValue> <integerValue paramId = "G2S_maxHopperPayOut" > 2000 </integerValue> <booleanValue paramId = "G2S_splitPayOut" > true </booleanValue> <stringValue paramId = "G2S_acceptNonCashAmts" > G2S_acceptAlways </stringValue> </complexValue> </optionCurrentValues> <optionDefaultValues> <complexValue paramId = "G2S_limitParams" > <integerValue paramId = "G2S_largeWinLimit" > 119999 </integerValue> <integerValue paramId = "G2S_maxCreditMeter" > 999999 </integerValue> <integerValue paramId = "G2S_maxHopperPayOut" > 999999 </integerValue> <booleanValue paramId = "G2S_splitPayOut" > false </booleanValue> <stringValue paramId = "G2S_acceptNonCashAmts" > G2S_acceptAlways </stringValue> </complexValue> </optionDefaultValues> </optionItem> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 153 G2S™ Message Protocol v1.0.3 Page 154 Chapter 3 cabinet Class gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 4 eventHandler Class 4.1 Introduction Chapter 4 eventHandler Class The eventHandler class manages the event subscriptions for an EGM, providing the means to determine the events supported by the EGM, to install and remove and inquire about event subscriptions, and to manage the collection and delivery of events and associated affected data. The eventHandler class is a multiple device class. Each permitted host to which the EGM connects owns an event handler device assigned a device identifier that is the same as the host identifier assigned to the host. An event represents an occurrence of an incident detected by a device in an EGM. The device can generate an event in an unsolicited manner or in response to a host command. Some events may also have an associated command that is sent to the owner of the device. 4.1.1 Determining Events Supported by EGM Through the getSupportedEvents command a host can ask the event handler device for a list of events supported by any device on the EGM. The host can do this one-by-one or by using wildcards to determine the supported events for a group of devices. The event handler device returns this information in the supportedEvents command. 4.1.2 Affected Data Every event within the EGM has a set of affected data that can optionally be sent to the host subscriber along with the event (see Section 4.1.3). The affected data is broken into the following four distinct categories; • The device status of devices that have changed as a result of the event. • The transaction that initiated the event. • A set of class meters for classes of the devices that were affected as a result of the event. • A set of device meters for devices that were affected by the event. The meter sets (for both classes and devices) can be either: • The complete set for the class or device. • The set of meters that may have changed as a result of the event for the class or device. The affected data that can be requested for a particular event is limited to the device data of the devices that are affected by the action that generated the event. The superset of the possible data for each event is well known, and an event will contain the affected data items from within this super set. The definition of the affected data accompanies the definition of the events within each of the class chapters in this document. 4.1.3 Subscriptions The ability to configure the way an EGM handles events allows hosts to define which events to receive and what affected data should accompany the event. The host uses the setEventSub command to add event subscriptions. Each event subscription consists of two parts: the event and the list of affected data that the host wants to accompany the event. A host adds subscriptions to the event handler device indicating which, if any, of the four sets of data (described in 4.1.2) should accompany the event. The event subscriptions are persisted. If there are overlapping subscriptions for the same event, the values for persistence and which associated data to send will be ORed together to provide the superset of data. For example if there is a forced subscription (see gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 155 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 Section 4.1.5) for event X asking for meters, and a host subscription for event X not asking for meters, then the meters will be sent. Event subscriptions are maintained on an event by event basis, meaning that if a subscription is added using a wildcard it will be expanded internally. There are a few implications of this: • The detailed list of event subscriptions are returned in response to a getEventSub command (wildcards are not persisted). • Subscriptions will only be applicable to the devices that are active at the time the subscription was added. There is no implied subscription on a device when it is added to the EGM (wildcards will not carry over to new devices). 4.1.4 Persistence: Event and Affected Data There is an option, eventPersist, that can be specified with each event subscription indicating whether or not to persist an event. The affected data is not persisted with the event; however, the transaction identifier, transactionId, and the affected device list are persisted with the event. Each event can have at most 1 (one) transaction associated with it. The affected data is gathered when the event is retried, and is not persisted with the event itself. Data that is not in sync with the event can be detected by checking the retry indicator in the event command. If the event is not persisted it is sent out once as a notification and no acknowledgement will be received, otherwise it is sent as a request/response pair and the event will be persisted until it is acknowledged by the host service. 4.1.5 Forced Subscriptions There is also the concept of forced event subscriptions. A forced event subscription is sent down to the device by the configuration server, or entered manually at the EGM. A forced subscription cannot be deleted or changed by the host. Other than this restriction, the forced event subscription has the same behavior as a nonforced event subscription. The owning host cannot clear forced event subscriptions. Unlike regular subscriptions, forced subscriptions are not additive. They are sent as complete subscription sets on a per device basis. When a new set of forced subscriptions is sent down by the configuration server all other forced subscriptions for that device are cleared. 4.1.6 Full Event Queue Behavior The behavior of the event handler device when facing an event queue full is dependent on the configuration that is sent by the configuration server (or manually entered). The event handler device may overwrite the oldest events, stop queueing events or become disabled. This option is configurable on a host-by-host basis. 4.1.7 Event Processing When an event occurs, the event handler device (see also Figure 4.1): 1. Assigns an event identifier, eventId, to the event. The eventId is a monotonically increasing number starting at 1 (one) that is maintained for the entire EGM. The eventId can be used to sequence events coming from a particular EGM. 2. Checks whether the event needs to be persisted; if so, it will place the event into non-volatile memory. 3. Gathers all the affected data requested. 4. Sends the event command. If the command is not deliverable, the affected data is not persisted. The affected data is retrieved each time the event is retried. By coupling the affected data with the event, the host has context by which to act upon this data and knows that it is receiving certain data sets as a direct result of an event occurrence. Page 156 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 Event Occurs Get new event ID for the event Persist event? no yes Gather associated data Add event details to NVRAM Send to communications class for delivery Gather associated data Send to communications class for delivery yes Timeout waiting for ACK? no DONE Figure 4.1 Normal Event Processing Flow gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 157 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.1.8 Power Failure and Persisted Subscriptions All subscriptions need to be persisted in non-volatile memory, and after a power failure the EGM will use the existing subscriptions until they are deleted or overwritten. P ow er O n C om m s E stablished Foreach event in persistent m em ory G ather associated data S end to com m unications class for delivery E nd Foreach Figure 4.2 Power on Recovery Page 158 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.2 Request/Response Pairs The following tables organize the commands contained within the eventHandler class into request-response pairs: Table 4.1 Commands Originated by EGM Request Response eventReport eventAck Table 4.2 Commands Originated by Host Request Response Owner Guest getEventHandlerProfile eventHandlerProfile Yes Yes setEventSub setEventSubAck Yes No getEventSub eventSubList Yes Yes clearEventSub clearEventSubAck Yes No getEventHandlerStatus eventHandlerStatus Yes Yes setEventHandlerState eventHandlerStatus Yes No getEventHandlerLogStatus eventHandlerLogStatus Yes Yes getEventHandlerLog eventHandlerLogList Yes Yes getSupportedEvents supportedEvents Yes Yes gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 159 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.3 setEventHandlerState Command This command is sent by the host to enable or disable its event handler device. The eventHandlerStatus command is sent in response to this command. Table 4.3 setEventHandlerState Attributes Attribute Restrictions Description enable type: boolean use: optional default: true The new status of the event handler device. disableText type: textMessage use: optional default: <empty> Optional message to display while the device is disabled. 4.4 getEventHandlerStatus Command This command is sent by the host to query the status of the event handler device. The eventHandlerStatus command is sent in response to this command. This command has no attributes or elements. Page 160 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.5 eventHandlerStatus Command The EGM sends this command in response to the getEventHandlerStatus and setEventHandlerState commands, indicating whether the event handler device is enabled. Table 4.4 eventHandlerStatus Attributes Attribute Restrictions Description configurationId type: configurationId use: optional default: 0 Configuration identifier set by the host. hostEnabled type: boolean use: optional default: true Indicates whether the host has enabled the event handler device. egmEnabled type: boolean use: optional default: true Indicates whether the EGM has enabled the event handler device. eventHandlerOverflow type: boolean use: optional default: false Indicates whether the event handler device queues are full. 4.6 getEventHandlerProfile Command This command is used by a host to request the current profile of an event handler device from the EGM. An eventHandlerProfile command is sent in response to the getEventHandlerProfile command. The getEventHandlerProfile element has no additional attributes or elements. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 161 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.7 eventHandlerProfile Command This command is used by an EGM to report the current profile of an event handler device. This profile contains the protocol-related configuration option selections for the event handler device. These options can be set locally at the EGM or remotely via a configuration server using commands within the optionConfig class. The eventHandlerProfile command is sent in response to the getEventHandlerProfile command. Table 4.5 eventHandlerProfile Attributes Attribute Restrictions Description configurationId * type: configurationId use: optional default: 0 Last configuration identifier set by a G2S host; set to 0 (zero) when configuration changes are made by hosts other than G2S hosts. restartStatus * type: boolean use: optional default: true Indicates the state of hostEnabled when the EGM restarts. useDefaultConfig * type: boolean use: optional default: false requiredForPlay * type: boolean use: optional default: false minLogEntries type: int use: optional minIncl: 1 default: 35 Indicates whether the default configuration for the device MUST be used when the EGM restarts. Indicates whether the EGM MUST be disabled if either egmEnabled or hostEnabled is set to false. Minimum number of log entries. timeToLive * type: timeToLive use: optional default: 30000 Time-to-live value for requests originated by the device. queueBehavior * type: queueBehaviors use: required Indicates the type of behavior required when an event queue overflow condition occurs. Table 4.6 eventHandlerProfile Elements Element Restrictions Description forcedSubscription minOcc: 0 maxOcc: ∞ Identifies a forced subscription for this event handler. See attributes in Table 4.7. Page 162 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 Table 4.7 forcedSubscription Attributes Attribute Restrictions Description deviceClass * type deviceClass use: required The class that can generate the event. A device class of G2S_all indicates that all the events from all device classes are part of this filter. deviceId * type: deviceId use: Required Identifier of the device that may generate the event. The -1 wildcard indicates that all the device instances within the class will be used in the scope of this filter. eventCode * type: eventCode use: required The event code that this subscription pertains to. An event code of G2S_all is considered a wildcard, meaning all events within the device will be sent. forceDeviceStatus * type: boolean use: optional default: false Indicates whether to send the affected device status messages with the event. forceTransaction * type: boolean use: optional default: false Indicates whether to send the affected transaction record with the event. forceClassMeters * type: boolean use: optional default: false Indicates whether to send the affected class level meters with the event. forceDeviceMeters * type: boolean use: optional default: false Indicates whether to send the affected device level meters with the event. forceUpdatableMeters * type: boolean * use: optional default: false Indicates which of the possible meter sets to send with the event. • false = The complete meter set for affected devices. • true = The set of meters that may have changed in the affected devices as a result of the event. forcePersist * type: boolean use: optional default: false Indicates whether this event needs to be persisted until acknowledged, or only sent out once. * Standard configuration option that MUST be included in the standard option configuration group – G2S_eventHandlerOptions – for devices within the eventHandler class. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 163 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.8 getSupportedEvents Command The host uses the getSupportedEvents command to query the EGM for a list of supported events. The events returned include all the defined events as well as any manufacturer specified events that may exist. The supportedEvents command is sent in response to this command. Table 4.8 getSupportedEvents Attributes Attribute Restrictions Description deviceClass type deviceClass use: required Class the host wishes to query. A device class of G2S_all indicates that all device classes will be used to formulate the response. deviceId type: deviceId use: required Identifier of the device host wishes to query. The -1 wildcard indicates that all the device instances within the class will be used in the scope of this filter. 4.9 supportedEvents Command The EGM sends the supportedEvents command to provide a list of the devices that were queried and for each device, the event codes the device supports. This command is sent in response to the getSupportedEvents command. Table 4.9 supportedEvents Element Element Restrictions Description supportedEvent minOcc: 0 Contains the events supported for a device. See also Table 4.10. maxOcc: ∞ Table 4.10 supportedEvent Attributes Attribute Restrictions Description deviceClass type deviceClass use: required Class to which the events belong. deviceId type: deviceId use: required Device identifier to which the events belong. eventCode type eventCode use: required The specific event code. eventText type: egmMessage use: optional default: <empty> A textual description of the event. Page 164 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.10 setEventSub Command The host sends the setEventSub command to add a host event subscription to the event handler device. Forced event subscriptions can be configured manually or through the optionConfig class. If the event subscription defines an event that already has a subscription associated with it, the old subscription is ORed with the new; otherwise, the new subscriptions are added to the list of existing subscriptions. The setEventSub command can return the error codes G2S_EHX001 Invalid Subscription or G2S_EHX003 Cannot Add Subscription. The response to the setEventSub command is the setEventSubAck command. Table 4.11 setEventSub Element Element Restrictions Description eventHostSubscription minOcc: 1 Defines the parameters of a host event subscription. See attributes in Table 4.12. maxOcc: ∞ Table 4.12 eventHostSubscription Attributes (Sheet 1 of 2) Attribute Restrictions Description deviceClass type deviceClass use: required The class that can generate the event. A device class of G2S_all indicates that all the events from all device classes are part of this filter. deviceId type: deviceId use: required Identifier of the device that may generate the event. The -1 wildcard indicates that all the device instances within the class will be used in the scope of this filter. eventCode type: eventCode use: required The event code that this subscription pertains to. An event code of G2S_all is considered a wildcard, meaning all events within the device will be sent. sendDeviceStatus type: boolean use: optional default: false Indicates whether to send the affected device status messages with the event. sendTransaction type: boolean use: optional default: false Indicates whether to send the affected transaction record with the event. sendClassMeters type: boolean use: optional default: false Indicates whether to send the affected class level meters with the event. sendDeviceMeters type: boolean use: optional default: false Indicates whether to send the affected device level meters with the event. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 165 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 Table 4.12 eventHostSubscription Attributes (Sheet 2 of 2) Attribute Restrictions Description sendUpdatableMeters type: boolean use: optional default: false Indicates which of the possible meter sets to send with the event. false = The complete meter set for affected devices. true = The set of meters that may have changed in the affected devices as a result of the event. eventPersist type: boolean use: optional default: false Indicates whether this event needs to be persisted until acknowledged, or only sent out once. 4.11 setEventSubAck Command This is the acknowledgement to the setEventSub command. This command has no elements or attributes. 4.12 getEventSub Command The getEventSub command is issued by a host to get the complete list of event subscriptions for a particular event handler device. The eventSelect element allows you to query for a specific subscription or to use wildcards for sets of subscriptions. The getEventSub command will return an empty list if no event subscriptions meet the selection criteria. This command can be issued by both the owner and guests. The response to the getEventSub command is the eventSubList command. Table 4.13 getEventSub Attributes Attribute Restrictions Description getForcedSubs type: boolean use: optional default: true Specifies whether to return the event subscriptions that are defined as forced. This also forces the sending of the forced attributes in the eventSubList command if they are set to true. getHostSubs type: boolean use: optional default: true Specifies whether to return the event subscriptions that are host defined. This also forces the sending of the non-forced attributes in the eventSubList command if they are set to true. Page 166 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 Table 4.14 getEventSub Element Element Restrictions Description eventSelect minOcc: 1 Contains the event subscription information for a particular event handler device. See attributes in Table 4.15. maxOcc: ∞ Table 4.15 eventSelect Attributes Attribute Restrictions Description deviceClass type deviceClass use: required Class that can generate the event. A device class of G2S_all indicates that all the events from all the device classes are part of this filter. deviceId type: deviceId use: required Identifier of the device that may generate the event. The -1 wildcard indicates that all the device instances within the class will be used in the scope of this filter. eventCode type: eventCode use: required Event code that this subscription pertains to. An event code of G2S_all is considered a wild card, meaning all events within the device will be sent. 4.13 eventSubList Command The eventSubList command is sent in response to the event subscription management commands getEventSub. This command returns the complete list of subscriptions that are currently persisted in the event handler device. Table 4.16 eventSubList Element Element Restrictions Description eventSubscription minOcc: 0 Contains the details for an event subscription. See also Table 4.17. maxOcc: ∞ Table 4.17 eventSubscription Attributes (Sheet 1 of 2) Attribute Restrictions Description deviceClass type deviceClass use: required Class that can generate the event. deviceId type: deviceId use: required Identifier of the device that may generate the event. eventCode type: eventCode use: required Event code that this subscription pertains to. eventText type: egmMessage use: optional default: <empty> Descriptive text for the eventCode. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 167 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 Table 4.17 eventSubscription Attributes (Sheet 2 of 2) Attribute Restrictions Description sendDeviceStatus type: boolean use: optional default: false Indicates whether the affected device status messages are sent with the event. sendTransaction type: boolean use: optional default: false Indicates whether the affected transaction record is sent with the event. sendClassMeters type: boolean use: optional default: false Indicates whether the affected class level meters are sent with the event. sendDeviceMeters type: boolean use: optional default: false Indicates whether the affected device level meters are sent with the event. eventPersist type: boolean use: optional default: false Indicates whether these events are persisted until acknowledged sent out only once. sendUpdatableMeters type: boolean use: optional default: false Indicates which of the possible meter sets are sent with the event. The valid options are: false = The complete meter set for affected devices. true = The set of meters that may have changed in the affected devices as a result of the event. forceDeviceStatus type: boolean use: optional default: false Indicates whether, for forced subscriptions, the affected device status messages are sent with the event. forceTransaction type: boolean use: optional default: false Indicates whether, for forced subscriptions, the affected transaction record is sent with the event. forceClassMeters type: boolean use: optional default: false Indicates whether, for forced subscriptions, the affected class level meters are sent with the event. forceDeviceMeters type: boolean use: optional default: false Indicates whether, for forced subscriptions, the affected device level meters are sent with the event. forceUpdatableMeters type: boolean use: optional default: false For forced subscriptions, indicates which of the possible meter sets the event handler device will send with the event. The valid options are: false = The complete meter set for affected devices. true = The set of meters that may have changed in the affected devices as a result of the event. forcePersist type: boolean use: optional default: false Indicates whether, for forced subscriptions, these events are persisted until acknowledged, or whether they are just sent out once. Page 168 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.14 clearEventSub Command The host sends the clearEventSub command to indicate that it should no longer receive a specified subscription and instruct the event handler device to remove that subscription. As discussed earlier, the clearEventSub cannot clear forced event subscriptions (those configured manually or by the configuration server). The response to the clearEventSub command is the clearEventSubAck command. To clear all event subscriptions for a host, the host sends a clearEventSub with wildcards for all the attributes (deviceClass = "G2S_all", deviceId = "-1", and eventCode = "G2S_all"). Table 4.18 clearEventSub Element Element Restrictions Description eventSelect minOcc: 1 Contains the details for an event subscription to be cleared. See also Table 4.19. maxOcc: ∞ Table 4.19 eventSelect Attributes Attribute Restrictions Description deviceClass type deviceClass use: required Class that can generate the event. A device class of G2S_all indicates that all the events from all the device classes are part of this filter. deviceId type: deviceId use: Required Identifier of the device that may generate the event. The -1 wildcard indicates that all the device instances within the class will be used in the scope of this filter. eventCode type: eventCode use: required Event code to which this subscription pertains. An event code of G2S_all is considered a wild card, meaning all events within the device will no longer be sent. 4.15 clearEventSubAck Command This command is the acknowledgement to the clearEventSub command. This command contains no attributes or elements. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 169 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.16 eventReport Command This command is initiated by the EGM and is the direct result of a subscription that was previously installed. When an event occurs on the EGM, the event handler device checks its subscriptions. If this event is to be sent to the host, the event handler device includes any requested affected data and sends the command to the host. The transaction identifier that initiated this event is included as part of the transaction within the transactionInfo element. The EGM MUST persist the transaction identifiers for all persisted events if applicable. Table 4.20 eventReport Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Class that generated the event. deviceId type: deviceId use: required Identifier of the device that generated the event. eventCode type: eventCode use: required Event code of the event that caused this event to be sent. eventText type: egmMessage use: optional default: <empty> Text description of the event. eventId type: eventId use: required Unique identifier for a particular event. eventDateTime type: dateTime use: required Date and time that this event occurred. transactionId type: transactionId use: required Transaction identifier associated with the event; 0 (zero) if no associated transaction. Page 170 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 Table 4.21 eventReport Elements Element Restrictions Description deviceList minOcc: 0 maxOcc: 1 Contains statusInfo elements for each affected device containing the device status at the time the event command was placed in the outbound queue. This element has no attributes. See Section 4.16.1. transactionList minOcc: 0 maxOcc: 1 For each affected device, includes a transactionInfo element containing information about device transaction states at the time the event command was placed in the outbound queue. This element has no attributes. See Section 4.16.2. meterList minOcc: 0 maxOcc: 1 For each affected meter, includes a meterInfo element containing information about the meter status at the time the eventReport command was placed in the outbound queue. This element has no attributes. See Section 4.16.3. 4.16.1 deviceList Element Details Contains the statuses of the devices affected by this event. Table 4.22 deviceList Element Element Restrictions Description statusInfo minOcc: 1 For each affected device, includes a device status element containing the status of the affected device at the time the eventReport command was placed in the outbound queue. See Table 4.23 for attributes and Table 4.24 for elements. maxOcc: ∞ Table 4.23 statusInfo Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Class of the device to which this status information pertains. deviceId type: deviceId use: required Identifier of the device that this status, transaction log or set of meters pertains to. Table 4.24 statusInfo Element Element Restrictions Description [device status] minOcc: 1 maxOcc: 1 Contains the *Status element of the affected device, such as cabinet or gamePlay. These elements are detailed in the appropriate class chapter. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 171 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.16.2 transactionList Element Details Contains the transactions, by device, that were affected by this event. Table 4.25 transactionList Element Element Restrictions Description transactionInfo minOcc: 1 For each affected device, includes a device log element containing the log entries of the affected device at the time the eventReport command was placed in the outbound queue. See Table 4.26 for attributes and Table 4.27 for elements maxOcc: ∞ Table 4.26 transactionInfo Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Class of the device to which this transaction log pertains. deviceId type: deviceId use: required Identifier of the device to which this transaction log pertains. Table 4.27 transactionInfo Element Element Restrictions Description [deviceLog] minOcc: 1 maxOcc: 1 Contains the *Log element of the affected device, such as cabinet or gamePlay. These elements are detailed in the appropriate class chapter. 4.16.3 meterList Element Details Contains the meters, by device, that were changed as a result of this event. Table 4.28 meterList Element Element Restrictions Description meterInfo minOcc: 1 For each affected device, includes the meter data at the time the eventReport command was placed in the outbound queue. This element contains no attributes. The deviceId and deviceClass are contained within the device meters sub-element. See Section 5.19. maxOcc: Page 172 ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.17 eventAck Command The host responds to an eventReport command with the eventAck command. This command has a single attribute to indicate which event is being acknowledged. The event handler device cannot remove a persisted event from its communication queues until this acknowledgement is received. Table 4.29 eventAck Attribute Attribute Restrictions Description eventId type: eventId use: required The identifier of the event being acknowledged. 4.18 getEventHandlerLogStatus Command This command is used by the host to request the current status of the class-level transaction log from an EGM. The response includes the sequence number of the last transaction and the total number of transactions in the log. An eventHandlerLogStatus is sent in response to a getEventHandlerLogStatus command. The getEventHandlerLogStatus element contains no additional attributes or elements. 4.19 eventHandlerLogStatus Command This command is used by the EGM to send the current status of the transaction log to a host. The eventHandlerLogStatus command is sent in response to the getEventHandlerLogStatus command. Table 4.30 eventHandlerLogStatus Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional default: 0 minIncl: 0 The sequence number of the last transaction within the log. totalEntries type: int use: optional default: 0 minIncl: 0 The total number of transactions within the log. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 173 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.20 getEventHandlerLog Command This command is used by the host to request the contents of a transaction log from an EGM. Additional information regarding the use of the lastSequence and totalEntries attributes can be found in Chapter 1. The eventHandlerLogList command is sent in response to the getEventHandlerLog command. Table 4.31 getEventHandlerLog Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional default: 0 minIncl: 0 The sequence number of the transaction that should be the first entry in the list; if set to 0 (zero) then default to the last transaction. totalEntries type: int use: optional default: 0 minIncl: 0 The total number of transactions that should be included in the list; if set to 0 (zero) then default to all transactions. Page 174 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.21 eventHandlerLogList Command This command is used by the EGM to send the contents of the transaction log to a host. The eventHandlerLogList command is sent in response to a getEventHandlerLog command. Table 4.32 eventHandlerLogList Element Element Restrictions Description eventHandlerLog minIncl:0 Contains information about a specific transaction. See Table 4.33 and Table 4.34 for attribute and element descriptions. maxIncl: ∞ Table 4.33 eventHandlerLog Attributes (Sheet 1 of 2) Attribute Restrictions Description logSequence type:logSequence use: required Unique log sequence number assigned by the EGM. deviceClass type: deviceClass use: required Device class identifier of the device that generated the transaction. deviceId type: deviceId use: required Device identifier of the device that generated the transaction. eventCode type: eventCode use: required Event code of the event that caused this event to be sent. eventText type: egmMessage use: optional default: <empty> Text description of the event. eventId type: eventId use: required Unique identifier for a particular event. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 175 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 Table 4.33 eventHandlerLog Attributes (Sheet 2 of 2) Attribute Restrictions Description eventDateTime type: dateTime use: required Date and time that this event occurred. transactionId type: transactionId use: required Unique transaction identifier assigned by the EGM; if no associated transaction, set to 0 (zero). eventAck type: boolean use: optional default: false Indicates whether the event has been acknowledged. Table 4.34 eventHandlerLog Elements Element Restrictions Description affectedDeviceList minIncl: 0 maxIncl: 1 List of all the devices whose status changed as a result of the generation of this event. See Section 4.21.1. affectedTransactionList minIncl: 0 maxIncl: 1 List of the transactions that were affected as a result of the generation of this event. See Section 4.21.2. affectedMeterList minIncl: 0 maxIncl: 1 List of all the devices whose meters changed as a result of this event. See Section 4.21.3. 4.21.1 affectedDeviceList Element Details This element contains a list of all devices whose status changed as a result of this event. Table 4.35 affectedDeviceList Element Attribute Restrictions Description deviceSelect minIncl: 1 Identifies a device whose status changed as a result of the generation of this event. See Table 4.36. maxIncl: ∞ Table 4.36 deviceSelect Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Class of the device that was affected by the action that caused the event to be fired. deviceId type: deviceId use: required Identifier of the device that was affected by the action that caused the event to be fired. Page 176 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.21.2 affectedTransactionList Element Details This element contains a list of the transactions that were affected by this event. Table 4.37 affectedTransactionList Element Attribute Restrictions Description transactionSelect minIncl: 1 Identifies a transaction affected as a result of the generation of this event. See Table 4.36. maxIncl: ∞ Table 4.38 transactionSelect Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Class of the device that initiated the transaction that caused the event. deviceId type: deviceId use: required Identifier of the device that initiated the transaction that caused the event. transactionId type: transactionId use: required Identifier of the transaction that caused the event. 4.21.3 affectedMeterList Element Details This element contains a list of all the devices whose meters changed as a result of this event. Table 4.39 affectedDeviceList Element Attribute Restrictions Description deviceSelect minIncl: 1 Identifies a device whose meters changed as a result of the generation of this event. maxIncl: ∞ Table 4.40 deviceSelect Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Class of the device with meters that were affected by the action that caused the event to be fired. deviceId type: deviceId use: required Identifier of the device with meters that were affected by the action that caused the event to be fired. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 177 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.22 Data Types The following table lists the data types specific to the eventHandler class. Table 4.41 eventHandler Class Data Types Data Type Restrictions Description eventCode type: uniqueIdentifier10 The event code, which consists of: 3-character GSA-assigned manufacturer identifier an underscore 2-character class identifier The character "E" indicating "Event" 3-digit event number. Example: G2S_EHE001. eventId type: long minincl: 1 The unique identifier for an event. queueBehaviors type: string enumerations: G2S_disable G2S_discard G2S_overwrite Type of behavior required when an event queue overflow condition occurs. 4.23 Error Codes The following table lists the error codes for the eventHandler class: Table 4.42 eventHandler Class Error Codes Error Code Suggested Error Text G2S_EHX001 Invalid Subscription G2S_EHX002 Event Subscription Not Found G2S_EHX003 Cannot Add Subscription G2S_EHX004 Cannot Delete Forced Subscription Page 178 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.24 Event Codes The following table summarizes the events that may be generated by devices within the eventHandler class. Full event descriptions follow the table. Table 4.43 eventHandler Class Event Codes (EH = eventHandler) Affected Device Logs, Meters, Statuses Event Code and Event Title EH G2S_EHE001 Event Handler Disabled by EGM S G2S_EHE002 Event Handler Enabled by EGM S G2S_EHE003 Event Handler Disabled by Host S G2S_EHE004 Event Handler Enabled by Host S G2S_EHE005 Event Handler Configuration Changed by Host S G2S_EHE006 Event Handler Configuration Changed by Operator S G2S_EHE101 Event Subscription Changed S G2S_EHE102 Event Handler Queue Overflow S G2S_EHE103 Event Handler Queue Overflow Cleared S The following table lists the elements contained within the eventHandler class which may be included as affected data with events: Table 4.44 Elements Included With Events Affected Data Element Device Status eventHandlerStatus 4.24.1 evaluate(state) The egmEnabled and egmState attributes are both determined from multiple factors. If all of the faults for a device have been cleared then the egmEnabled attribute for the device can be set to true. If any one fault still exists then the egmEnabled attribute MUST be set to false. Thus, after a fault is cleared, the EGM MUST evaluate all of the attributes that contribute to the state of the egmEnabled attribute. If anyone of them shows a fault then the egmEnabled attribute MUST remain set to false. This is communicated in the following documentation by using the convention "evaluate(device.egmEnabled)". Likewise, the egmState attribute of the cabinetStatus reflects the aggregate state of all devices in the EGM. If the requiredForPlay attribute in the profile of a device is set to true then if either the egmEnabled or hostEnabled attribute of the device is set to false then the egmState MUST reflect that the EGM is disabled. Similarly, if the egmLocked or hostLocked attribute of a device is set to true then the egmState MUST reflect that the EGM is locked out. If any one device is in such a state then the egmState MUST reflect that the EGM is disabled or locked out, as appropriate. Thus, after a device has been enabled or a lockout has been cleared, the EGM MUST evaluate the state of all active devices within the EGM to determine the proper value of the egmState attribute. At the same time, the deviceClass and deviceId attributes of the cabinetStatus MUST be updated to reflect the appropriate device. This is communicated in the following documentation by using the convention "evaluate(cabinet.egmState)". gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 179 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.24.2 G2S_EHE001 Event Handler Disabled by EGM If the EGM disables an event handler device, it must generate this event. Table 4.45 G2S_EHE001 Device, Meter, Log Changes, and Related Commands Details Device State Changes egmEnabled = "false" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands None. 4.24.3 G2S_EHE002 Event Handler Enabled by EGM If the EGM enables an event handler device, it must generate this event. Table 4.46 G2S_EHE002 Device, Meter, Log Changes, and Related Commands Details Device State Changes egmEnabled = "true" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands None. 4.24.4 G2S_EHE003 Event Handler Disabled by Host If the host disables an event handler device, it must generate this event. Table 4.47 G2S_EHE003 Device, Meter, Log Changes, and Related Commands Details Device State Changes hostEnabled = "false" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands None. Page 180 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.24.5 G2S_EHE004 Event Handler Enabled by Host If the host enables an event handler device, it must generate this event. Table 4.48 G2S_EHE004 Device, Meter, Log Changes, and Related Commands Details Device State Changes hostEnabled = "true" evaluate(cabinet.egmState) Meter State Changes None. Log State Changes None. Related Commands None. 4.24.6 G2S_EHE005 Event Handler Configuration Changed by Host This event is generated by the EGM after the configuration for the event handler has been changed by the host. Changes must be applied to the EGM, optionChangeStatus command sent, before this event is generated. Table 4.49 G2S_EHE005 Device, Meter, Log Changes, and Related Commands Details Device State Changes Subscription list updated. Meter State Changes None. Log State Changes None. Related Commands eventSubList 4.24.7 is sent to the owner host. G2S_EHE006 Event Handler Configuration Changed by Operator This event is generated by the EGM after the configuration for the event handler has been changed by an operator. Changes must be applied to the EGM before this event is generated. Table 4.50 G2S_EHE006 Device, Meter, Log Changes, and Related Commands Details Device State Changes Subscription list updated. Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 181 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.24.8 G2S_EHE101 Event Subscription Changed If the event subscription is changed within an event handler device, it must generate this event. Table 4.51 G2S_EHE101 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands eventSubList 4.24.9 is sent to the owner host. G2S_EHE102 Event Handler Queue Overflow If the event handler device event queue fills, it must generate this event. Table 4.52 G2S_EHE102 Device, Meter, Log Changes, and Related Commands Details Device State Changes eventHandlerOverflow = "true" Meter State Changes None. Log State Changes None. Related Commands None. 4.24.10 G2S_EHE103 Event Handler Queue Overflow Cleared If the event handler device queue full condition is cleared, it must generate this event. Table 4.53 G2S_EHE103 Device, Meter, Log Changes, and Related Commands Details Device State Changes eventHandlerOverflow = "false" Meter State Changes None. Log State Changes None. Related Commands None. Page 182 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25 Examples 4.25.1 Supported Event Command Sequence A host may wish to query the EGM for the list of supported events. This allows a host to discover the particular events an EGM supports, allowing for manufacturer defined events to be used. The list of supported events can then be used to construct event subscriptions. EGM HOST getSupportedEvents supportedEvents 4.25.1.1 getSupportedEvents: Host to EGM The following query is requesting all of the events that the event handler device supports. For simplicity the example is not using wildcards, however wildcards are valid for both the deviceClass and deviceId attributes. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2001" sessionId = "1001" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "false" > <getSupportedEvents> <device deviceClass = "G2S_eventHandler" deviceId = "1" /> </getSupportedEvents> </eventHandler> The response is shown on the following page. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 183 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.1.2 supportedEvents: EGM to Host The following response to the getSupportedEvents command shows all the events the event handler device in question supports. In this case it is the standard set of events. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3001" sessionId = "1001" sessionType = "G2S_response" > <supportedEvents> <supportedEvent deviceClass = "G2S_eventHandler" deviceId = "1" eventCode = "G2S_EHE001" eventText = " EGM Disabled" /> <supportedEvent deviceClass = "G2S_eventHandler" deviceId = "1" eventCode = "G2S_EHE002" eventText = "EGM Enabled" /> <supportedEvent deviceClass = "G2S_eventHandler" deviceId = "1" eventCode = "G2S_EHE003" eventText = " Host Disabled" /> <supportedEvent deviceClass = "G2S_eventHandler" deviceId = "1" eventCode = "G2S_EHE004" eventText = "Host Enabled" /> <supportedEvent deviceClass = "G2S_eventHandler" deviceId = "1" eventCode = "G2S_EHE005" eventText = "Configuration Changed By Host" /> <supportedEvent deviceClass = "G2S_eventHandler" deviceId = "1" eventCode = "G2S_EHE006" eventText = "Configuration Changed By Operator" /> <supportedEvent deviceClass = "G2S_eventHandler" deviceId = "1" eventCode = "G2S_EHE101" eventText = "Subscription Changed" /> <supportedEvent deviceClass = "G2S_eventHandler" deviceId = "1" eventCode = "G2S_EHE102" eventText = "Event Handler Queue Overflow" /> <supportedEvent deviceClass = "G2S_eventHandler" deviceId = "1" eventCode = "G2S_EHE103" eventText = "Event Handler Queue Overflow Cleared" /> </supportedEvents> </eventHandler> Page 184 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.2 Set Event Subscriptions Command Sequence In order to set the event subscriptions, the host will initiate the setEventSub command. The EGM will add the subscriptions to the list of existing subscriptions (ORs the subscription with already existing subscriptions) and generates an setEventSubAck as a response. The setEventSubAck is queued after all the pre-existing events, so any event that has a commandId lower than that of the setEventSubAck is going to have data based on the earlier version of the subscription. In the case where there is overlap between subscriptions, caused by the use of wildcards and specific event subscriptions, the more specific subscription is the one that is processed when an event occurs. However, forced subscriptions are always processed and can never be overridden. 4.25.2.1 EGM HOST setEventSub event eventAck event eventAck setEventSubAck setEventSub: Host to EGM The following add subscription request is adding the host’s event subscription for all cabinet class events, asking for the transaction data and device status for those events. It is also requesting to receive the communications overflow from the communications class. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2003" sessionId = "1003" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "false" > <setEventSub> <eventHostSubscription deviceClass = "G2S_cabinet" deviceId = "-1" eventCode = "G2S_all" sendDeviceStatus = "true" sendTransaction = "true" sendClassMeters = "false" sendDeviceMeters = "false" eventPersist = "true" /> <eventHostSubscription deviceClass = "G2S_communications" deviceId = "-1" eventCode = "G2S_CME003" sendDeviceStatus = "false" sendTransaction = "false" sendClassMeters = "false" sendDeviceMeters = "false" eventPersist = "true" /> </setEventSub> </eventHandler> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 185 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.2.2 setEventSubAck: EGM to Host The response to the set event subscription command is an acknowledgement stating the event subscription was added. The response would look like: <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3003" sessionId = "1003" sessionType = "G2S_response" > <setEventSubAck /> </eventHandler> Page 186 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.3 Get Current Event Subscriptions Command Sequence A host can, at any time, get a list of subscriptions for a particular event handler device. This is done by issuing the getEventSub command. 4.25.3.1 HOST getEventSub: Host to EGM <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2002" sessionId = "1002" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "false" > <getEventSub> <eventSelect deviceClass = "G2S_all" deviceId = "-1" eventCode = "G2S_all" /> </getEventSub> </eventHandler> 4.25.3.2 EGM getEventSub eventSubList eventSubList: EGM to Host The response to the getEventSub command is a list of all the current subscriptions for that event handler device. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3002" sessionId = "1002" sessionType = "G2S_response" > <eventSubList> <eventSubscription deviceClass = "G2S_cabinet" deviceId = "-1" eventCode = "G2S_CBE017" forceDeviceStatus = "true" forceTransaction = "true" forcePersist = "true" /> <eventSubscription deviceClass = "G2S_cabinet" deviceId = "-1" eventCode = "G2S_all" sendDeviceStatus = "true" sendTransaction = "true" eventPersist = "true" /> <eventSubscription deviceClass = "G2S_communications" deviceId = "-1" eventCode = "G2S_CME003" eventPersist = "true" /> </eventSubList> </eventHandler> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 187 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.4 Clear Event Subscriptions Command Sequence A host can clear its event subscriptions by using the clear event subscriptions command. As noted earlier the host can clear any subscription except forced subscriptions. The response to the clear event subscriptions command is the eventSubList command. HOST EGM clearEventSub eventSubList 4.25.4.1 clearEventSub: Host to EGM The following example shows the clearing of the communications class subscriptions that were added previously. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2004" sessionId = "1004" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "false" > <clearEventSub> <eventSelect deviceClass = "G2S_communications" deviceId = "-1" eventCode = "G2S_CME003" /> </clearEventSub> </eventHandler> 4.25.4.2 clearEventSubAck: EGM to Host The response to the clearEventSubAck command. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3004" sessionId = "1004" sessionType = "G2S_response" > <clearEventSubAck /> </eventHandler> Page 188 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.5 Set Event Handler State Command Sequence HOST EGM setEventHandlerState eventHandlerStatus 4.25.5.1 setEventHandlerState: Host to EGM The following is an example of a command that is generated by the host in order to disable the event handler device. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2005" sessionId = "1005" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "false" > <setEventHandlerState enable = "false" /> </eventHandler> 4.25.5.2 eventHandlerStatus: EGM to Host The response to this command is shown below: <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3005" sessionId = "1005" sessionType = "G2S_response" > <eventHandlerStatus hostEnabled = "false" egmEnabled = "true" /> </eventHandler> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 189 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.6 Get Event Handler State Command Sequence HOST EGM getEventHandlerStatus eventHandlerStatus 4.25.6.1 get Event Handler Status: Host to EGM The following command is sent by the host to find the status of a particular event handler device. A monitoring host can check on the status of any event handler device. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2006" sessionId = "1006" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "false" > <getEventHandlerStatus /> </eventHandler> 4.25.6.2 eventHandlerStatus: EGM to Host The response to the command is shown below: <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3006" sessionId = "1006" sessionType = "G2S_response" > <eventHandlerStatus hostEnabled = "false" egmEnabled = "true" /> </eventHandler> Page 190 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.7 Get Event Handler Log Status Command Sequence EGM HOST getEventHandlerLogStatus eventHandlerLogStatus 4.25.7.1 getEventHandlerLogStatus: Host to EGM The following command is sent by a host to get the event handler device log status from the specified event handler device. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2007" sessionId = "1007" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "false" > <getEventHandlerLogStatus /> </eventHandler> 4.25.7.2 eventHandlerLogStatus: EGM to Host The response to this command is the list log entries for the event handler device as shown below: <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3007" sessionId = "1007" sessionType = "G2S_response" > <eventHandlerLogStatus lastSequence = "42" totalEntries = "27" /> </eventHandler> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 191 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.8 Get Event Handler Log Command Sequence EGM HOST getEventHandlerLog eventHandlerLogList 4.25.8.1 getEventHandlerLog: Host to EGM The following command is sent by a host to get the event handler device log from this event handler device. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "2008" sessionId = "1008" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "false" > <getEventHandlerLog lastSequence = "42" totalEntries = "1" /> </eventHandler> 4.25.8.2 eventHandlerLogList: EGM to Host The response to this command is the list log entries for the event handler device as shown below: <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "3008" sessionId = "1008" sessionType = "G2S_response" > <eventHandlerLogList> <eventHandlerLog logSequence = "42" deviceClass = "G2S_cabinet" deviceId = "1" eventCode = "G2S_CBE023" eventId = "7" eventDateTime = "2001-12-17T09:30:47-05:00" transactionId = "0" eventAck = "false" > <affectedDeviceList> <deviceSelect deviceClass = "G2S_cabinet" deviceId = "1" /> </affectedDeviceList> </eventHandlerLog> </eventHandlerLogList> </eventHandler> Page 192 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.25.9 Event Report Command Sequence HOST EGM eventReport eventAck 4.25.9.1 eventReport: EGM to Host The following is an example of a command that is generated by the EGM in response to an event that has just happened on the EGM to which the host is subscribed. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.321-05:00" commandId = "3009" sessionId = "1009" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "false" > <eventReport deviceClass = "G2S_cabinet" deviceId = "1" eventCode = "G2S_CBE023" eventId = "12345" eventDateTime = "2001-12-17T09:30:47-05:00" transactionId = "42" > <deviceList> <statusInfo deviceClass = "G2S_cabinet" deviceId = "1" > <cabinetStatus egmEnabled = "true" logicDoorOpen = "true" cabinetDoorOpen = "true" currencyId = "USD" /> </statusInfo> </deviceList> </event> </eventHandler> 4.25.9.2 eventAck: Host to EGM The response to the event is shown below. <eventHandler deviceClass = "G2S_eventHandler" deviceId = "1" dateTime = "2003-03-01T13:23:27.432-05:00" commandId = "2009" sessionId = "1009" sessionType = "G2S_response" > <eventAck eventId = "12345" /> </eventHandler> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 193 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.26 Event Handler Device Option Configuration The following sections identify the G2S-specified configuration option selections for event handler devices and provides examples of optionItem elements in Section 4.26.6. Configuration option selections are set using commands from the optionConfig class. The current configuration option selections for an event handler device are reported via the eventHandlerProfile command. Further descriptions of the sub-parameters can be found under the eventHandlerProfile command. 4.26.1 Option Group Definitions optionGroupId optionGroupName 4.26.2 G2S_eventHandlerOptions G2S Event Handler Options G2S Protocol Option Definitions optionId G2S_protocolOptions securityLevel G2S_administrator minSelections 1 maxSelections 1 duplicates Duplicate Key Parameter Type paramId 4.26.3 n/a n/a Complex G2S_protocolParams paramName G2S Protocol Parameters paramHelp Standard G2S protocol parameters for Event Handler devices G2S Protocol Option Sub-Parameter Definitions Table 4.54 G2S Protocol Option Sub-Parameter Definitions paramId paramName Example paramHelp G2S_configurationId Configuration Identifier 123456 ID assigned by the last successful G2S option configuration G2S_restartStatus Enabled on Restart True hostEnabled attribute status upon EGM restart G2S_useDefaultConfig Use Default Configuration False Use default configuration on restart G2S_requiredForPlay Required For Play True Device is required for game play G2S_minLogEntries Minimum Log Entries 35 Minimum number of entries for the device level log G2S_timeToLive Time to Live 30000 Time to live value for requests (in milliseconds) G2S_queueBehavior Queue Behavior G2S_disable Required behavior when event queue overflows Page 194 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.26.4 Forced Subscription Table Option Definitions optionId G2S_forcedSubscriptionTable securityLevel G2S_administrator minSelections 0 maxSelections >=1 duplicates Duplicate Key Parameter Type paramId 4.26.5 false G2S_deviceClass + G2S_deviceId + G2S_eventCode Complex G2S_forcedSubscription paramName Forced Subscription Table paramHelp Forced event subscription for host Forced Subscription Table Sub-Parameter Definitions Table 4.55 Forced Subscription Table Sub-Parameter Definitions paramId paramName Example paramHelp G2S_deviceClass Device Class cabinet Class causing the event G2S_deviceId Device ID 1 Device ID within class causing the event G2S_eventCode Event Code G2S_CBE001 Event code being forced (can be G2S_all) G2S_forceDeviceStatus Include Status True Include affected device statuses with event G2S_forceTransaction Include Transaction Info True Include affected transaction record with event G2S_forceClassMeters Include Class Meters True Include affected class meters with event G2S_forceDeviceMeters Include Device Meters True Include affected device meters with event G2S_forceUpdatableMeters Just Updated Meters True Only send meters that could have been updated by this event G2S_forcePersist Persist Event True Persist event until acknowledged gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 195 Chapter 4 eventHandler Class G2S™ Message Protocol v1.0.3 4.26.6 Example optionItem Elements in optionList The following are examples of optionItem elements used by the EGM to describe its configurable options for the event handler device. These elements are sent by the EGM to the host in the optionList command. // G2S Protocol Options <optionItem optionId = "G2S_protocolOptions" securityLevel = "G2S_administrator" minSelections = "1" maxSelections = "1" > <optionParameters> <complexParameter paramId = "G2S_protocolParams" paramName = "G2S Protocol Parameters" paramHelp = "Standard G2S protocol parameters for event handler devices" > <integerParameter paramId = "G2S_configurationId" paramName = "Configuration Identifier" paramHelp = "ID assigned by the last successful G2S option configuration" canModLocal = "false" canModRemote = "false" /> <booleanParameter paramId = "G2S_restartStatus" paramName = "Enabled on Restart" paramHelp = "hostEnabled attribute status upon EGM restart" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_useDefaultConfig" paramName = "Use Default Configuration" paramHelp = "Use default configuration on restart" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_requiredForPlay" paramName = "Required For Play" paramHelp = "Device is required for game play" canModLocal = "true" canModRemote = "true" /> <integerParameter paramId = "G2S_minLogEntries" paramName = "Minimum Log Entries" paramHelp = "Minimum number of entries for the device level log" canModLocal = "true" canModRemote = "true" minIncl = "1" /> <integerParameter paramId = "G2S_timeToLive" paramName = "Time To Live" paramHelp = "Time to live value for requests (in milliseconds)" canModLocal = "true" canModRemote = "true" minIncl = "0" /> <stringParameter paramId = "G2S_queueBehavior" paramName = "Queue Behavior" paramHelp = "Required behavior when event queue overflows" canModLocal = "true" canModRemote = "true" /> </complexParameter> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 123456 </integerValue> <booleanValue paramId = "G2S_restartStatus" > true </booleanValue> <booleanValue paramId = "G2S_useDefaultConfig" > false </booleanValue> <booleanValue paramId = "G2S_requiredForPlay" > true </booleanValue> <integerValue paramId = "G2S_minLogEntries" >35</integerValue> <integerValue paramId = "G2S_timeToLive" >30000</integerValue> <stringValue paramId = "G2S_queueBehavior" > G2S_disable </stringValue> </complexValue> </optionCurrentValues> <optionDefaultValues> Page 196 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 4 eventHandler Class <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 0 </integerValue> <booleanValue paramId = "G2S_restartStatus" > true </booleanValue> <booleanValue paramId = "G2S_useDefaultConfig" > false </booleanValue> <booleanValue paramId = "G2S_requiredForPlay" > true </booleanValue> <integerValue paramId = "G2S_minLogEntries" >35</integerValue> <integerValue paramId = "G2S_timeToLive" >30000</integerValue> <stringValue paramId = "G2S_queueBehavior" > G2S_disable </stringValue> </complexValue> </optionDefaultValues> </optionItem> // Forced Subscription Table Options <optionItem optionId = "G2S_forcedSubscriptionTable" securityLevel = "G2S_administrator" minSelections = "1" maxSelections = "1" duplicates = "false" > <optionParameters> <complexParameter paramId = "G2S_forcedSubscription" paramName = "Forced Subscription Table" paramHelp = "Forced event subscription for host" > <stringParameter paramId = "G2S_deviceClass" paramName = "Device Class" paramHelp = "Class causing the event" canModLocal = "true" canModRemote = "true" /> <integerParameter paramId = "G2S_deviceId" paramName = "Device ID" paramHelp = "Device ID within class causing the event" canModLocal = "true" canModRemote = "true" /> <stringParameter paramId = "G2S_eventCode" paramName = "Event Code" paramHelp = "Event code being forced (Can be G2S_all)" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_forceDeviceStatus" paramName = "Include Status" paramHelp = "Include affected device statuses with event" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_forceTransaction" paramName = "Include Transaction Info" paramHelp = "Include affected transaction record with event" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_forceClassMeters" paramName = "Include Class Meters" paramHelp = "Include affected class meters with event" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_forceDeviceMeters" paramName = "Include Device Meters" paramHelp = "Include affected device meters with event" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_forceUpdatableMeters" paramName = "Just Updatable Meters" paramHelp = "Only send meters that could have been updated by this event" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_forcePersist" paramName = "Persist Event" paramHelp = "Persist event until acknowledged" gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 197 G2S™ Message Protocol v1.0.3 Chapter 4 eventHandler Class canModLocal = "true" canModRemote = "true" /> </complexParameter> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_forcedSubscription" > <stringValue paramId = "G2S_deviceClass" >G2S_cabinet</stringValue> <integerValue paramId = "G2S_deviceId" >1</integerValue> <stringValue paramId = "G2S_eventCode" >G2S_CB001</stringValue> <booleanValue paramId = "G2S_forceDeviceStatus" >true</booleanValue> <booleanValue paramId = "G2S_forceTransaction" >true</booleanValue> <booleanValue paramId = "G2S_forceClassMeters" >true</booleanValue> <booleanValue paramId = "G2S_forceDeviceMeters" >true</booleanValue> <booleanValue paramId = "G2S_forcePersist" >false</booleanValue> <booleanValue paramId = "G2S_forceUpdatableMeters" >true</booleanValue> </complexValue> </optionCurrentValues> <optionDefaultValues /> <optionItem> Page 198 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 5 meters Class 5.1 Introduction Chapter 5 meters Class The meters class is used to collect meter information from an EGM. Meter information can be queried by a host in real-time or a host may set a periodic meter subscription to cause the EGM to send selected meters at predetermined intervals. Commands contained within the meters class are used to manage meter subscriptions and to send meter information. NOTE: A host may also subscribe to device or class meters affected by an event via the class (see Chapter 4). Device and class meter sets are always consistent, whether they are reported via a getMeterInfo command, a meter subscription, or as associated data with an event. eventHandler 5.2 Meter Subscriptions Each host registered with an EGM may subscribe to periodic meter reports from that EGM. For the purposes of the G2S protocol, meter subscriptions are explicitly set by the host. When an EGM first starts up, it contains no meter subscriptions for any host. After receiving a commsOnLine command from an EGM, a host may set its meter subscriptions. Once a host has set a meter subscription, the EGM MUST persist that subscription until it is modified or cleared by the host. A host may set periodic meter subscriptions with an EGM that causes selected meters to be sent on a fixed schedule (G2S_onPeriodic) and/or at a scheduled End of Day time (G2S_onEOD). The periodic meter subscription is designed to be used by accounting servers that need to collect periodic meter snapshots, as well as by other servers who receive most meters when events occur, but periodically want to check these or other meter values. The meters class is a multi-device class. Each registered host is assigned a deviceId (which is given the same value as the hostId) within the communications class (see Chapter 2). This allows the EGM to differentiate between hosts. This deviceId is also used within the eventHandler (see Chapter 4) and meters classes to identify each host’s subscriptions. The deviceId assigned within the communications class is used by a host to reference its event and meters subscriptions. Each host owns its subscriptions. Only the owner of a meter subscription can set or clear that subscription. Each EGM maintains one periodic meter subscription and one EOD meter subscription for each hostId. Each subscription can contain as many meter selection commands as necessary to fully describe the meters required by a host. If an EGM receives a new meter subscription and it already has a subscription of that type for that hostId, the existing subscription will be overwritten. Meter subscriptions can be cleared using the clearMeterSub command (see Section 5.22), or by sending a setMeterSub command that specifies no meters (see Section 5.21). gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 199 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.3 Crafting Periodic Subscriptions Periodic meter subscriptions allow the host to specify a set of meters which are sent at the specified periodic interval (subscription schedule). In order to stagger the arrival of the periodic meter reports from thousands of EGMs, the host can specify an offset from midnight by which the base schedule calculation is performed. The periodicInterval is used to inform the EGM how frequently the periodic meter set should be sent, for example every 15 minutes. The periodicBase attribute provides an offset so that the host can tell the EGM that, not only does it want the meters every 15 (fifteen) minutes, they also should be slightly offset for the reports from other EGMs. The periodicBase specifies the number of milliseconds the schedule is to be offset from midnight. A host system will typically choose to have the meter reports spread out over a minute or two. For End of Day (EOD) reports, meters are sent once per day at the offset from midnight that is specified by the host via the eodBase attribute. For periodic reports, the EGM will take the base, which is the milliseconds after midnight, plus the interval to determine the first trigger point. After the first trigger point and for each successive trigger point, the EGM adds the interval to determine the next trigger point. If the periodicBase is set to 0 (zero) and the periodicInterval is a non-zero value, then periodic meter reports are sent to the host every periodicInterval milliseconds, using a periodic schedule that starts at midnight plus the periodicInterval. If a host desires to have periodic meters sent once per day, at a time other than when the EOD meters are sent, it should set the periodicBase to the time at which it would like the meters collected and the periodicInterval to one day, which is 86400000 milliseconds. EOD meter subscriptions, being sent only once per day, forgo the periodicInterval attribute and just use the eodBase attribute to specify when the meters are to be gathered and sent. 5.4 Periodic vs. EOD Meter Subscriptions In addition to the differences described above related to the creation of the meter subscription commands, additional significant differences between periodic and EOD meter subscriptions follow: EOD meterInfo commands are sent once per day, whereas periodic meter subscriptions are sent as often as needed, using the schedule defined by each host, using the periodicBase and periodicOffset attributes. Periodic meterInfo commands are always sent as notifications to the host—that is, no response is allowed, or fire and forget. EOD meterInfo commands are sent as requests—that is, an application response, meterInfoAck, is expected from the host to which the message is sent. If no response is received within the timeToLive value defined in the message, the EGM MUST collect a new EOD meter set and send it to the host, repeating this behavior until a meterInfoAck acknowledgement is received. Page 200 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.5 Periodic Reports When EGM is Offline If the EGM is offline, the EGM MAY suspend the gathering of Periodic meter reports, with the schedule being resumed at the first trigger point that occurs after the EGM regains communication with the host. For End of Day meter reports, if the EGM is offline at the time that the End of Day meter report is to be created, the EGM MUST process the EOD meter request and place it on the outbound queue to the host to ensure that an End of Day snapshot is captured at the appropriate time, even if there are temporary network difficulties. If the EGM is powered down through the EOD trigger time, the EGM must gather the EOD meters when the EGM comes back up. In any case, the EGM must retry the EOD meter message until it is acknowledged by the host. 5.6 Meter Classifications Within the G2S protocol, meters are organized into ten meter groups: cabinet, performance, game denomination, wager category, transfer in, transfer out, progressive, voucher, currency in, and currency out. All of these meter groups are available by class (EGM life-to-date) or by individual device, except for the wager category meters which are only available at the individual device level. Cabinet This group includes the current value of the credit meters, counts for cabinet door openings, game play counts, credit meter collection meters, bonus award meters, and total wagered meters for the EGM (broken down by funding type). Performance This meter group includes meters related to actual game play on the EGM, such as coin in, coin out, and games played. Meters in this group are available for each individual game on the EGM, game play device meters, and also as LTD meters for the EGM, gamePlay class meters. Game Denomination This group includes a limited set of performance meters used to track the performance of different denominations at the game play device and class level. Wager Category This group includes a limited set of performance meters used to track the performance of different wager categories within a paytable at the game play device level. These meters are not accumulated at the class level. Transfer In This group includes meters related to the transfer of funds into the EGM, such as progressives, bonuses, and wagering account transfers. Transfer Out This group includes meters related to the transfer of funds out of the EGM, such as handpays, and wagering account transfers. Voucher This group includes meters related to the transfer of funds resulting from voucher transactions. For vouchers, counts must be maintained by fund type, and the redemption of EGM-issued and system-issued vouchers at an EGM are accounted for separately. Progressive This group contains the total amount of wager contributions to progressive devices (or class), as well as the count of contributing games played. Currency In This group includes meters related to currency accepted by coin acceptors and note acceptors. Currency Out This group includes meters related to currency dispensed by coin hoppers and note dispensers. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 201 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 Even though vouchers are collected by the note acceptor, when a voucher is redeemed by an EGM, the funds transferred to the EGM are recorded using transfer in meters, not currency meters. Only actual currency accepted or disbursed is recorded using the currency meters. Table 5.1 identifies the meter group(s) used by the devices in each G2S class: Table 5.1 Meter Groups by G2S Class G2S Class Meter Group(s) cabinet Cabinet gamePlay Performance Wager Category Game Denomination handpay Transfer Out coinAcceptor Currency In noteAcceptor Currency In hopper Currency Out noteDispenser Currency Out progressive Transfer In and Progressive bonus Transfer In voucher Voucher WAT Transfer In and Transfer Out 5.7 Expected and Omitted Meters The meterInfo responses sent by an EGM as a result of a getMeterInfo request, or as a result of a meter subscription, MUST contain all meters in the identified group if the functionality referenced by the meters is supported by the EGM. If the EGM does not support the referenced functionality, it may exclude the meters, and the requesting system will assume a default value of 0 (zero). Some examples of meters which may be omitted by an EGM include the cabinet bonus meters (if the EGM does not support bonusing), the note acceptor dispenser meters described in the Currency Out meter group (if the EGM does not have a note dispenser), and the secondary game meters in the performance meter group (if the EGM has no secondary game function). If the EGM does not support the class or device for which a set of meters are requested, the EGM MUST return the general G2S_APX007 Class Not Supported or G2S_APX003 Invalid Device Identifier errors (described in Chapter 1). NOTE: Host system developers must be aware that meter sets returned with event subscriptions will only contain those meters in the group that could be updated as a result of the event, if the sendUpdatableMeters flag has been set to true. In this case, assuming a default value of 0 (zero) for meters missing from the meter group is improper. Page 202 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.8 Meters and Currencies Within the G2S protocol, meters are either monetary values or counts. Each EGM has a base currency. All monetary meters in the EGM are expressed in terms of this currency, however to accommodate fractional cent play, these meters are expressed in millicents rather than in the minor unit of the base currency, or as decimal values (which would result in rounding errors). Items of value such as notes and coins, which are accepted or dispensed by the EGM, may be expressed in other currencies, however when the item of value is accepted or dispensed, the EGM must translate the value of the item into the base currency of the EGM and record the translated value against its meters in the base currency of the EGM, expressed in thousandths of the minor unit. The translated value appears on the credit, and other, meters. The EGM is not expected to maintain meters in more than one currency. The G2S protocol uses the set of codes defined by ISO-4217 to express currencies. Monetary meters are expressed in one thousandth of the minor unit of the base currency of the EGM. (Note: this does not affect count or percentage meters.) For example, If the base currency is United States Dollars, then monetary meters are expressed in millicents (1/1000th of one cent). Typically, depending on the base currency of the EGM, there is an implied decimal place to convert from the minor unit to the major unit of the currency. The ISO-4217 standard defines the number of implied decimal places when converting from the minor unit to the major unit of a currency. Because monetary meters are recorded in thousandths of the minor unit, there will always be a conversion applied to convert meter values to minor or major units of the currency. The range of meter values is defined as 0 to 999,999,999,999,999 ($9,999,999,999.99999 for USD). The following chart provides an example of meter representations for US dollars: Denomination One US dollar ($1.00) Meter Representation 100000 1/100 of a dollar or 1 cent 1000 25 cents 25000 Thirty seven dollars and 43 cents 5.5 cents 1/8 cent (.125 cents) 3743000 55000 125 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 203 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.9 Credit Meters Three distinct types of credits are supported by the protocol. The credit meter displayed to the player is the total of the three types of credits. The EGM MUST maintain a separate credit meter for each credit type in persistent storage. cashable Credits that are equivalent to cash. promotional Credits for promotional play that can be converted into cash. nonCashable Credits for promotional play that cannot be converted to cash. Credits must be played at an EGM or transferred off. The order of precedence for using credits is: nonCashable, promotional, and then cashable. All credits won from base game play or progressives are applied to the cashable credit meter. Credits won from bonus features are applied to the meter specified in the relevant commands. Transfers due to voucher or WAT activity will cause credits to be added to, or removed from, any of the three meters as specified in those commands. 5.10 Meter Consistency Within the G2S protocol, the meters within a meter snapshot MUST be consistent, that is: • Updates to the meters MUST be done within a single transaction, • All meters affected by an event MUST be updated at the same time and • The EGM MUST NOT report meters until all meters affected by an event have been updated. Thus, the result of the following generalized formula MUST always be true: Money In + Money Won – Money Out – Money Wagered – Player Credits = 0 Money In includes physical coin in, notes accepted, vouchers redeemed, and WAT transfers into the EGM. Money Won includes coin out as well as bonus and progressive wins paid to the credit meter. Money Out includes physical coin out, notes disbursed, vouchers issued, and WAT transfers off of the EGM. Money Wagered is equivalent to coin in. For an extended discussion, please see B Balancing The G2S Meter Model. Page 204 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.11 Meter Consistency in Complex Transactions In several cases in the protocol, commands that affect the meters in several classes can occur in a series of transactions initiated by a single event (for example game play results in a handpay which is paid by a voucher, system directs that a WAT transfer cause a voucher to be issued, and so on). To ensure consistent protocol implementation, and to also ensure that the appropriate meters are updated for the intervening events, the EGM MUST update all affected meters when it is determined that the transaction is going to be successful. As an example, consider the case of a game play transaction that results in a large win that must be hand paid, but the casino has elected to have handpays keyed off to vouchers that the player takes to the cage for redemption. The EGM cannot be sure that the transaction will successfully complete until the voucher is issued, at which time all meters get updated (see Figure 5.1). In this case, by updating all meters when the transaction is known to be successful, the meters associated with the voucher issuance event show the voucher issuance meters were properly incremented, the Keyed Off event shows that the handpay transfer meters do not increment (the game play win was actually paid to a voucher, rather than being transferred off the EGM), and the Game Ended event shows that the win was game paid. Figure 5.1 One Meter Update Per Transaction gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 205 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.12 Simple and Complex Meters The G2S meter model accommodates both simple and complex meters. A simple meter, simpleMeter element, is the lowest level meter reported by the EGM. Simple meters are often referred to as atomic meters, primitive meters, or leaf meters, and have the following attributes: Table 5.2 simpleMeter Attributes Attribute Restrictions Description meterName type: meterNames use: required Name of the meter: GSA- or manufacturer-assigned. See Section 5.25.3 for GSA meter name enumerations. meterValue type: meterValue use: required Current value of the meter. meterType type: meterTypes use: optional enumerations: G2S_count G2S_amount G2S_percent default = <null> Type of meter. meterRollover type: meterValue use: optional default = <null> Rollover value of the meter. meterIncreasing type: boolean use: optional default = <null> Indicates whether the meter is an ever-increasing meter. The following example highlights the construction of a simple meter information message without the optional attributes. <simpleMeter meterName = "G2S_wageredAmt" meterValue = "123450000" /> The next example highlights the construction of a simple meter information message with the optional attributes. <simpleMeter meterName = "G2S_wageredAmt" meterValue = "123450000" meterType = "G2S_amount" meterRollover = "9999999999999" meterIncreasing = "true" /> Complex meters, complexMeter elements, provide a mechanism for breaking down simple meters into component parts. In practice, complex meters elements are used to group the components of a meter into a logical unit. Those components may be simple meters or additional complex meters. Ultimately, a complex meter structure, at its lowest level, will be composed of simple meters. The value of a complex meter is calculated by adding the values of the simple meters contained within the complex meter. Because the value of a complex meter is determined from simpleMeter elements, a complexMeter element itself has only one attribute, meterName. Page 206 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 5 meters Class The following example highlights the construction of a complex meter information message when the G2S_testMeterAmt meter is broken down into its component parts: <complexMeter meterName = "G2S_testMeterAmt" > <simpleMeter meterName = "G2S_subMeter1Amt" meterValue = "120000000" /> <simpleMeter meterName = "G2S_subMeter2Amt" meterValue = "3000000" /> <simpleMeter meterName = "G2S_subMeter3Amt" meterValue = "450000" /> </complexMeter> The meter value of the complex meter, 123450000, can be determined by adding the meter values of the simple meters contained within the complex meter. This model of simple and complex meters permits the G2S meter model to be extended in a fashion where new EGMs introduced to the gaming floor will continue to be compatible with the existing host systems. The rules for extending the meter model (see Section 5.14) apply to meters specified by GSA as well as to those specified in manufacturer extensions. 5.13 Optional Meter Attributes The getDeviceMeters, getGameDenomMeters, getWagerMeters, and getCurrencyMeters commands include three optional meter definition attributes that allow a host to query an EGM for each meter’s type, direction, and rollover value. These three values give the host additional information about an unknown meter that may provide enough information to the host for it to be able to report the meter in a reasonable fashion. The meterType attribute is used to indicate whether the meter is a count meter or a value meter. The meterIncreasing attribute indicates whether a meter is an ever increasing meter (like most meters). An example of a meter which is not ever increasing is the EGM’s cashable credit meter. The meterRollover attribute indicates the maximum value that can be stored on the meter; the next increment in the meter will cause the meter to return to 0 (zero). Within the protocol, the data type of all meters has 15 significant digits (maximum = $9,999,999,999.99999 for USD monetary meters); consequently, for EGMs that store meters in this format, it is unlikely that the meters will ever rollover. However, some manufacturers may choose to store their proprietary meters in other formats that may cause meters to rollover. Even if an EGM is storing meters in the 15 digit format, all EGMs MUST support the query for rollover values. Hosts will use these values to accurately calculate changes in meter values. When requesting meters, a host can elect to have these optional meter definition attributes included with simple meters. This is accomplished by setting the meterDefinitions attribute to true. When meter definitions are requested, the EGM MUST include the meterType, meterRollover and meterIncreasing attributes within each simpleMeter element. Please note that the default value of these optional attributes is a <null> character, and so a <null> character received in these fields must be appropriately handled by receiving applications. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 207 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.14 Extending the Meter Model GSA will define the base set of root, or highest, level meters for the G2S protocol. As a result, GSA owns these meters, and so is the only party authorized to break down these meters by creating sub-meters under them. Only the creator of a root level meter, GSA or a manufacturer, shall be permitted to define a breakdown of that meter into component, or simple, meters. To accommodate a second/alternate view of the data, GSA may create a second root level meter, with an alternate name, whose component meters represent a traditional GSA meter, but use a different view. These new root level meters will be communicated by the release of a new version of the G2S protocol document and schema. Manufacturers who need to extend the meter model should first apply to GSA for an official extension, which is the easiest way to extend the model. If this method does not work, the manufacturer can create a new root level meter, using that manufacturer’s namespace extension. The names of new meters created by the manufacturer MUST start with the manufacturer’s GSA-assigned prefix followed by the underscore character, and then a descriptive name of the meter (for example, ABC_coinIn). In accordance with the rules above, this new root meter, created by the manufacturer ABC, can only be broken down by manufacturer ABC. See Chapter 1 for an extended discussion of unique identifiers in G2S. 5.15 Metering at the Class and Device Level Meters are available at two levels within the protocol: class and device. Class meters represent the aggregate total of the meters for all devices within the class. Over time, as devices are added and removed from a class, the aggregate total of the individual device meters will no longer equal the class meters. Class meters provide life-to-date totals for the EGM. Individual device meters only represent the life-to-date totals for the device. The life of a device may be different than the life of the EGM. All devices within a class will probably use the same meter structure, and so the class meters are expected to follow suit. However, as the devices within a class may be using different complex meter structures, each manufacturer MUST adopt a strategy for rolling up the device-level meters into the class-level meters. The protocol does not require that the complex meter structure of each device within a class be consistent or that the complex meter structure for the class-level meters be consistent with the individual devices. However, complex meter structures used at both the class-level and the device-level MUST obey the same rules—that is, the value of a complex meter MUST be derived by adding the values of the simple meters contained within the complex meter. By convention, device identifier 0 (zero) is used to access the class-level meters for a class. Device identifier 0 (zero) MUST NOT be used as a device identifier for individual logical or physical devices. It should only be used as a query and reporting convention for accessing class-level data. Page 208 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 5.16 Chapter 5 meters Class Wildcard Conventions The meters class supports the G2S_all wildcard to simplify meter selection throughout the meters class of commands. Classes are referenced by specifying the class name, for example deviceClass = "G2S_cabinet". Alternatively, all classes can be referenced using the all wildcard, for example deviceClass = "G2S_all". Individual devices are referenced by specifying the class of the device and the device identifier of the device within that class, for example deviceClass = "G2S_gamePlay" deviceId = "1". All active devices within a class can be referenced using the –1 (negative one) wildcard, for example deviceId = "-1". NOTE: Using the –1 wildcard for deviceId does NOT include class meters, which is deviceId= "0", nor does the –1 wildcard include inactive devices. When these wildcards are used, all instances of the particular attribute are reported. Thus, when is specified, all classes within the EGM MUST be reported. When deviceId = "1" is specified, all active devices within a class MUST be reported. The life-to-date class meters for all classes within the EGM can simply be referenced as deviceClass = "G2S_all" deviceId = "0". deviceClass = "G2S_all" The following example demonstrates how a host would request all meters for all devices within the EGM (again, this wildcard selection does not include the class-level meters): <getDeviceMeters deviceClass = "G2S_all" deviceId = "-1" /> A host could request meters for all active devices in the gamePlay class by specifying: <getDeviceMeters deviceClass = "G2S_gamePlay" deviceId = "-1" /> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 209 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.17 Request-Response Pairs The following tables organize the commands contained within the meters class into request-response pairs: Table 5.3 Commands Originated by EGM Request Response meterInfo meterInfoAck Table 5.4 Commands Originated by Host Request Response Owner Guest getMeterInfo meterInfo Yes Yes setMeterSub meterSubList Yes No getMeterSub meterSubList Yes Yes clearMeterSub meterSubList Yes No Page 210 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 5.18 Chapter 5 meters Class getMeterInfo Command This command is used by a host to request current meter information from an EGM. Because each EGM may contain different primitive meters and report different complex meter structures, it would be very inconvenient and impractical for a host system to construct meter queries using each specific EGM’s chosen meter structure. Potentially, a host would have to customize its meter queries for each EGM. Thus, when reporting meters, an EGM always reports all meters for a specific device or class. This alleviates the need for a host to customize its requests and for an EGM to interpret those requests. 5.18.1 Requesting Wager Category, Denomination, and Currency Meters Devices within the gamePlay and currency-handling classes contain additional device-specific meter breakdowns below the device level. Special getMeterInfo sub-commands are used to request these devicespecific meter breakdowns. The standard getMeterInfo.getDeviceMeters command is used to request the totals for a device, and the following special sub-commands within the getMeterInfo command are used to request the additional breakdowns for the device. The game play devices contain additional meter breakdowns by denomination and wager category. For each game play device, at least one denomination and one wager category MUST be supported. The totals for all denominations reported by a device MUST equal the totals for the device. Likewise, the totals for all wager categories reported by a device MUST equal the totals for the device. Denomination and wager category meters are reported independently of one another. Either denomination breakdowns or wager category breakdowns can be requested. It is not possible to request denomination breakdowns by wager category or vice-versa. The protocol does not require that denomination and wager category breakdowns include the full set of performance meters specified by the protocol. Rather, only the primary wager meters are required—that is, amount wagered, number of games played, and payback percentage. Devices within currency-handling classes—that is, the noteAcceptor, noteDispenser, coinAcceptor and hopper classes—contain additional meter breakdowns by currency and denomination. For each device within these classes, at least one currency and denomination must be supported. The totals for all currencies and denominations must equal the totals for the device. Currency and denomination breakdowns include the full set of meters required at the device-level. Special sub-commands are used to request these device-specific meters: getGameDenomMeters, getWagerMeters and getCurrencyMeters. The getGameDenomMeters sub-command is used to request denomination breakdowns for game play devices. The getWagerMeters sub-command is used to request wager category breakdowns for game play devices. The getCurrencyMeters sub-command is used to request currency and denomination breakdowns for currency-handling devices. When used, these commands cause the EGM to report the full breakdown of meters for the specified device or devices. Device-specific meters are always reported as a complete set—that is, all components of a breakdown are included. Thus, the attributes of these special sub-commands are the same as the attributes of the getDeviceMeters sub-command. The getDeviceMeters sub-command reports the totals for a device. The special sub-commands provide a further breakdown. The breakdowns always equal the totals. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 211 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 The following example demonstrates how a request for all wager category meters for all game play devices would be constructed: <getWagerMeters deviceClass = "G2S_gamePlay" deviceId = "-1" /> Likewise, a request to report a breakdown of notes accepted by currency and denomination could be specified as: <getCurrencyMeters deviceClass = "G2S_noteAcceptor" deviceId = "-1" /> Like the getDeviceMeters command, multiple getGameDenomMeters, getWagerMeters and getCurrencyMeters sub-commands can be grouped within a single getMeterInfo command. When an EGM receives a getMeterInfo command that includes one or more of these sub-commands and a G2S_all wildcard for the class attribute, it MUST not return an error, but instead reply with a meterInfo command response for those classes which implement the meter breakdown. As an example, if an EGM receives a getMeterInfo.getCurrencyMeters command for deviceClass = "G2S_all" and deviceId = "-1", it should return the currency meters for all currency handling classes (coinAcceptor, hopper, noteAcceptor, and noteDispenser). Page 212 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.18.2 getMeterInfo Elements The sub-elements of the getMeterInfo command are the same as the sub-elements of the setMeterSub and meterSubList commands. Wildcard conventions are permitted for the sub-elements of the getMeterInfo command. A meterInfo command is sent by the EGM in response to a getMeterInfo command. Table 5.5 getMeterInfo Elements (sub-commands) Element Restrictions Description getDeviceMeters minOcc: 0 Contains a specific device meter information request. See Section 5.18.3. maxOcc: getWagerMeters minOcc: 0 maxOcc: getGameDenomMeters ∞ minOcc: 0 maxOcc: getCurrencyMeters ∞ ∞ minOcc: 0 maxOcc: ∞ Contains a specific wager category meter information request. See Section 5.18.4. Contains a specific game denomination meter information request. See Section 5.18.5. Contains a specific currency meter information request. See Section 5.18.6. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 213 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.18.3 getDeviceMeters Element The getDeviceMeters sub-command is used by the host to request the complete set of meters that are associated with a particular device. Table 5.6 getDeviceMeters Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Specifies a device class; wildcard G2S_all permitted. deviceId type: deviceId use: required Selects a specific device within the device class; wildcard -1 is permitted. deviceId = "0" is used to identify class level meters. meterDefinitions type: boolean use: optional default: false Indicates whether optional meter definition attributes should be included in the response. When requesting meters, a host can elect to have the optional meter definition attributes included with the meters. This is accomplished by setting the meterDefinitions attribute to true. When meter definitions are requested, the EGM MUST include the meterType, meterRollover and meterIncreasing attributes within each simpleMeter element. The following example demonstrates how a host would request all meters for all devices within the EGM: <getDeviceMeters deviceClass = "G2S_all" deviceId = "-1" /> Multiple requests for specific meters can be accommodated by grouping multiple getDeviceMeters subcommands within a single getMeterInfo command. Such a command would take the form: <getMeterInfo> <getDeviceMeters . . . /> <getDeviceMeters . . . /> <getDeviceMeters . . . /> </getMeterInfo> NOTE: The . . . is not part of the XML structure. It indicates where the additional attributes and elements of each of the getDeviceMeters command would be included. Page 214 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.18.4 getWagerMeters Element The getWagerMeters sub-command is used by the host to request the complete set of wager category meters that are associated with a particular game play device. Table 5.7 getWagerMeters Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Specifies a device class; wildcard G2S_all permitted. deviceId type: deviceId use: required Specific device within the device class; wildcard -1 is permitted. deviceId = "0" is used to identify class level meters. meterDefinitions type: boolean use: optional default: false Indicates whether meter definition attributes should be included in the response. 5.18.5 getGameDenomMeters Element The getGameDenomMeters sub-command is used by the host to request the complete set of denomination meters that are associated with a particular game play device. Table 5.8 getGameDenomMeters Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Specifies a device class; wildcard G2S_all permitted. deviceId type: deviceId use: required Specific device within the device class; wildcard -1 is permitted. deviceId = "0" is used to identify class level meters. meterDefinitions type: boolean use: optional default: false Indicates whether optional meter definition attributes should be included in the response. 5.18.6 getCurrencyMeters Element The getCurrencyMeters sub-command is used by the host to request the complete set of currency meters that are associated with a particular currency device. Table 5.9 getCurrencyMeters Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Used to specify a device class; wildcard G2S_all permitted. deviceId type: deviceId use: required Select a specific device within the device class; wildcard -1 is permitted. deviceId = "0" is used to identify class level meters. meterDefinitions type: boolean use: optional default: false Indicates whether optional meter definition attributes should be included in the response. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 215 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.19 meterInfo Command This command is used by an EGM to send meter information to a host in response to a getMeterInfo command, when meter information needs to be sent to a host as a result of a meter subscription, or as associated data for an event subscription. Device, denomination, wager category, and currency meters can all be combined in a single meterInfo command. The meterDateTime attribute of the meterInfo element indicates the meter snapshot time. If the meterInfo command that is generated as a result of a complex request or subscription is larger than can be reasonably produced by the EGM, the meterInfo command can be chunked, or divided, into multiple responses. The meterDateTime attribute MUST be the same in all of the separate chunks, and the separate messages are to be broken along getMeterInfo command boundaries. Additionally, the sessionType for all response chunks MUST be set to response, the sessionId MUST reflect the original sessionId, and the optional class level session continuation indicator must be set to true for all chunks except the final one. Using this strategy, a host will receive a series of valid XML documents, each of which can be tied together with a common meterDateTime and sessionId. See Chapter 1 for an extended discussion. Each meter report identifies the device class and device identifier of the device whose meters are being reported. • For wager category meters, the meter report also includes the wager category of the meters. • For game denomination meters, the meter report also includes the denomination of the meters. • For currency meters, the meter report also includes the currency and denomination of the meters. These attributes are contained in a single upper-level element and are applicable to all simpleMeter and complexMeter elements contained within that upper-level element. Page 216 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 Table 5.10 meterInfo Attributes Attribute Restrictions Description meterInfoType type: meterInfoTypes use: required Identifies the cause of meter message: G2S_onPeriodic or G2S_onEOD subscription, G2S_onDemand (responding to a request), or G2S_onEvent (associated data for an event). meterDateTime type: dateTime use: required Trigger date/time, or the date/time that the meter snapshot was taken by the EGM. If there are multiple chunks for meterInfo command, all contain the same date/time to tie them together. Table 5.11 meterInfo Elements Element Restrictions Description deviceMeters minOcc: 0 Contains the device meter group for a specific device. See Section 5.19.1. maxOcc: wagerMeters Contains the game denomination meter group for a specific device. See Section 5.19.3. ∞ Contains the currency meter group for a specific device. See Section 5.19.4. minOcc: 0 maxOcc: 5.19.1 ∞ minOcc: 0 maxOcc: currencyMeters Contains the wager category meter group for a specific device. See Section 5.19.2. minOcc: 0 maxOcc: gameDenomMeters ∞ ∞ deviceMeter Element This element contains the device meter group for a specific device. Table 5.12 deviceMeters Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Specifies the device class being reported. deviceId type: deviceId use: required Specifies the device within the class whose meters are being reported. deviceId = "0" is used to identify class level meters. Table 5.13 deviceMeters Elements Attribute Restrictions Description simpleMeter minOcc: 0 Contains the information for a specific simple (primitive) meter for the specified device. See Table 5.14 for attributes. maxOcc: complexMeter ∞ minOcc: 0 maxOcc: ∞ Contains the information for a specific complex meter for the specified device. See Table 5.15 for attributes. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 217 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 Table 5.14 simpleMeter Attributes Attribute Restrictions Description meterName type: meterNames use: required Name of the meter: GSA or manufacturer-assigned. See Section 5.25.3 for GSA meter names. meterValue type: meterValue use: required Current value of the meter. meterType* type: meterTypes use: optional default: <null> Type of meter. Included if meterDefinitions attribute in the request is set to true. meterRollover* type: meterValue use: optional default: <null> Rollover value of the meter. Included if meterDefinitions attribute in the request is set to true. meterIncreasing* type: boolean use: optional default: <null> Indicates whether the meter is an ever-increasing meter. Included if meterDefinitions attribute in the request is set to true. * So that the actual value of the meterType, meterRollover, and meterIncreasing attributes is not changed when the attribute is not included, the default for all three attributes is set to <null>. Table 5.15 complexMeter Attributes Attribute Restrictions Description meterName type: meterNames use: required Name of the meter: GSA or manufacturer-assigned. See Section 5.25.3 for GSA meter names. 5.19.2 wagerMeters Element This element contains the wager category meter group for a specific device. Table 5.16 wagerMeters Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Specifies the device class being reported. deviceId type: deviceId use: required Specifies the device within the class whose meters are being reported. deviceId = "0" is used to identify class level meters. wagerCategory type: wagerCategory use: required Wager category identifier. See Table 5.14 and Table 5.15 for a description of the simpleMeter and complexMeter elements within the wagerMeters element. Page 218 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.19.3 gameDenomMeters Element This element contains the game denomination meter group for a specific device. Table 5.17 gameDenomMeters Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class identifier. deviceId type: deviceId use: required Specifies the device within the class whose meters are being reported. deviceId = "0" is used to identify class level meters. denomId type: denomId use: required Specifies the game denomination whose meters are being reported. See Table 5.14 and Table 5.15 for a description of the simpleMeter and complexMeter elements within the gameDenomMeters element. 5.19.4 currencyMeters Element This element contains the currency meter group for a specific device. Table 5.18 currencyMeters Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class identifier. deviceId type: deviceId use: required Specifies the device within the class whose meters are being reported. deviceId = "0" is used to identify class level meters. currencyType type: currencyTypes use: required Currency type. currencyId type: currencyId use: required Currency identifier. denomId type: denomId use: required Denomination identifier. See Table 5.14 and Table 5.15 for a description of the simpleMeter and complexMeter elements within the currencyMeters element. 5.20 meterInfoAck Command As end of day meter sets are sent to hosts as requests, an acknowledgement command is needed so that the host can return an application-level acknowledgement that the meterInfo command has been received. The EGM sends the meterInfoAck to provide that acknowledgement. This command has no additional attributes or elements. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 219 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.21 setMeterSub Command This command is used by a host to register its meter subscription with an EGM. Requests for device, wager category, game denomination, and currency meters are all combined in a single command. Wildcard conventions are permitted. The sub-elements of the setMeterSub command are the same as the sub-elements of the getMeterInfo and meterSubList commands. A meterSubList command is sent by the EGM in response to a setMeterSub command. Each host gets one G2S_onPeriodic and one G2S_onEOD meter subscription for each EGM. Though a host may use wildcards to simplify its expression of the set meter subscription command, the EGM expands the meter subscription from the wildcard form to the full device form upon acceptance. The meterSubList is expected to return the full expanded form of the meter subscription. NOTE: Meter subscriptions are not additive. A new meter subscription command overwrites the prior subscription. An empty setMeterSub command is equivalent to a clearMeterSub command (though a setMeterSub event will still be sent). Table 5.19 setMeterSub Attributes Attribute Restrictions Description meterSubType type: meterSubTypes use: required Meter subscription type: G2S_onPeriodic or G2S_onEOD. periodicInterval type: milliseconds use: optional minIncl: 60000 default: 900000 Frequency of periodic meters in milliseconds. Minimum value is 1 (one) minute. • Required if meterSubType = "G2S_onPeriodic". • Invalid if meterSubType = "G2S_onEOD". periodicBase type: milliseconds use: optional default: 0 Offset from midnight, in milliseconds, for periodic meters. • Required if meterSubType = "G2S_onPeriodic". • Invalid if meterSubType = "G2S_onEOD". eodBase type: milliseconds use: optional default: 0 Offset from midnight, in milliseconds, for EOD meters. • Required if meterSubType = "G2S_onEOD". • Invalid if meterSubType = "G2S_onPeriodic". Page 220 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 Table 5.20 setMeterSub Elements Element Restrictions Description getDeviceMeters minOcc: 0 Contains a specific device meter information request. maxOcc: getWagerMeters ∞ Contains a specific wager category meter information request. minOcc: 0 maxOcc: getGameDenomMeters Contains a specific game denomination meter information request. minOcc: 0 maxOcc: getCurrencyMeters ∞ ∞ Contains a specific currency meter information request. minOcc: 0 maxOcc: ∞ The attributes of the getDeviceMeters, getWagerMeters, getGameDenomMeters, and getCurrencyMeters commands are described in the getMeterInfo Command section, which begins on page 211. 5.22 clearMeterSub Command This command is used by a host to remove a meter subscription from an EGM. A host may only clear its own subscriptions. A host may not clear the subscriptions of other hosts. A meterSubList command is sent by the EGM in response to a clearMeterSub command. Table 5.21 clearMeterSub Attributes Attribute Restrictions Description meterSubType type: meterSubTypes use: required Meter subscription type: G2S_onPeriodic or G2S_onEOD. 5.23 getMeterSub Command This command is used by a host to request a list of its current meter subscriptions from an EGM. It may also be used to request the list of subscriptions for another host by specifying the deviceId of the other host in the meters element. (This is the class level element. See Chapter 1 for details.) A meterSubList command is sent by the EGM in response to a getMeterSub command. Table 5.22 getMeterSub Attributes Attribute Restrictions Description meterSubType type: meterSubTypes use: required Meter subscription type: G2S_onPeriodic or G2S_onEOD. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 221 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.24 meterSubList Command This command is used by an EGM to send a listing of the specified meter subscription to a host. The meterSubList command is sent in response to a setMeterSub, clearMeterSub or getMeterSub command. Though a host may use wildcards to simplify its expression of the set meter subscription command, the EGM expands the meter subscription from the wildcard form to the full device form upon acceptance. The meterSubList is expected to return the full expanded form of the meter subscription. Table 5.23 meterSubList Attributes Attribute Restrictions Description meterSubType type: meterSubTypes use: required Meter subscription type: G2S_onPeriodic or G2S_onEOD. periodicInterval type: milliseconds use: optional minIncl: 60000 default: 900000 Frequency of periodic meters in milliseconds. Minimum value is 1 minute (60,000 milliseconds). Included if type: milliseconds use: optional default: 0 Offset from midnight, in milliseconds, for periodic meters. Included if meterSubType = periodicBase eodBase type: milliseconds use: optional default: 0 meterSubType = "G2S_onPeriodic". "G2S_onPeriodic". Offset from midnight, in milliseconds, for EOD meters. Included if meterSubType = "G2S_onEOD". Table 5.24 meterSubList Elements Element Restrictions Description getDeviceMeters minOcc: 0 Contains a specific device meter information request. maxOcc: getWagerMeters ∞ minOcc: 0 maxOcc: ∞ getGameDenomMeters minOcc: 0 maxOcc: getCurrencyMeters ∞ minOcc: 0 maxOcc: ∞ Contains a specific wager category meter information request. Contains a specific game denomination meter information request. Contains a specific currency meter information request. The attributes of the getDeviceMeters, getWagerMeters, getGameDenomMeters, and getCurrencyMeters commands are described in Section 5.18, which begins on page 211. Page 222 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.25 Data Types The following table lists the data types specific to the meters class: Table 5.25 meters Class Data Types Data Type Restrictions Description meterTypes type: string enumerations: G2S_count G2S_amount G2S_percent Indicates type of meter: count, amount, or percent. meterSubTypes type: extensibleList Type of meter subscription. See Section 5.25.1 for reserved enumerations. meterInfoTypes type: extensibleList Type of meter subscription. See Section 5.25.2 for reserved enumerations. meterNames type: extensibleList Name of GSA-defined meter. See Section 5.25.3 for reserved enumerations. 5.25.1 meterSubTypes Reserved Enumerations The following table lists the enumerations for the meterSubTypes data type: Table 5.26 Enumerations for the meterSubTypes Data Type Enumeration Description G2S_onPeriodic Meters are to be sent on a fixed schedule based on periodicInterval and periodicBase. The periodicInterval is the frequency, in milliseconds, with which the meters should be sent. The periodicBase is the starting time, in milliseconds since midnight, for the first set of meters. Additional sets of meters are sent at each subsequent periodicInterval (minimum interval of 1 (one) minute). G2S_onEOD Meters are sent once per day at eodBase. 5.25.2 meterInfoTypes Reserved Enumerations The following table lists the enumerations for the meterInfoTypes data type: Table 5.27 Enumerations for the meterInfoTypes Data Type Enumeration Description G2S_onPeriodic Meters are to be sent on a fixed schedule based on periodicInterval and periodicBase. The periodicInterval is the frequency, in milliseconds, with which the meters should be sent. The periodicBase is the starting time, in milliseconds since midnight, for the first set of meters. Additional sets of meters are sent at each subsequent periodicInterval (minimum interval of 1 (one) minute). G2S_onEOD Meters are sent once per day at eodBase. G2S_onDemand Meters are sent as a result of a getMeterInfo command. G2S_onEvent Meters are sent as associated data with an event. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 223 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.25.3 meterName Enumerations NOTE: Appendix I provides a comparison between the Nevada Gaming Control Board meters (Regulation 14, Standard 2.040, Section 1) and the relevant G2S class meters. 5.25.3.1 Performance Meters Performance meters are associated with the game play devices. They can be retrieved for any or all individual devices, or at a cabinet level by requesting the class level meters, with deviceId = "0". Table 5.28 Performance Meters Enumeration Description G2S_wageredAmt Total amount wagered. G2S_egmPaidGameWonAmt EGM paid base paytable win from game play. Does not include win from bonuses or progressives. G2S_handPaidGameWonAmt Hand paid base paytable win from game play. Does not include win from bonuses or progressives. G2S_egmPaidProgWonAmt EGM paid progressive win, resulting from game play. Does not include base paytable win, if any. G2S_handPaidProgWonAmt Hand paid progressive win, resulting from game play. Does not include base paytable win, if any. G2S_wonCnt Number of primary games won by the player. G2S_lostCnt Number of primary games lost by the player. G2S_tiedCnt Number of primary games where there were no credits won or lost. G2S_failedCnt Number of primary games where no outcome could be determined as the game failed to complete. G2S_avgPaybackPct Weighted theoretical payback percentage, with two implied decimal places. For example, an 88.65% payback is expressed is 8865. G2S_secWageredAmt Amount wagered on secondary games, such as double-up features. G2S_secWonAmt Amount won from secondary games. G2S_secWonCnt Count of secondary games won by the player. G2S_secLostCnt Count of secondary games lost by the player. G2S_secTiedCnt Count of secondary games where there were no credits won or lost. G2S_secFailedCnt Count of secondary games where no outcome could be determined (game failed to complete). G2S_theoPaybackAmt Theoretical payback amount. Incremented by the amount wagered times the payback percentage of the wager category played. NOTE: each time a secondary game is played, the secondary meters, G2S_sec*, are incremented. If a player successfully doubles up three times before exiting the double-up feature, the secondary meters should have been incremented three times; three games were played, three games were won, and amount wagered was incremented three times and the amount won was incremented three times. The G2S_egmPaidGameWonAmt meter should be incremented with the total winnings remaining when the double up feature is exited. When double-up meters are in use, the win amount related to the base game play can be calculated as: base game play win amount = game won amount + secondary wagered amount - secondary won amount. Bonus and progressive wins are not eligible for double ups. The meter model does not support the doubling up of bonus or progressive wins. Page 224 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.25.3.2 Wager Category Meters Some paytables vary the theoretical hold of the EGM based on the wager. These variants are identified as wager categories. When such features are employed, the EGM MUST maintain the total amount wagered, number of games played, and un-weighted payback percentage meters for each distinct wager category. Actual payback percentages are used, as the wager category meters record play at each of the distinct hold percentages available within the game play device. Wager category meters can only be queried at the game play device level. Since wager categories represent a breakdown in wagers made at different hold percentages within a single paytable, they lose meaning when rolled up to the class level. If an EGM does not employ wager categories, the meter values reported by the wager category group will be the same as the meter values reported by the performance group. In such cases, the EGM MUST still support queries against the wager category meters. For convenience, the EGM may simply report the meter values from the performance group using the paytableId as the wager category. Table 5.29 Wager Category Meters Enumeration Description G2S_wageredAmt Amount wagered on the EGM for this game play device at this wager category. G2S_playedCnt Total count of games played on the EGM for this game at this wager category. G2S_paybackPct Actual theoretical payback percentage for this wager category, with two implied decimal places. For example, an 88.65% payback is expressed as 8865. 5.25.3.3 Game Denomination Meters Game Denomination meters can be queried by game play device or class. Each game play device must contain at least one game denomination category, but the manufacturer may choose to provide simple game performance reporting at the denomination level for multiple denominations within a single game play device, and so would use these meters for that purpose. For class level meters, there must be one class level meter for every game denomination reported within the set of all game play devices. When reporting denomination within the game play device, the EGM MUST maintain the total amount wagered, number of games played, and weighted average payback percentage meters to record the activity for each distinct game denomination If an EGM reports only a single denomination for the game play device, the meter values reported in the game denomination group will be the same as the meter values reported by the performance group. In such cases, the EGM MUST still support queries against the game denomination meters for all game play devices. For convenience, the EGM may simply report the meter values from the performance group using the minor unit of the base currency as the denomId. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 225 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 Table 5.30 Game Denomination Meters Enumeration Description G2S_wageredAmt Amount wagered on the EGM for this game at this denomination. G2S_playedCnt Total count of games played on the EGM for this game at this denomination. G2S_avgPaybackPct Weighted theoretical payback percentage for games played on this game at this denomination, with two implied decimal places. For example, an 88.65% payback is expressed as 8865. G2S_theoPaybackAmt Theoretical payback amount. Incremented by the amount wagered times the payback percentage of the wager category played. 5.25.3.4 Transfer In Meters Transfer meters are associated with the device class and the specific device making the transfers. Thus, transfer meters can be queried in total by the class level meter, or by individual deviceId. Devices making transfers into an EGM include the devices in the progressive, bonus, and wat classes. Table 5.31 Transfer In Meters Enumeration Description G2S_cashableInAmt Value of cashable credits transferred in. G2S_promoInAmt Value of promo credits transferred in. G2S_nonCashInAmt Value of non-cashable credits transferred in. G2S_transferInCnt Count of transfers in. 5.25.3.5 Transfer Out Meters Transfer meters are associated with the device class and the specific device making the transfers. Transfer meters can be queried in total by the class level meter, or by individual deviceId. Devices making transfers from an EGM include the devices in the handpay, and wat classes. Table 5.32 Transfer Out Meters Enumeration Description G2S_cashableOutAmt Value of cashable credits transferred out. G2S_promoOutAmt Value of promo credits transferred out. G2S_nonCashOutAmt Value of non-cashable credits transferred out. G2S_transferOutCnt Count of transfers out. Page 226 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.25.3.6 Voucher Meters Voucher meters are associated with the device class and the specific device making the transfers. They can be queried in total by the class level meter, or by individual deviceId. To accommodate jurisdictions where the voucher expense is taken at the time of redemption, system-issued vouchers (which have no corresponding deduction) are metered separately from EGM-issued vouchers which do. The system indicates the source of the voucher to the EGM in the authorizeVoucher command. In jurisdictions where this is not an issue, all voucherIn amounts should be posted to the first set of voucherIn meters. Table 5.33 Voucher Meters Enumeration Description G2S_cashableInAmt Value of cashable credits transferred in. G2S_cashableInCnt Count of cashable credits transferred in. G2S_promoInAmt Value of promo credits transferred in. G2S_promoInCnt Count of promo credits transferred in. G2S_nonCashInAmt Value of non-cashable credits transferred in. G2S_nonCashInCnt Count of non-cashable credits transferred in. G2S_cashableSysInAmt Value of cashable credits from redeemed system created vouchers. G2S_cashableSysInCnt Count of redeemed system created cashable credit vouchers. G2S_promoSysInAmt Value of promo credits from redeemed system created vouchers. G2S_promoSysInCnt Count of redeemed system created promo credit vouchers. G2S_nonCashSysInAmt Value of non-cashable credits from redeemed system created vouchers. G2S_nonCashSysInCnt Count of redeemed system created non-cashable credit vouchers. G2S_cashableOutAmt Value of cashable credits transferred out. G2S_cashableOutCnt Count of cashable credit vouchers issued. G2S_promoOutAmt Value of promo credits transferred out. G2S_promoOutCnt Count of promo credit vouchers issued. G2S_nonCashOutAmt Value of non-cashable credits transferred out. G2S_nonCashOutCnt Count of non-cashable credit vouchers issued. 5.25.3.7 Progressive Meters Progressive meters are associated with the progressive class and each progressive device, and so can be queried in total (class level meter) or by individual deviceId. Table 5.34 Progressive Meters Enumeration Description G2S_wageredAmt Money wagered on all game play devices that contribute to the progressive device. G2S_playedCnt Count of games played on all game play devices that contribute to the progressive device. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 227 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.25.3.8 Currency Meters Currency meters are the meters associated with the currency classes: coinAcceptor, hopper, noteAcceptor, and noteDispenser. If a host requests the deviceMeters for one of these devices, it gets the totals for the device. If a host requests currencyMeters for a device, it receives the breakdown by currency type. As the currency devices either move credits onto the EGM (noteAcceptor and coinAcceptor) or off of the EGM (hopper and noteDispenser), the currency meters are divided into currency in meters and currency out meters. One set will be associated with each device/class. The currency in meters account for currency accepted by the EGM, and then indicate whether the currency went to the dispenser or to the drop. A drop door opened counter is included with the device meters so that the currency meter set can be included with currency drop door open events. Table 5.35 Currency In Meters Enumeration Description G2S_currencyInAmt Value of currency accepted by the EGM. G2S_currencyInCnt Count of currency accepted by the EGM. G2S_currencyToDropAmt Value of currency diverted to the drop box or note stacker. G2S_currencyToDropCnt Count of currency diverted to the drop box or note stacker. G2S_currencyToDispAmt Value of currency diverted to the hopper or note dispenser. G2S_currencyToDispCnt Count of currency diverted to the hopper or note dispenser. G2S_dropDoorOpenCnt Count of drop door opens for this currency device. The currency out meters account for currency dispensed from the EGM. A dispenser door opened counter is included with the device meters so that the currency out meter set can be included with currency dispenser door open events. Table 5.36 Currency Out Meters Enumeration Description G2S_currencyOutAmt Value of currency dispensed by the EGM. G2S_currencyOutCnt Count of currency dispensed by the EGM. G2S_dispDoorOpenCnt Count of dispenser door opens for this currency device 5.25.3.9 Cabinet Meters The cabinet meters are the deviceMeters for the cabinet class. These meters contain the current credit meters and cabinet door open counts, along with a variety of performance and win meters that are accumulated at the cabinet level, rather than for every game play device. Table 5.37 Cabinet Meters (Sheet 1 of 2) Enumeration Description G2S_playerCashableAmt Value of cashable credit meter. G2S_playerPromoAmt Value of promo credit meter. G2S_playerNonCashAmt Value of non-cashable credit meter. G2S_wageredCashableAmt Cashable credits wagered on the EGM. Page 228 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 5 meters Class G2S™ Message Protocol v1.0.3 Table 5.37 Cabinet Meters (Sheet 2 of 2) Enumeration Description G2S_wageredPromoAmt Cashable promotional credits wagered on the EGM. G2S_wageredNonCashAmt Non-cashable credits wagered on the EGM. G2S_cardedWageredNonCashAmt Non-cashable credits wagered on the EGM while player card was present. G2S_cardedWageredCashableAmt Cashable credits wagered on the EGM while player card was present. G2S_cardedWageredPromoAmt Cashable promotional credits wagered on the EGM while player card was present. G2S_egmPaidGameWonAmt Total EGM paid base paytable win from game play. G2S_handPaidGameWonAmt Total hand paid base paytable win from game play. G2S_cardedGameWonAmt Total base paytable win from game play (EGM paid and hand paid) while player card was present. G2S_egmPaidProgWonAmt Total EGM paid progressive win. G2S_handPaidProgWonAmt Total hand paid progressive win. G2S_cardedProgWonAmt Total progressive win (EGM paid and hand paid) while player card was present. G2S_egmPaidBonusWonAmt Total EGM paid external bonus awards transferred as win (creditType = "G2S_cashable"). G2S_handPaidBonusWonAmt Total hand paid external bonus awards transferred as win (creditType = "G2S_cashable"). G2S_egmPaidBonusNonWonAmt Total EGM paid non-win external bonus awards (creditType = "G2S_promo" or creditType ="G2S_nonCash"). G2S_handPaidBonusNonWonAmt Total hand paid non-win external bonus awards (creditType = "G2S_promo" or creditType = "G2S_nonCash"). G2S_cardedBonusWonAmt Total G2S_cashable external bonus awards (EGM paid and hand paid) while player card was present. G2S_cardedBonusNonWonAmt Total G2S_promo and G2S_nonCash external bonus awards (EGM paid and hand paid) while player card was present. G2S_egmDispensedCashableAmt Total cashable credits paid out via currency by the EGM. G2S_egmDispensedPromoAmt Total cashable promotional credits paid out via currency by the EGM. G2S_egmDispensedNonCashAmt Total non-cashable credits paid out via currency by the EGM. G2S_handPaidCancelAmt Total handpaid cancel credits (all fund types). G2S_cardedPlayedCnt Number of games played while player card was inserted. G2S_gamesSinceInitCnt Number of games since initialization. G2S_gamesSincePowerResetCnt Number of games since the last power up. G2S_gamesSinceDoorClosedCnt Number of games since the last cabinet door closed. G2S_logicDoorOpenCnt Number of logic door opens. G2S_auxDoorOpenCnt Number of auxiliary door opens. G2S_cabinetDoorOpenCnt Number of cabinet door opens. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 229 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.26 Error Codes The following table lists the error codes specific to the meters class: Table 5.38 meters Class Error Codes Error Code Suggested Error Text G2S_MTX001 Invalid meterSubType Specified G2S_MTX002 Invalid Periodic Meter Values Page 230 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 5.27 Chapter 5 meters Class Event Codes The following table summarizes the events that may be generated by devices within the meters class. NOTE: No device, meter, or log state changes are associated with meters class events. A full description of each event follows the table. Table 5.39 meters Class Event Codes Event Code and Description G2S_MTE100 Meter Subscription Set G2S_MTE101 Meter Subscription Cleared 5.27.1 G2S_MTE100 Meter Subscription Set This event is sent by the EGM when a host’s meter subscription is set as a result of a setMeterSub command. Table 5.40 G2S_MTE001 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands Prior to generating this event, the EGM MUST generate a meterSubList command for the host that owns the meter device. 5.27.2 G2S_MTE101 Meter Subscription Cleared This event is sent by the EGM when a host’s meter subscription is cleared as a result of a clearMeterSub command. Table 5.41 G2S_MTE002 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands Prior to generating this event, the EGM MUST generate a meterSubList command for the host that owns the meter device. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 231 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.28 Examples 5.28.1 Get Meter Info Command Sequence EGM HOST getMeterInfo meterInfo 5.28.1.1 getMeterInfo: Host to EGM, Requesting Class Level Performance Meters The following example highlights the construction of a getMeterInfo command sent from a host system to an EGM to request class level (EGM life-to-date) performance meters: <meters deviceId = "2" dateTime = "2004-03-07T15:20:27.321-05:00" commandId = "2003" sessionId = "1003" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <getMeterInfo> <getDeviceMeters deviceClass = "G2S_gamePlay" deviceId = "0" /> </getMeterInfo> </meters> Page 232 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 5.28.1.2 Chapter 5 meters Class meterInfo: EGM Response to Host getMeterInfo The following example highlights the construction of a meterInfo command sent from an EGM to a host system in response to the command above. Because this EGM has no secondary game support, those meters are omitted, and are assumed to be 0 (zero) by the receiving host. <meters deviceId = "2" dateTime = "2004-03-07T15:20:27.432-05:00" commandId = "3003" sessionId = "1003" sessionType = "G2S_response" > <meterInfo meterInfoType = "G2S_onDemand" meterDateTime = "2004-03-07T15:20:27.432-05:00" > <deviceMeters deviceClass = "G2S_gamePlay" deviceId = "0" >" > <simpleMeter meterName = "G2S_wageredAmt" meterValue = "123456000" > <simpleMeter meterName = "G2S_egmPaidGameWonAmt" meterValue = "50000000" /> <simpleMeter meterName = "G2S_handPaidGameWonAmt" meterValue = "0" /> <simpleMeter meterName = "G2S_egmPaidProgWonAmt" meterValue = "0" /> <simpleMeter meterName = "G2S_handPaidProgWonAmt" meterValue = "0" /> <simpleMeter meterName = "G2S_wonCnt" meterValue = "250" /> <simpleMeter meterName = "G2S_lostCnt" meterValue = "1023" /> <simpleMeter meterName = "G2S_tiedCnt" meterValue = "2" /> <simpleMeter meterName = "G2S_failedCnt" meterValue = "0" /> <simpleMeter meterName = "G2S_avgPaybackPct" meterValue = "9275" /> </deviceMeters> </meterInfo> </meters> 5.28.1.3 getMeterInfo: Host to EGM, Requesting Device Meters The following example highlights the construction of a getMeterInfo command sent from a host system to an EGM to request device meters for the note acceptor, and then the associated response: <meters deviceId = "2" dateTime = "2004-03-07T15:20:27.321-05:00" commandId = "2004" sessionId = "1004" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <getMeterInfo> <getDeviceMeters deviceClass = "G2S_noteAcceptor" deviceId = "1" /> </getMeterInfo> </meters> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 233 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.28.1.4 meterInfo: EGM to Host, Device Meters The following example highlights the construction of a meterInfo command sent from an EGM to a host system in response to the command above: <meters deviceId = "2" dateTime = "2004-03-07T15:20:27.432-05:00" commandId = "3004" sessionId = "1004" sessionType = "G2S_response" > <meterInfo meterInfoType = "G2S_onDemand" meterDateTime = "2004-03-07T15:20:27.432-05:00" > <deviceMeters deviceClass = "G2S_noteAcceptor" deviceId = "1" > <simpleMeter meterName = "G2S_currencyInAmt" meterValue = "64000000" /> <simpleMeter meterName = "G2S_currencyInCnt" meterValue = "14" /> <simpleMeter meterName = "G2S_currencyToDropAmt" meterValue = "64000000" /> <simpleMeter meterName = "G2S_currencyToDropCnt" meterValue = "14" /> <simpleMeter meterName = "G2S_dropDoorOpenCnt" meterValue = "2" /> </deviceMeters> </meterInfo> </meters> 5.28.1.5 getMeterInfo: Host to EGM, Requesting Currency Meters The following example highlights the construction of a getMeterInfo command sent from a host system to the same EGM as in the above example, this time requesting currency meters for the note acceptor, and then the associated response: <meters deviceId = "2" dateTime = "2004-03-07T15:20:27.321-05:00" commandId = "2005" sessionId = "1005" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <getMeterInfo> <getCurrencyMeters deviceClass = "G2S_noteAcceptor" deviceId = "1" /> </getMeterInfo> </meters> Page 234 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 5.28.1.6 Chapter 5 meters Class meterInfo: EGM to Host, Currency Meters The following example highlights the construction of a meterInfo command sent from an EGM to a host system in response to the command above, assuming the note acceptor has no dispenser: <meters deviceId = "2" dateTime = "2004-03-07T15:20:27.432-05:00" commandId = "3005" sessionId = "1005" sessionType = "G2S_response" > <meterInfo meterInfoType = "G2S_onDemand" meterDateTime = "2004-03-07T15:20:27.432-05:00" > <currencyMeters deviceClass = "G2S_noteAcceptor" deviceId = "1" currencyType = "G2S_note" currencyId = "USD" denomId = "10000000" > <simpleMeter meterName = "G2S_currencyInAmt" meterValue = "50000000" /> <simpleMeter meterName = "G2S_currencyInCnt" meterValue = "5" /> <simpleMeter meterName = "G2S_currencyToDropAmt" meterValue = "50000000" /> <simpleMeter meterName = "G2S_currencyToDropCnt" meterValue = "5" /> </currencyMeters> <currencyMeters deviceClass = "G2S_noteAcceptor" deviceId = "1" currencyType = "G2S_note" currencyId = "USD" denomId = "2000000" > <simpleMeter meterName = "G2S_currencyInAmt" meterValue = "10000000" /> <simpleMeter meterName = "G2S_currencyInCnt" meterValue = "5" /> <simpleMeter meterName = "G2S_currencyToDropAmt" meterValue = "10000000" /> <simpleMeter meterName = "G2S_currencyToDropCnt" meterValue = "5" /> </currencyMeters> <currencyMeters deviceClass = "G2S_noteAcceptor" deviceId = "1" currencyType = "G2S_note" currencyId = "USD" denomId = "1000000" > <simpleMeter meterName = "G2S_currencyInAmt" meterValue = "4000000" /> <simpleMeter meterName = "G2S_currencyInCnt" meterValue = "4" /> <simpleMeter meterName = "G2S_currencyToDropAmt" meterValue = "4000000" /> <simpleMeter meterName = "G2S_currencyToDropCnt" meterValue = "4" /> </currencyMeters> </meterInfo> </meters> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 235 Chapter 5 meters Class G2S™ Message Protocol v1.0.3 5.28.2 Meter Subscription Command Sequences HOST 5.28.2.1 EGM HOST EGM HOST EGM setMeterSub getMeterSub clearMeterSub meterSubList meterSubList meterSubList setMeterSub: Host to EGM, Requesting Subscription to Meters The following example highlights the construction of a setMeterSub command sent from a host system to an EGM to request periodic meters every 15 minutes (900,000 milliseconds) starting at 5 minutes (300,000 milliseconds) after midnight. In this example, the host is requesting game play device class meters (performance meters), cabinet meters, and note acceptor and dispenser currency meters (broken down by currency, rather than just total notes in (which would be getDeviceMeters)): <meters deviceId = "7" dateTime = "2004-03-07T15:20:27.321-05:00" commandId = "2002" sessionId = "1002" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <setMeterSub meterSubType = "G2S_onPeriodic" periodicInterval = "900000" periodicBase = "300000" > <getDeviceMeters deviceClass = "G2S_gamePlay" deviceId = "0" /> <getDeviceMeters deviceClass = "G2S_cabinet" deviceId = "0" /> <getCurrencyMeters deviceClass = "G2S_noteAcceptor" deviceId = "0" /> <getCurrencyMeters deviceClass = "G2S_noteDispenser" deviceId = "0" /> </setmeterSub> </meters> 5.28.2.2 getMeterSub: Host to EGM, Requesting Meter Subscription List The following example highlights the construction of a getMeterSub command sent from a host system to an EGM to request a listing of the current G2S_onPeriodic meter subscription for this host. <meters deviceId = "7" dateTime = "2004-03-07T15:20:27.321-05:00" commandId = "2001" sessionId = "1001" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <getMeterSub meterSubType = "G2S_onPeriodic" / > </meters> Page 236 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 5.28.2.3 Chapter 5 meters Class meterSubList: EGM to Host, Meter Subscription Details The following example highlights the construction of the meterSubList command sent from an EGM to a host system in response to the command above: <meters deviceId = "7" dateTime = "2004-03-07T15:20:27.321-05:00" commandId = "3001" sessionId = "1001" sessionType = "G2S_response" timeToLive = "30000" sessionRetry = "0" > <meterSubList meterSubType = "G2S_onPeriodic" periodicInterval = "900000" periodicBase = "300000" > <getDeviceMeters deviceClass = "G2S_gamePlay" deviceId = "0" /> <getDeviceMeters deviceClass = "G2S_cabinet" deviceId = "0" /> <getCurrencyMeters deviceClass = "G2S_noteAcceptor" deviceId = "0" /> <getCurrencyMeters deviceClass = "G2S_noteDispenser" deviceId = "0" /> </meterSubList> </meters> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 237 G2S™ Message Protocol v1.0.3 Page 238 Chapter 5 meters Class gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6 gamePlay Class 6.1 Introduction The gamePlay class includes commands and events related to the games available on an EGM. The class provides a means to discover the capabilities of each game play device as well as control which game play devices and the associated game combos (defined below) are available, thus allowing a player to select them. The class provides commands to determine the state of game play devices and obtain a game recall log of current and previous games. The gamePlay class is a multi-device class. deviceId play device is assigned its own unique deviceId. 6.2 0 is reserved for class level meters and logs. Each game Themes, Paytables, and Denominations The G2S protocol associates three primary attributes with each game offered by an EGM: Theme: theme of the game, such as red-white-blue, super sevens, and so on. A game play device MUST include only one theme. Paytable: algorithms used to determine the payouts from the game. A game play device MUST include only one paytable, and the paytable MUST include at least one wager category. Denomination: value of each credit wagered as part of the game. A game play device MUST include at least one denomination. 6.2.1 Game Combinations (Game Combos) The definition of a game combination, often referred to as a game combo, is the joining of one theme, one paytable, and one denomination to result in a game that may be accessible to a player. A game combination that is accessible to a player is an available game combination; a game combination that is temporarily inaccessible to a player is an inactive game combination. Within a game play device, the only difference between any two game combinations is the different denomination associated with each combination. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 239 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.2.2 Denominations Denominations are referenced in many different sections within the G2S protocol. For the purpose of illustrating the various contexts of denominations, assume there is a set of denominations that correspond to superset of all denominations referenced within the EGM. This is the egm.denomList set. Given this superset, there are four important denominations contexts within the EGM’s egm.denomList: • A single denomination associated with the EGM (cabinet.reportDenomId). • The set of denominations contained within the game denomination meter group of a meter class (meter.gameDenomList). • The set of denominations contained within a game play device (gamePlay.denomList). • A single denomination associated with a game combination (gameCombo.denomId). The following statements illustrate the relationships between the denomination contexts: meter.gameDenomList ⊆ egm.denomList cabinet.reportDenomId ∈ egm.denomList gameCombo.denomId ∈ gamePlay.denomList ⊆ egm.denomList NOTE: Some common set notation symbols: A⊆ B The set ‘A’ is a subset of set ‘B’ or is equal to set ‘B’. a∈ B The item ‘a’ is an element of set ‘B’. A game play device MUST have one or more denominations in its gameDenomList; however, it is possible that all of the denominations in the gameDenomList are inactive. This may occur under different scenarios, for example when the game play device is first created (instantiated). A game play device with 0 (zero) active denominations MUST not be playable. 6.2.3 Paytables and Wager Categories A word about paytables and wager categories: some paytables vary the theoretical payback percentage of the game based upon wager. These variants are identified as wager categories. The following table illustrates how a single paytable may contain two wager categories with different theoretical payback percentages: Table 6.1 Paytable With Two Wager Categories Paytable Wager Categories Credits Wagered Theoretical Payback % Wager Category A 1 ... 4 90.0% Wager Category B 5 94.0% Within the G2S protocol, a game play device consists of a theme, paytable, and a list of denominations. Within a paytable, at least one wager category MUST be included. A game play device may be subdivided into a game combo by representing the combo as a theme, paytable, and a single denomination selected from the list of denominations for the game play device. So the following rules apply: Table 6.2 Game Play Device and Game Combo Rules Parameter Game Play Device Rules Game Combo Rules Themes Only 1 (Themes = 1) Only 1 (Themes = 1) Paytables Only 1 (Paytables = 1) Only 1 (Paytables = 1) Denominations At least 1 (Denoms 1) Only 1 (Denoms = 1) Page 240 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 6 gamePlay Class The conclusion is that a game combo must be a subset of a game play device such that: gameCombo.themeId = gamePlay.themeId gameCombo.paytableId = gamePlay.paytableId gameCombo.denomId ∈ gamePlay.gameDenomList Furthermore, the fact that an EGM supports a specific theme does not necessarily mean that the theme can be used in combination with all the paytables and denominations supported by the EGM. An EGM may only support specific combinations of theme, paytable, and denomination; not necessarily every possible combination. Theme and paytable identifiers must follow G2S naming conventions for unique identifiers (see Section 1.11). Such identifiers are prefixed by one of the manufacturer’s GSA-assigned prefixes followed by the underscore character. Denominations are expressed in 1/1000ths of the minor unit of the EGM base currency. For example, if the base currency is United States Dollars, then the denominations would be expressed as millicents. Typically, depending on the EGM base currency, there is an implied decimal place to convert from the minor unit to the major unit of the currency (see Chapter 5, meters Class for more information). 6.2.4 Game Play Device Collisions There is a condition where two or more game play devices may overlap each other with respect to theme and denomination or theme, paytable and denomination. This is a condition where the EGM would enable two or more games that have the same theme and active denomination (regardless of paytable). This condition may cause some confusion to the player because the same game may appear multiple times on the game selection screen of the EGM. This scenario defines a game play device collision. An EGM manufacturer may choose to prevent game play device collisions. If specific conditions require it, the EGM MAY reject G2S commands (such as the setGamePlayState and setActiveDenoms commands) that would lead to a game play device collision and generate the error code G2S_GPX002. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 241 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.3 Denomination Ranges Denominations are primarily represented by a denomination identifier (denomId), and lists of denominations may consist of a series of denomIds; however these lists may become large and unwieldy. To address this issue, there is a shorthand method of specifying a range of denomination identifiers as a denomRange. The denomination range can substitute for a series of denomIds that increase at a constant interval by specifying the minimum denomId, the maximum denomId, and an optional interval for the series. For example, if we use the default interval of 1000 for the range then: {denomId(1000), denomId(2000), denomId(3000), denomId(4000), denomId(5000)} = 5000) denomRange(1000, The denomRange can substitute for a series of denomIds in all cases where a list of denomIds can be used. For example, the following two lists are equivalent: {denomId(1000), denomId(2000), denomId(3000), denomId(4000), denomId(5000), denomId(10000), denomId(25000)} {denomRange(1000, 5000), denomId(10000), denomId(25000)} Referencing individual denominations from a denomination range is allowed. This provides a means to single out specific denominations for specifying game combos. Addressing the individual denominations from a range is no different from addressing the same denominations from a list of denomination identifiers. For example, using the following denomination list: {denomRange(1000, 5000), denomId(10000), denomId(25000)} We are permitted to select individual denomination identifiers as follows: {denomId(1000), denomId(2000), denomId(5000), denomId(10000)} Page 242 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.4 playState Transitions The gamePlay class will indicate the state of the game play activity using the playState value. This state value has a defined state transition sequence that will accommodate all game play activity. The following diagram illustrates the playState transitions: Primary game failed gameEnded Primary game started Game ended Wager Changed primaryGameStarted handpayPending progressivePending gameDelayStarted Primary game ended Game delay started primaryGameEnded Secondary game started Secondary game failed secondaryGameEnded secondaryGameStarted Secondary game ended Branch/Merge: One activity occurs depending upon conditions Figure 6.1 playState State Transition Diagram A host may determine the status of the current game play activity by requesting the most recent gamePlay recallLog. The EGM will respond with a recallLogList that includes the most recent gamePlay log that contains the current gamePlay playState value. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 243 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.4.1 gameIdle State The game is not in play (not in a game-cycle), player input is enabled, player may leave the game and browse the various games available on the EGM. Bonus awards MAY be paid while in the gameIdle state. Based upon the EGM design, the player may adjust some game parameters such as lines bet or keno marks, without initiating a game-cycle. The transition from gameIdle state may lead to the primaryGameEscrow state for central determinant games or to the primaryGameStarted state for conventional games. Either of these transitions will initiate a gamecycle. 6.4.2 primaryGameEscrow State This state only applies when a central determinant game is being played. It indicates that the player has started a primary game-cycle with a wager; however the wager is in escrow and has NOT been committed yet. This state will remain until either the central determination logic has provided a valid primary game outcome, or when the central determination logic has failed to obtain a valid primary game outcome. The transition from the primaryGameEscrow state will lead to the primaryGameStarted state if the central determinant logic provided a valid primary game outcome. Alternatively, if the central determinant logic failed to provide a valid primary game outcome, then the game-cycle is terminated and the state will transition to the gameIdle state. 6.4.3 primaryGameStarted State This state indicates that a primary game-cycle has been started by the player and the initial wager has been committed to the accounting meters. This state also indicates that the ‘primary-game-cycle’ can not be aborted. Some game types may permit additional wagers (blackjack double-down, insurance, split, etc.) while in the primary game cycle, therefore additional wager changes may be committed to the accounting meters while in this state. The transition from the primaryGameStarted state may lead to either the progressivePending state, the secondaryGameChoice state, the payGameResults state, or the gameEnded state. 6.4.4 progressivePending State This state only applies when a game hits one or more progressive wins. The game play device uses this state to suspend when waiting for the progressive logic to provide a winning value. The transition from the progressivePending state typically will post the G2S_GPE105 Primary Game Ended event and bypass the secondaryGameChoice state because progressive wins are not permitted to be applied to secondary games; this will lead to either the payGameResults state or the gameEnded state. Alternatively, the transition may return to the primaryGameStarted state if remaining spins/plays exist within a multiple spin/ play game type. 6.4.5 secondaryGameChoice State This state allows the player to select whether they want to risk their primary game winnings in a secondary game, such as double-or-nothing. This state only applies when an EGM is capable and configured for secondary games and the primary game results in a win that does not include any progressive awards. Bonus awards MAY be paid while in the secondaryGameChoice state. The transition from the secondaryGameChoice state will lead to the secondaryGameStart state if the player chose to play a secondary game; however, if the game is operating with central determination, then the transition will lead to the secondaryGameEscrow state. Alternatively, if the player chose not to play a secondary game, then the transition will lead to either the payGameResults state or the gameEnded state. Page 244 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 6.4.6 Chapter 6 gamePlay Class secondaryGameEscrow State This state only applies when a central determinant game is being played. It indicates that the player has requested to start a secondary game with a wager; however the wager is in escrow and has NOT been committed at this state. This state will remain until either the central determination logic has provided a valid secondary game outcome, or when the central determination logic has failed to provide a valid secondary game outcome. The transition from the secondaryGameEscrow state will lead to the secondaryGameStarted state when the central determination logic has provided a valid secondary outcome. Alternatively, the transition MAY lead to the secondaryGameChoice state if the central determination logic failed to provide a valid secondary game outcome. The secondary game failure may have alternative implementations where the failure MAY cause the game play device to decline the secondary game choice and transition to the payGameResults state. 6.4.7 secondaryGameStarted State This state indicates that a secondary game has been selected by the player and the secondary wager has been committed to the accounting meters. This state also indicates that the game play device is in the ‘secondarygame-cycle’ and can not be aborted. The transition from the secondaryGameStarted state may lead to the secondaryGameChoice state if the current secondary game resulted in a win and other conditions permit another secondary game, otherwise the transition will lead to either the payGameResults state or the gameEnded state – depending on the current secondary game results. 6.4.8 payGameResults State This state indicates the final win for the game cycle has been determined and payment is in progress. The game will remain in the payGameResults states until all payments have completed. This state also indicates that the primary game and any secondary games associated with this game cycle have concluded. The transition from the payGameResults state always leads to the gameEnded state. 6.4.9 gameEnded State This state indicates the results for the game cycle has been determined any winnings have been paid, thus ending the game-cycle. While in the gameEnded state, no player input will be accepted. This state provides a ‘delay’ before returning input to the player. Bonus awards MAY be paid while in the gameEnded state. The gameEnded state will always transition to the gameIdle state when the programmed game delay timer has expired. It is possible that a game delay timer may not be in effect or has already expired before transitioning into the gameEnded state, and thus the transition to the gameIdle state may occur instantly. See the setGameDelay command in the bonus class for details on the game delay timer. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 245 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.5 Secondary Games Many EGMs support a secondary game feature where the winnings resulting from the primary game can be wagered and won or lost in a secondary game. For example: the primary game winnings can be risked in a ‘double-or-nothing’ secondary game feature. It may also be possible to complete the secondary game feature and re-enter it, effectively wagering the winnings resulting from the previous secondary game feature. NOTE: Any primary game result that contains one or more progressive win amounts MUST not be allowed to advance to a secondary game. Figure 6.1 illustrates this by showing that all primary game progressive activity bypasses the secondary game states. 6.6 Game Play Device Associations A game play device is associated with a list of game combos. Those game combos share a single set of configuration options and a single set of performance meters, wager category meters and denomination meters. In other words, the configuration for a game play device applies to all game combinations within that device. Similarly, only one set of performance meters exists for a game play device, so game play activity from all game combinations contained within a device will affect the same performance meters associated with the game play device. Likewise, the wager category meters are shared across game combinations within a game play device. NOTE: the denomination meters for a game play device are not shared across game combinations within that device because each game combination has a unique denomination associated with it. Furthermore, it is not required that an EGM provide individual gameDenom meters for each available denomination. A host may interrogate the meter class for game denomination meter group of the game play device to discover the EGM’s denomination metering support. 6.7 gamePlay Class Associations Every game play device shares specific information with the gamePlay class. The gamePlay class contains a single instance of the game recall transaction log, which is shared by all game play devices. This game recall log is considered to belong to deviceId = 0. A host may issue a getRecallLogStatus or getRecallLog command to any game play deviceId that is contained in the descriptorList, and the response will be constructed as if the request was issued to deviceId = 0. No special filtering is performed if the commands are directed to a non-zero gamePlay deviceId, the recallLogStatus and recallLogList may contain records corresponding to several gamePlay deviceIds. Additionally, a single instance of life-to-date performance meters are maintained at the class level. These meters reflect all gamePlay activity for game play devices, including both current devices and removed devices. Page 246 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.8 Request-Response Pairs The following table organizes the commands contained within the gamePlay class into request-response pairs. NOTE: In the gamePlay class, there are no commands that are originated by the EGM.: Table 6.3 Commands Originated by Host Request Response Owner Guest setGamePlayState gamePlayStatus Yes No getGamePlayStatus gamePlayStatus Yes Yes getGamePlayProfile gamePlayProfile Yes Yes setActiveDenoms gameDenomList Yes No getGameDenoms gameDenomList Yes Yes getRecallLogStatus recallLogStatus Yes Yes getRecallLog recallLogList Yes Yes gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 247 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.9 setGamePlayState Command This command is used by a host to enable or disable the game play device. Disabling the game play device prevents the device from being active or available to a player. Only the owner of the device can execute this command. A gamePlayStatus command is sent in response to a setGamePlayState command. The game play device will set the hostEnabled attribute to true when the setGamePlayState command is received with the enable attribute set to true. The hostEnabled attribute is set independently of the egmEnabled attribute, hence the host may request a game play device be enabled, yet the device may not be enabled because the EGM conditions prohibit it. Jurisdictional regulations and operator preferences will dictate when this command can be applied by the EGM. Changing the accessible game play devices on an EGM while the EGM is being played will probably not be permitted in most jurisdictions. The proper response in this case is a gamePlayStatus command with the egmEnabled attribute set to false and the hostEnabled attribute set to true. One reason the egmEnabled attribute may be set to false is that the game play device does not currently have any active denominations. A host may determine if denominations are active before or after attempting to enable the device by monitoring game play events or by using the getGameDenoms command. For example, an EGM may apply the following logic when executing the setGamePlayState command: 1. Wait for credit meter to reach 0 (zero). 2. Wait for the EGM to be idle according to the idleTimePeriod parameter configured in the cabinet class. 3. Apply the setGamePlayState command to affect the gamePlayStatus.hostEnabled attribute. 4. Generate event G2S_GPE003 Device Disabled by depending upon the hostEnabled attribute value. Host or G2S_GPE004 Device Enabled by Host, NOTE: An EGM is considered inactive if there is no activity at the coin acceptor, note acceptor, touch screen, buttons, or other player-interface devices. If there is activity at the EGM while the EGM is waiting to apply the setGamePlayState command, the EGM MUST restart the sequence, which in the example above is to wait for the credit meter to reach 0 (zero) and then wait for the EGM idle period. Table 6.4 setGamePlayState Attributes Attribute Restrictions Description enable type: boolean use: optional default: true Indicates whether the game play device should be enabled or disabled. true = enabled and false = disabled. disableText type: textMessage use: optional default: <empty> Optional message to display while the device is disabled. Page 248 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.10 getGamePlayStatus Command This command is used by a host to request the current status information of the device. The gamePlayStatus command is sent in response to the getGamePlayStatus command. The getGamePlayStatus element contains no additional attributes or elements. 6.11 gamePlayStatus Command This command is used by an EGM to send the current status of the device to a host. The game status includes the theme, paytable, and tilt indicators. The gamePlayStatus command is sent in response to the setGamePlayState and getGamePlayStatus commands. Table 6.5 gamePlayStatus Attributes Attribute Restrictions Description configurationId type: configurationId use: optional default: 0 hostEnabled type: boolean use: optional default: true Indicates whether the device has been enabled by the host. egmEnabled type: boolean use: optional default: true Indicates whether the device has been enabled by the EGM. themeId type: themeId use: required Theme associated with the device. paytableId type: paytableId use: required Paytable associated with the device. generalTilt type: boolean use: optional default: false Indicates whether the device has an undefined malfunction and requires intervention. reelTilt type: boolean use: optional default: false Indicated if one or more of the physical reels associated with the device has a malfunction. Configuration identifier set by the host. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 249 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.12 getGamePlayProfile Command This command is used by a host to request the device profile information. The gamePlayProfile command is sent in response to the getGamePlayProfile command. The getGamePlayProfile element contains no additional attributes or elements. 6.13 gamePlayProfile Command This command is used by an EGM to send the profile of the device to a host. The profile contains the protocol-related configuration options selections for a game play device. The configuration options can be set locally at the EGM or remotely via a configuration server using commands within the optionConfig class. The game play device profile includes the theme, paytable, wager categories, win levels and so on. The gamePlayProfile command is sent in response to the getGamePlayProfile command. By definition, the gamePlayProfile command MUST contain at least one wagerCategoryItem element. Similarly, the gamePlayProfile command MUST contain at least one winLevelItem element. Table 6.6 gamePlayProfile Attributes (Sheet 1 of 2) Attribute Restrictions configurationId * type: configurationId use: optional default: 0 restartStatus * type: boolean use: optional default: true useDefaultConfig * type: boolean use: optional default: false requiredForPlay * type: boolean use: optional default: false minLogEntries Page 250 type: int use: optional minIncl: 1 default: 10 Description Last configuration identifier set by a G2S host; set to 0 (zero) when configuration changes are made by hosts other than G2S hosts. Indicates the state of hostEnabled when the EGM restarts (true = enabled/false = disabled). Indicates whether the default configuration for the device MUST be used when the EGM restarts. Indicates whether the EGM MUST be disabled if either egmEnabled or hostEnabled is set to false. Indicates the minimum number of log entries the EGM must maintain in persistent memory. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.6 gamePlayProfile Attributes (Sheet 2 of 2) Attribute Restrictions Description themeId * type: themeId use: required Theme associated with the device. paytableId * type: paytableId use: required Paytable associated with the device. maxWagerCredits * type: int use: optional minIncl: 1 default: 1 Maximum wager of the device in credits. progAllowed * type: boolean use: optional default: false Indicates whether the game play device can have progressive win levels. secondaryAllowed * type: boolean use: optional default: false Indicates whether the game play device can wager the game winnings through a secondary game, such as double-or-nothing. * type: boolean use: optional default: false Indicates whether the device can support central determinant game outcome. centralAllowed * * Standard configuration option that MUST be included in the standard option configuration group – G2S_gamePlayOptions – for devices within the gamePlay class. Table 6.7 gamePlayProfile Elements Element Restrictions Description wagerCategoryList minOcc: 1 maxOcc: 1 Contains a list of wager categories supported by the device. See Table 6.8 winLevelList minOcc: 1 maxOcc: 1 Contains a win level resulting from game play activity. Table 6.8 wagerCategoryList Elements Element Restrictions Description wagerCategoryItem minOcc: 1 Contains a wager category supported by the device. See Table 6.9. maxOcc: ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 251 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.9 wagerCategory Attributes Attribute Restrictions Description wagerCategory type: wagerCategory use: required Wager category identifier. theoPaybackPct type: meterValue use: required Theoretical payback percentage associated with the wager category. minWagerCredit type: int use: optional minIncl: 1 default: 1 Minimum wager, in credits, associated with the wager category. maxWagerCredit type: int use: optional minIncl: 1 default: 1 Maximum wager, in credits, associated with the wager category. Table 6.10 winLevelList Elements Element Restrictions Description winLevelItem minOcc: 1 Contains a win level corresponding to a potential winning combination of the gamePlay device. See Table 6.11. maxOcc: ∞ Table 6.11 winLevelItem Attributes Attribute Restrictions Description winLevelIndex type: winLevelIndex use: required Unique paytable index for the win level. winLevelCombo type: winLevelCombo use: optional default: <empty> Description of the paytable win level. progressiveAllowed type: boolean use: optional default: false Indicates whether the paytable win level is permitted to be assigned to a progressive. 6.14 getGameDenoms Command This command is used by a host to request a list of game combinations supported by the device. The gameDenomList command is sent in response to the getGameDenoms command. The getGameDenoms element contains no additional attributes or elements. Page 252 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.15 setActiveDenoms Command This command is used by a host to set the list of game combinations that can be played within a device. Only the owner of the device can execute this command. The gameDenomList command is sent in response to the setActiveDenoms command. If the game play device has 0 (zero) active denominations in its gameDenomList, the EGM MUST not allow the game play device to be playable, thus the egmEnabled attribute of the gamePlayStatus command MUST be set to false, which would generate a G2S_GPE001 Device Disabled by EGM event after the G2S_GPE201 Active Denominations Changed event. Alternatively, when the game play device has one or more active denominations in its gameDenomList, the egmEnabled attribute of the gamePlayStatus command MAY only be set to true when all of the EGM's conditions for a playable device have been satisfied. If an error occurs during the execution of the setActiveDenoms command, none of the actions specified in the setActiveDenoms command are applied by the EGM. To avoid errors, it is anticipated that a host will send a getGameDenoms command to an EGM for the supported game combos before attempting to send a setActiveDenoms command. When the setActiveDenoms command is executed, the device’s current game combinations are deactivated and the new list of game combinations is activated. Jurisdictional regulations and operator preferences will dictate when this command can be applied by the EGM. Changing the game combinations that are active on an EGM while the EGM is actively being played will probably not be permitted in most jurisdictions. For example, an EGM may apply the following logic when executing the setActiveDenoms command: 1. Wait for credit meter to reach zero. 2. Wait for the EGM to be idle according to the idleTimePeriod parameter configured in the cabinet class. 3. Disable all game combinations in the game play device, followed by enabling the game combinations specified in the setActiveDenoms command. 4. Generate a G2S_GPE201 Active Denominations Changed. NOTE: An EGM is considered inactive if there is no activity at the coin acceptor, note acceptor, touch screen, buttons, or other player-interface devices. If there is activity at the EGM while the EGM is waiting to apply the setActiveDenoms command, the EGM MUST restart the sequence, which in the example above is to wait for the credit meter to reach zero and then wait for the EGM idle period. Table 6.12 setActiveDenoms Elements Element Restrictions Description activeDenom minOcc: 0 Contains a denomination supported by the device. See Table 6.13. maxOcc: activeRange ∞ minOcc: 0 maxOcc: ∞ Contains a range of denominations supported by the device. See Table 6.14. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 253 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.13 activeDenom Attributes Attribute Restrictions Description denomId type: denomId use: required A denomination supported by the device. Table 6.14 activeRange Attributes Attribute Restrictions Description denomMin type: denomId use: required Minimum value of a denomination range supported by the device. denomMax type: denomId use: required Maximum value of a denomination range supported by the device. denomInterval type: denomId use: optional default: 1000 Interval for denominations between denomMin and denomMax. 6.16 gameDenomList Command This command is used by an EGM to send the list of game combinations supported by the device to a host. The gameDenomList command is sent in response to the getGameDenoms and setActiveDenoms commands. Table 6.15 gameDenomList Elements Element Restrictions Description gameDenom minOcc: 0 Contains a denomination supported by the device. See Table 6.16. maxOcc: gameRange ∞ Contains a range of denominations supported by the device. See Table 6.17. minOcc: 0 maxOcc: ∞ Table 6.16 gameDenom Attributes Attribute Restrictions Description denomId type: denomId use: required A denomination supported by the device. active type: boolean use: required Indicates whether a player can select the game combination associated with this denomination. Page 254 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.17 gameRange Attributes Attribute Restrictions Description denomMin type: denomId use: required Minimum value of a denomination range supported by the game combos within the device. denomMax type: denomId use: required Maximum value of a denomination range supported by the game combos within the device. denomInterval type: denomId use: optional default: 1000 Interval for game combo denominations between denomMin and denomMax. active Indicates whether a player can select the game combination associated with this denomRange. 6.17 type: boolean use: required getRecallLogStatus Command This command is used by a host to request the current status of the class-level transaction log from an EGM. The response includes the sequence number of the last transaction and the total number of transactions in the log. A recallLogStatus command is sent in response to the getRecallLogStatus command The getRecallLogStatus element contains no additional attributes or elements. 6.18 recallLogStatus Command This command is used by an EGM to send the current status of the transaction log to a host. The recallLogStatus command is sent in response to the getRecallLogStatus command. Table 6.18 recallLogStatus Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional default: 0 minIncl: 0 The sequence number of the most recent transaction within the log; 0 (zero) if no records. totalEntries type: int use: optional default: 0 minIncl: 0 The total number of log entries within the log. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 255 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.19 getRecallLog Command This command is used by a host to request the contents of a transaction log from an EGM. Additional information regarding the use of the lastSequence and totalEntries attributes can be found in Chapter 1. The recallLogList command is sent in response to the getRecallLog command. Table 6.19 getRecallLog Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional default: 0 minIncl: 0 The sequence number of the game recall transaction that should be the first entry in the list; if set to 0 (zero), then defaults to the most recent record. totalEntries type: int use: optional default: 0 minIncl: 0 The total number of game recall entries that should be included in the list; if set to 0 (zero), then defaults to all records. 6.20 recallLogList Command This command is used by an EGM to send the contents of the transaction log to a host. The recallLogList command is sent in response to the getRecallLog command. Table 6.20 recallLogList Elements Element Restrictions Description recallLog minOcc: 0 Contains information about a specific transaction. See attributes in Table 6.21 and elements in Table 6.22. maxOcc: ∞ Table 6.21 recallLog Attributes (Sheet 1 of 2) Attribute Restrictions Description logSequence type: logSequence use: required Unique log sequence number assigned by an EGM. deviceId type: deviceId use: required Device identifier of the device that generated the transaction. Page 256 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.21 recallLog Attributes (Sheet 2 of 2) Attribute Restrictions Description transactionId type: transactionId use: required minIncl: 1 Unique transaction identifier assigned by the EGM. gameDateTime type: dateTime use: required Date/time that the log record was last updated. playState type: playStates use: required State of game play. playResult type: playResults use: required Indicates the result of the game when playState = "G2S_gameEnded" or playState = "G2S_gameIdle". playResult MUST be set to G2S_noResult for all other play states. denomId type: denomId use: required Denomination of the game. initialWager type: meterValue use: required Initial amount wagered. finalWager type: meterValue use: required Final amount wagered in the primary game. initialWin type: meterValue use: required Initial win from primary game, including progressive win amounts. secondaryPlayed type: meterValue use: optional default: 0 Count of secondary games played. secondaryWager type: meterValue use: optional default: 0 Total amount wagered during all secondary games played. secondaryWin type: meterValue use: optional default: 0 Total amount won during all secondary games played. finalWin type: meterValue use: required Final amount won at the G2S_gameEnded or G2S_gameIdle states. Table 6.22 recallLog Elements Element Restrictions Description winLevelList minOcc: 0 maxOcc: 1 Contains win level resulting from game play activity. See attributes in Table 6.24 and elements in Table 6.23. gamePlaySourceRef minOcc: 0 Contains information about a progressive transaction. See Table 6.25. maxOcc: ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 257 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.23 winLevelList Elements Element Restrictions Description winLevelItem minOcc: 0 Contains a win level resulting from game play activity. maxOcc: ∞ Table 6.24 winLevelItem Attributes Attribute Restrictions Description winLevelIndex type: winLevelIndex use: required A unique index for the win level. winLevelCombo type: winLevelCombo use: optional default: <empty> A description of the win level. progressiveAllowed type: boolean use: optional default: false Indicates if the win level is permitted to be assigned to a progressive. Table 6.25 gamePlaySourceRef Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class of the progressive transaction. deviceId type: deviceId use: required Device identifier of the progressive transaction. transactionId type: transactionId use: required minIncl: 1 Transaction identifier of the progressive transaction. logSequence type: logSequence use: required Log sequence of the progressive transaction. cashableAmt type: meterValue use: optional default: 0 Cashable amount of the progressive transaction. promoAmt type: meterValue use: optional default: 0 Promotional amount of the progressive transaction. nonCashAmt type: meterValue use: optional default: 0 Non-cashable amount of the progressive transaction. Page 258 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.21 Data Types The following table lists the data types specific to the gamePlay class: Table 6.26 gamePlay Class Data Types Data Type Restrictions Description playStates type: string enumerations: Indicates the play state of the device. See Section 6.21.1 playResults type: string enumerations: See Section 6.21.2 6.21.1 Indicates the result of the game when playState is set to G2S_gameEnded. playResult MUST equal G2S_noResult for all other play states. playStates Enumerations The following table lists the enumerations of the playStates data type: Table 6.27 playStates Enumerations Enumeration Description G2S_gameIdle The game is idle (not in a game-cycle) and awaiting player input. G2S_primaryGameEscrow The player has initiated a central determinant primary game-cycle, but the initial wager has not been committed to the accounting meters. G2S_primaryGameStarted The player is in the primary game-cycle and the initial wager has been committed to the accounting meters. G2S_primaryGameEnded The results for the primary game-cycle have been determined and any winnings have been paid. G2S_progressivePending The game is in the primary game-cycle and is waiting for the progressive logic to provide a win value. G2S_secondaryGameChoice The game is in a game-cycle and is offering the player a secondary game such as double-or-nothing. G2S_secondaryGameEscrow The player has initiated a central determinant secondary game-cycle, but the secondary wager has not been committed to the accounting meters. G2S_secondaryGameStarted The player is in the secondary game-cycle and the secondary wager has been committed to the accounting meters. G2S_secondaryGameEnded The results for the secondary game-cycle have been determined and any winnings have been paid. G2S_payGameResults The game resulted in a win and is in the process of paying the winning value. G2S_gameEnded The game cycle and any payment of wins have concluded, thus ending the game-cycle. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 259 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.21.2 playResults Enumerations The following table lists the enumerations of the playResults data type: Table 6.28 playResults Enumerations Enumeration Description G2S_noResult The game has not yet concluded, hence no result has been determined. G2S_gameFailed The game was unable to reach conclusion and failed. The net result of the game was the wager was returned to the player. Only the gamesPlayed and gamesFailed performance meters are affected. G2S_gameLost The game cycle concluded and the finalWin value was set to 0 (zero). G2S_gameTied The game cycle concluded and the finalWin value was equal to the finalWager value. G2S_gameWon The game cycle concluded and the finalWin was set to a value greater than 0 (zero). The playResults enumerations in the table above are intended to be a superset of all possible game results that may occur for any game type. It is not expected that every game implemented on an EGM will have a possible game outcome corresponding to each enumeration. The EGM manufacturer is responsible for determining which playResults enumerations are applicable to each individual game implemented on the EGM based upon the specific game design. For example, traditional poker and slot games would likely only make use of the enumerations G2S_noResult, and G2S_gameWon. An implementation of a blackjack game or another electronic table game that contains a possible outcome, where the player’s wager is returned to them (i.e. a push outcome in blackjack), would likely make use of the enumerations G2S_noResult, G2S_gameLost, G2S_gameTied, and G2S_gameWon. The G2S_gameFailed enumeration would likely be expected to be implemented in an EGM in which design requires the game outcome to be distributed by a central host. G2S_gameLost, Page 260 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.22 Error Codes The following table lists the error codes specific to the gamePlay class: Table 6.29 gamePlay Class Error Codes Error Code Suggested Error Text G2S_GPX001 Invalid Denomination Specified G2S_GPX002 EGM Does Not Permit Operations That Would Cause A Game Play Device Collision gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 261 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23 Event Codes The following table lists the event codes specific to the gamePlay class and associated log, meter, and status changes for other G2S classes: Table 6.30 gamePlay Class Event Codes (CB = cabinet, GP = gamePlay, JP = handpay, HP = hopper, ND = noteDispenser, PG = progressive, BN = bonus, PR = player, VC = voucher, WT = WAT) Affected Device Logs, Meters, Statuses Event Code and Event Title CB GP G2S_GPE001 Device Disabled by EGM S G2S_GPE002 Device Enabled by EGM S G2S_GPE003 Device Disabled by Host S G2S_GPE004 Device Enabled by Host S G2S_GPE005 Device Configuration Changed by Host S G2S_GPE006 Device Configuration Changed at EGM S G2S_GPE099 Device Tilts Cleared S G2S_GPE101 Primary Game Escrow L G2S_GPE102 Primary Game Failed LM G2S_GPE103 Primary Game Started M LM G2S_GPE104 Wager Changed M LM G2S_GPE105 Primary Game Ended L G2S_GPE106 Secondary Game Choice L G2S_GPE107 Secondary Game Escrow L G2S_GPE108 Secondary Game Failed LM G2S_GPE109 Secondary Game Started LM G2S_GPE110 Secondary Game Ended LM JP HP M M ND PG VC WT M M L G2S_GPE111 Game Result M G2S_GPE112 Game Ended LM M M L G2S_GPE113 Game Idle G2S_GPE201 Active Denominations Changed G2S_GPE202 Device Tilt S A brief word about the set of events related to the play of the device (G2S_GPE101 through G2S_GPE202). There are a variety of combinations of events that may occur. Refer to Figure 6.1, which contains a diagram that illustrates the events in relationship to the playStates of the device. Page 262 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 The following table lists the elements contained within the gamePlay class which may be included as affected data with events: Table 6.31 Elements Included With Events Affected Data Element Device Status gamePlayStatus Transaction Record recallLog 6.23.1 evaluate(state) The egmEnabled and egmState attributes are both determined from multiple factors. If all of the faults for a device have been cleared then the egmEnabled attribute for the device can be set to true. If any one fault still exists then the egmEnabled attribute MUST be set to false. Thus, after a fault is cleared, the EGM MUST evaluate all of the attributes that contribute to the state of the egmEnabled attribute. If anyone of them shows a fault then the egmEnabled attribute MUST remain false. This is communicated in the following documentation by using the convention "evaluate(device.egmEnabled)". Likewise, the egmState attribute of the cabinetStatus reflects the aggregate state of all devices in the EGM. If the requiredForPlay attribute in the profile of a device is set to true then if either the egmEnabled or hostEnabled attribute of the device is set to false, the egmState MUST reflect that the EGM is disabled. Similarly, if the egmLocked or hostLocked attribute of a device is set to true then the egmState MUST reflect that the EGM is locked out. If any one device is in such a state then the egmState MUST reflect that the EGM is disabled or locked out, as appropriate. Thus, after a device has been enabled or a lockout has been cleared, the EGM MUST evaluate the state of all active devices within the EGM to determine the proper value of the egmState attribute. At the same time, the deviceClass and deviceId attributes of the cabinetStatus MUST be updated to reflect the appropriate device. This is communicated in the following documentation by using the convention "evaluate(cabinet.egmState)". 6.23.2 G2S_GPE001 Device Disabled by EGM This event is sent by the EGM after the device has been disabled by the EGM. If the device was already disabled by the EGM then no event will be sent. Table 6.32 G2S_GPE001 Device, Meter, Log Changes, and Related Commands Details Device State Changes gamePlay.egmEnabled = "false" (however, all commands functional). evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 263 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.3 G2S_GPE002 Device Enabled by EGM This event is sent by the EGM after the device has been enabled by the EGM. If the device was already enabled, then no event will be sent. Table 6.33 G2S_GPE002 Device, Meter, Log Changes, and Related Commands Details Device State Changes gamePlay.egmEnabled = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 6.23.4 G2S_GPE003 Device Disabled by Host This event is sent by the EGM after the device has been disabled by the host. If the device was already disabled by the host then no event will be sent. Table 6.34 G2S_GPE003 Device, Meter, Log Changes, and Related Commands Details Device State Changes gamePlay.hostEnabled = "false" (however, all commands functional). evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 6.23.5 G2S_GPE004 Device Enabled by Host This event is sent by the EGM after the device has been enabled by the host. If the device was already enabled, then no event will be sent. Table 6.35 G2S_GPE004 Device, Meter, Log Changes, and Related Commands Details Device State Changes gamePlay.hostEnabled = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. Page 264 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 6.23.6 Chapter 6 gamePlay Class G2S_GPE005 Device Configuration Changed by Host This event is sent by the EGM after the configuration of the game play device has been changed by a host via the optionConfig class. The event MUST be sent after the optionChangeStatus command is sent by the configuration device. A host may use this event to as a means to trigger a re-discovery of the device by issuing getGamePlayStatus, getGamePlayProfile, and getGameDenoms commands to the device, causing the EGM to respond with updated information. Table 6.36 G2S_GPE005 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. 6.23.7 G2S_GPE006 Device Configuration Changed at EGM This event is sent by the EGM after the configuration of the game play device has been changed at the EGM via operator menu. The event MUST NOT be sent until the operator commits the changes or exits the operator menu of the EGM. A host may use this event to as a means to trigger a re-discovery of the device by issuing getGamePlayStatus, getGamePlayProfile, and getGameDenoms commands to the device, causing the EGM to respond with updated information. Table 6.37 G2S_GPE006 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. 6.23.8 G2S_GPE099 Device Tilts Cleared This event is sent by the EGM when the all device malfunctions have been remedied. In the case where multiple malfunctions occur simultaneously, each malfunction MUST be remedied before a G2S_GPE008 device restored event will be sent. Table 6.38 G2S_GPE099 Device, Meter, Log Changes, and Related Commands Details Device State Changes gamePlay.generalTilt = "false". gamePlay.reelTilt = "false". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 265 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.9 G2S_GPE101 Primary Game Escrow This event is sent by the EGM after the game play device has entered the primaryGameEscrow state. This will only apply when a central determinant game is being played. Table 6.39 G2S_GPE101 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes A new log record will be created and initialized as indicated in Table 6.40. Related Commands None. Table 6.40 G2S_GPE101 Log Changes Attribute Set to Value ... logSequence Set to a gamePlay class global sequence number. transactionId Set to an EGM global transaction identifier. deviceId Set to the gamePlay deviceId for the game activity. gameDateTime Updated to the time the record was created. playState Updated to G2S_primaryGameEscrow. playResult Reset to G2S_noResult. denomId Set to the denomId of the selected game combo. initialWager Set to the initial wager. finalWager Updated to the initial wager. initialWin Reset to 0 (zero). secondaryPlayed Reset to 0 (zero). secondaryWager Reset to 0 (zero). secondaryWin Reset to 0 (zero). finalWin Reset to 0 (zero). Page 266 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.10 G2S_GPE102 Primary Game Failed This event is sent by the EGM after the game play device has entered the gameIdle state from the previous primaryGameEscrow state and all associated meters have been updated. This will only apply when a central determinant game has failed to provide a valid outcome. Table 6.41 G2S_GPE102 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes The accounting meters may be updated as described in Table 6.42. Log State Changes The transaction log record associated with this game activity is updated with the data in Table 6.43. Related Commands None. Table 6.42 G2S_GPE102 Meters Incremented Bal Device Meter Group Attribute Description game play performance G2S_failedCnt Incremented by 1 (one). Table 6.43 G2S_GPE102 Log Changes Attribute Set Value to ... logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to the time the record was updated. playState Updated to G2S_gameIdle. playResult Set to G2S_gameFailed. denomId Unchanged. initialWager Unchanged. finalWager Reset to 0 (zero). initialWin Unchanged. secondaryPlayed Unchanged. secondaryWager Unchanged. secondaryWin Unchanged. finalWin Unchanged. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 267 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.11 G2S_GPE103 Primary Game Started This event is sent by the EGM after the game play device has entered the primaryGameStarted state and all associated meters have been updated. NOTE: The primaryGameStarted state MAY initiate a new game play transaction record if the game play device is not a central determinant game, otherwise the primaryGameStarted state will update the same transaction record that was created on the primaryGameEscrow state. Table 6.44 G2S_GPE103 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes The accounting meters may be updated as described in the following tables: Table 6.45, Table 6.46, and Table 6.47. Log State Changes If the game device is a central determinant game, then only the playState attribute will be updated; otherwise a new log record will be created and initialized as indicated in Table 6.48. Related Commands None. Table 6.45 G2S_GPE103 Meters Decremented Bal Device Meter Group Attribute Description Y cabinet cabinet G2S_playerCashableAmt Decremented by the portion of cashable credit contained in initialWager. Y cabinet cabinet G2S_playerPromoAmt Decremented by the portion of promotional credit contained in initialWager. Y cabinet cabinet G2S_playerNonCashAmt Decremented by the portion of noncashable credit contained in initialWager. Table 6.46 G2S_GPE103 Meters Incremented Bal Device Meter Group Attribute Description game play performance G2S_wageredAmt Incremented by the initialWager value. game play wager category G2S_wageredAmt Incremented by the initialWager value. game play game denom G2S_wageredAmt Incremented by the initialWager value. Y cabinet cabinet G2S_wageredCashableAmt Incremented by the portion of cashable credit contained in initialWager. Y cabinet cabinet G2S_wageredPromoAmt Incremented by the portion of promotional credit contained in initialWager. Y cabinet cabinet G2S_wageredNonCashAmt Incremented by the portion of noncashable credit contained in initialWager. Page 268 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.47 G2S_GPE103 Meters Updated Bal Device Meter Group Attribute Description game play performance G2S_avgPaybackPct Updated average payback percentage. game play performance G2S_theoPaybackAmt Incremented by the amount wagered times the payback percentage of the wager category played. game play game denom G2S_avgPaybackPct Updated average payback percentage. game play game denom G2S_theoPaybackAmt Incremented by the amount wagered times the payback percentage of the wager category played. Table 6.48 G2S_GPE103 Log Changes Attribute Description logSequence Set to a gamePlay class global sequence number. transactionId Set to an EGM global transaction identifier. deviceId Set to the gamePlay deviceId for the game activity. gameDateTime Updated to time that the record was updated. playState Updated to G2S_primaryGameStarted state. playResult Reset to G2S_noResult. denomId Set to the denomId of the active game combo. initialWager Set to the initial wager. finalWager Updated to the initial wager. initialWin Reset to 0 (zero). secondaryPlayed Reset to 0 (zero). secondaryWager Reset to 0 (zero). secondaryWin Reset to 0 (zero). finalWin Reset to 0 (zero). gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 269 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.12 G2S_GPE104 Wager Changed This event is sent by the EGM when the wager is changed within the context of the primary game cycle and all associated meters have been updated. In the case where multiple wager changes occur, then a separate G2S_GPE104 wager changed event will be sent corresponding to each wager change. Table 6.49 G2S_GPE104 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes The accounting meters may be updated as described in the following tables: Table 6.50, Table 6.51, and Table 6.52. Log State Changes The transaction log record associated with this game cycle is updated with the corresponding finalWager value. The finalWager value must not decrement from one G2S_GPE104 Wager Changed event to the next, the value may only increase or remain at the previous value. See Table 6.53. Related Commands None. Table 6.50 G2S_GPE104 Meters Decremented Bal Device Meter Group Attribute Description Y cabinet cabinet G2S_playerCashableAmt Decremented by the portion of cashable credit contained in the wager change. Y cabinet cabinet G2S_playerPromoAmt Decremented by the portion of promotional credit contained in the wager change. Y cabinet cabinet G2S_playerNonCashAmt Decremented by the portion of noncashable credit contained in the wager change. Table 6.51 G2S_GPE104 Meters Incremented Bal Device Meter Group Attribute Description game play performance G2S_wageredAmt Incremented by the wager change value. game play wager category G2S_wageredAmt Incremented by the wager change value. game play game denom G2S_wageredAmt Incremented by the wager change value. Y cabinet cabinet G2S_wageredCashableAmt Incremented by the portion of cashable credit contained in the wager change. Y cabinet cabinet G2S_wageredPromoAmt Incremented by the portion of promotional credit contained in the wager change. Y cabinet cabinet G2S_wageredNonCashAmt Incremented by the portion of noncashable credit contained in the wager change. Page 270 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.52 G2S_GPE104 Meters Updated Bal Device Meter Group Attribute Description game play performance G2S_avgPaybackPct Updated average payback percentage. game play performance G2S_theoPaybackAmt Incremented by the amount wagered times the payback percentage of the wager category played. game play game denom G2S_avgPaybackPct Updated average payback percentage. game play game denom G2S_theoPaybackAmt Incremented by the amount wagered times the payback percentage of the wager category played. Table 6.53 G2S_GPE104 Log Changes Attribute Description logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to time that the record was updated. playState Unchanged. playResult Unchanged. denomId Unchanged. initialWager Unchanged. finalWager Updated to match the wager change. initialWin Unchanged. secondaryPlayed Unchanged. secondaryWager Unchanged. secondaryWin Unchanged. finalWin Unchanged. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 271 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.13 G2S_GPE105 Primary Game Ended This event is sent by the EGM when the primary game concludes. NOTE: the primary game may conclude without necessarily completing the game cycle. Other states or events may occur, based upon the primary game results and secondary game activity. gamePlay Table 6.54 G2S_GPE105 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes The transaction log record associated with this game cycle is updated with the corresponding initialWin value. See Table 6.55. Related Commands None. Table 6.55 G2S_GPE105 Log Changes Attribute Set Value to ... logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to time that the record was updated. playState Updated to G2S_primaryGameEnded. playResult Unchanged. denomId Unchanged. initialWager Unchanged. finalWager Unchanged. initialWin Set to the initial win resulting from the primary game activity, including any progressive wins. secondaryPlayed Unchanged. secondaryWager Unchanged. secondaryWin Unchanged. finalWin Unchanged. Page 272 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.14 G2S_GPE106 Secondary Game Choice This event is sent by the EGM after the game play device has entered the secondaryGameChoice state. Table 6.56 G2S_GPE106 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes The transaction log record associated with this game activity is updated with the data in Table 6.57. Related Commands None. Table 6.57 G2S_GPE106 Log Changes Attribute Description logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to the time the record was created. playState Updated to G2S_secondaryGameChoice. playResult Unchanged. denomId Unchanged. initialWager Unchanged. finalWager Unchanged. initialWin Unchanged. secondaryPlayed Unchanged. secondaryWager Unchanged. secondaryWin Unchanged. finalWin Unchanged. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 273 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.15 G2S_GPE107 Secondary Game Escrow This event is sent by the EGM after the game play device has entered the secondaryGameEscrow state. This will only apply when a central determinant secondary game is being played. Table 6.58 G2S_GPE107 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes The transaction log record associated with this game activity is updated with the data in Table 6.59. Related Commands None. Table 6.59 G2S_GPE107 Log Changes Attribute Set Value to ... logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to the time the record was created. playState Updated to G2S_secondaryGameEscrow. playResult Unchanged. denomId Unchanged. initialWager Unchanged. finalWager Unchanged. initialWin Unchanged. secondaryPlayed Unchanged. secondaryWager Updated to reflect the additional secondary wager associated with this secondary game iteration. secondaryWin Unchanged. finalWin Unchanged. Page 274 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.16 G2S_GPE108 Secondary Game Failed This event is sent by the EGM after the game play device has entered the secondaryGameChoice state from the previous secondaryGameEscrow state and all associated meters have been updated. This will only apply when a central determinant secondary game has failed to provide a valid outcome. Table 6.60 G2S_GPE108 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes The accounting meters may be updated as described in Table 6.61. Log State Changes The transaction log record associated with this game activity is updated with the data in Table 6.62. Related Commands None. Table 6.61 G2S_GPE108 Meters Incremented Bal Device Meter Group Attribute Description game play performance G2S_secFailedCnt Incremented by 1 (one). Table 6.62 G2S_GPE108 Log Changes Attribute Description logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to the time the record was updated. playState Updated to G2S_secondaryGameChoice. playResult Unchanged. denomId Unchanged. initialWager Unchanged. finalWager Unchanged. initialWin Unchanged. secondaryPlayed Unchanged. secondaryWager Updated by removing the additional secondary wager amount associated with this secondary game iteration. secondaryWin Unchanged. finalWin Unchanged. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 275 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.17 G2S_GPE109 Secondary Game Started This event is sent by the EGM after the game play device has entered the secondaryGameStarted state and all associated meters have been updated. NOTE: each time a secondary game is played, the secondary* attributes of the recall log (secondaryPlayed, secondaryWager, secondaryWin) should be incremented. For example: If a player wagers and wins three secondary games before exiting the secondary game feature, the recall log’s secondary attributes should have been incremented three times; • three secondary games were played, • three secondary games were won, • the secondary wager was incremented three times, and • the amount won was incremented three times. Excluding any handpay jackpot, voucher, hopper, or note dispenser payment, the egmPaidGameWonAmt meter should be incremented with the total winnings remaining when the secondary game feature is exited and the playState attribute of the gamePlayStatus is set to G2S_gameEnded. Table 6.63 G2S_GPE109 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes The accounting meters may be updated as described in Table 6.64. Log State Changes If the game play device is a central determinant game, only the playState attribute will be updated; otherwise, the transaction log record associated with this secondary game activity is updated as indicated in Table 6.65. Related Commands None. Table 6.64 G2S_GPE109 Meters Incremented Bal Page 276 Device Meter Group Attribute Description game play performance G2S_secWageredAmt Incremented by the wager value of this secondary game iteration. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.65 G2S_GPE109 Log Changes Attribute Description logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to time that the record was updated. playState Updated to G2S_secondaryGameStarted. playResult Unchanged. denomId Unchanged. initialWager Unchanged. finalWager Unchanged. initialWin Set to the win amount from the primary game. secondaryPlayed Updated to number of secondary games played in this game cycle. secondaryWager Updated to the total accumulated secondary wager in this game cycle. secondaryWin Updated to the total accumulated secondary win in this game cycle. finalWin Unchanged. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 277 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.18 G2S_GPE110 Secondary Game Ended This event is sent by the EGM after a secondary game has ended and all associated meters have been updated. Table 6.66 G2S_GPE110 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes The accounting meters may be updated as described in Table 6.67. Log State Changes The transaction log record associated with this game cycle is updated with the value corresponding to the completion of a secondary game. See Table 6.68. secondaryWin Related Commands None. Table 6.67 G2S_GPE110 Meters Incremented Bal Device Meter Group Attribute Description game play performance G2S_secWonAmt Updated by the win value of this secondary game iteration. game play performance G2S_secWonCnt Incremented if the secondary game is won. game play performance G2S_secLostCnt Incremented if the secondary game is lost. game play performance G2S_secTiedCnt Incremented if the secondary game is tied. Table 6.68 G2S_GPE110 Log Changes Attribute Description logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to time that the record was updated. playState Updated to G2S_secondaryGameEnded. playResult Unchanged. denomId Unchanged. initialWager Unchanged. finalWager Unchanged. initialWin Unchanged. secondaryPlayed Unchanged. secondaryWager Unchanged. secondaryWin Updated to the total accumulated secondary win in this game cycle. finalWin Unchanged. Page 278 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.19 G2S_GPE111 Game Result This event is sent by the EGM after the game play device has concluded all primary and/or secondary game play activity. This event may be used to indicate that the EGM has determined the final win and is about to distribute payment of any winnings as a result of game play activity. Table 6.69 G2S_GPE111 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes The transaction log record associated with this game activity is updated with the data in Table 6.70. Related Commands None. Table 6.70 G2S_GPE111 Log Changes Attribute Set Value to ... logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to the time the record was created. playState Unchanged. playResult Unchanged. denomId Unchanged. initialWager Unchanged. finalWager Unchanged. initialWin Unchanged. secondaryPlayed Unchanged. secondaryWager Unchanged. secondaryWin Unchanged. finalWin Updated to reflect to net result of any primary and secondary game outcome. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 279 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.20 G2S_GPE112 Game Ended This event is sent by the EGM after the game play device has entered the gameEnded state and all associated meters have been updated. This event indicates that all game play activity has concluded and any payments have been distributed, yet the game play device is not ready to begin a new game cycle (due to a game delay period specified in the bonus class). Table 6.71 G2S_GPE112 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes The accounting meters may be updated as described in Table 6.72. Log State Changes The transaction log record associated with this game cycle is updated with the data in Table 6.73. Related Commands None. Table 6.72 G2S_GPE112 Meters Incremented (Sheet 1 of 2) Bal Device Meter Group Attribute Description game play performance G2S_egmPaidGameWonAmt Incremented based upon the pay distribution. game play performance G2S_handPaidGameWonAmt Incremented based upon the pay distribution. game play performance G2S_egmPaidProgWonAmt Incremented based upon the pay distribution. game play performance G2S_handPaidProgWonAmt Incremented based upon the pay distribution. game play performance G2S_wonCnt Incremented if initialWin > 0. game play performance G2S_lostCnt Incremented if initialWin = 0. game play performance G2S_tiedCnt Incremented if the game tied. game play game denom G2S_playedCnt Incremented by 1 (one). game play wager category G2S_playedCnt Incremented by 1 (one). Y cabinet cabinet G2S_playerCashableAmt Incremented by the portion of finalWin cashable credit added to the credit meter. Y cabinet cabinet G2S_egmPaidGameWonAmt Incremented based upon the pay distribution. Y cabinet cabinet G2S_handPaidGameWonAmt Incremented based upon the pay distribution. Y cabinet cabinet G2S_egmPaidProgWonAmt Incremented based upon the pay distribution. Y cabinet cabinet G2S_handPaidProgWonAmt Incremented based upon the pay distribution. Y cabinet cabinet G2S_egmDispensedCashableAmt Incremented by the portion of win that is dispensed by the EGM. cabinet cabinet G2S_gamesSinceInitCnt Incremented by 1 (one). Page 280 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.72 G2S_GPE112 Meters Incremented (Sheet 2 of 2) Bal Y Y Y Y Device Meter Group Attribute Description cabinet cabinet G2S_gamesSincePowerResetCnt Incremented by 1 (one). cabinet cabinet G2S_gamesSinceDoorClosedCnt Incremented by 1 (one). progressive transfer G2S_cashableInAmt Incremented by cashable progressive amount won. progressive transfer G2S_transferInCnt Incremented by the number of progressives won. hopper currency G2S_curOutAmt Incremented by the hopper dispensed amounts. hopper currency G2S_curOutCnt Incremented by the hopper dispensed count. note dispenser currency G2S_curOutAmt Incremented by the note dispenser amounts. note dispenser currency G2S_curOutCnt Incremented by the note dispenser count. handpay transfer G2S_cashableOutAmt Incremented by the cashable handpay amounts dispensed. handpay transfer G2S_transferOutCnt Increased by one for each handpay performed. voucher transfer G2S_cashableOutAmt Incremented by the cashable voucher dispensed amounts. voucher transfer G2S_transferOutCnt Incremented by one for each voucher dispensed. wat transfer G2S_cashableOutAmt Incremented by the cashable WAT out amounts. wat transfer G2S_transferOutCnt Incremented by one for each WAT out transfer. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 281 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 Table 6.73 G2S_GPE112 Log Changes Attribute Description logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to time that the record was updated. playState Updated to G2S_gameEnded state. playResult Set to the final result. denomId Unchanged. initialWager Unchanged. finalWager Unchanged. initialWin Unchanged. secondaryPlayed Unchanged. secondaryWager Unchanged. secondaryWin Unchanged. finalWin Set to the final win. Page 282 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.21 G2S_GPE113 Game Idle This event is sent by the EGM after the game play device enters the gameIdle state. This event indicates that all game play activity has concluded, any payments have been distributed, and the game play device is ready to begin a new game cycle. Table 6.74 G2S_GPE113 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes The transaction log record associated with this game activity is updated with the data in Table 6.70. Related Commands None. Table 6.75 G2S_GPE113 Log Changes Attribute Set Value to ... logSequence Unchanged. transactionId Unchanged. deviceId Unchanged. gameDateTime Updated to the time the record was updated. playState Update to G2S_gameIdle. playResult Unchanged. denomId Unchanged. initialWager Unchanged. finalWager Unchanged. initialWin Unchanged. secondaryPlayed Unchanged. secondaryWager Unchanged. secondaryWin Unchanged. finalWin Unchanged. 6.23.22 G2S_GPE201 Active Denominations Changed This event is sent by the EGM after the game play device has applied the settings from the setActiveDenoms command. This event may be used to indicate that the device’s active denominations have been altered by the host or at the EGM. Table 6.76 G2S_GPE201 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands setActiveDenoms. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 283 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.23.23 G2S_GPE202 Device Tilt This event is sent by the EGM when the device has a malfunction. In the case where multiple malfunctions occur simultaneously, each malfunction will cause a corresponding G2S_GPE007 device tilt event to be sent. Table 6.77 G2S_GPE202 Device, Meter, Log Changes, and Related Commands Details Device State Changes gamePlay.generalTilt = "true" and/or gamePlay.reelTilt = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. Page 284 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.24 Examples 6.24.1 Get Game Play Status Command Sequence HOST EGM getGamePlayStatus gamePlayStatus The following example illustrates the construction of a getGamePlayStatus request command sent from a host to an EGM, followed by the gamePlayStatus response command sent from the EGM to the host. 6.24.1.1 getGamePlayStatus: Host to EGM <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "2002" sessionId = "1002" sessionType = "G2S_request" > <getGamePlayStatus /> </gamePlay> 6.24.1.2 gamePlayStatus: EGM to Host <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "3002" sessionId = "1002" sessionType = "G2S_response" > <gamePlayStatus configurationId = "0" egmEnabled = "true" hostEnabled = "false" themeId = "ABC_bonusPoker" paytableId = "ABC_bonusPoker0090" generalTilt = "false" reelTilt = "false" /> </gamePlay> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 285 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.24.2 Set Game Play State Command Sequence HOST EGM setGamePlayState gamePlayState The following example illustrates the construction of a setGamePlayState request command sent from a host to an EGM, followed by the gamePlayStatus response command sent from the EGM to the host. 6.24.2.1 setGamePlayState: Host to EGM <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "2003" sessionId = "1003" sessionType = "G2S_request" > <setGamePlayState enable = "true" /> </gamePlay> 6.24.2.2 gamePlayStatus: EGM to Host <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "3003" sessionId = "1003" sessionType = "G2S_response" > <gamePlayStatus configurationId = "0" egmEnabled = "true" hostEnabled = "true" themeId = "ABC_bonusPoker" paytableId = "ABC_bonusPoker0090" generalTilt = "false" reelTilt = "false" /> </gamePlay> Page 286 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.24.3 Get Game Play Profile Command Sequence HOST EGM getGamePlayProfile gamePlayProfile The following example illustrates the construction of a getGamePlayProfile request command sent from a host to an EGM, followed by the gamePlayProfile response command sent from the EGM to the host. 6.24.3.1 getGamePlayProfile: Host to EGM <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "2001" sessionId = "1001" sessionType = "G2S_request" > <getGamePlayProfile /> </gamePlay> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 287 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.24.3.2 gamePlayProfile: EGM to Host <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "3001" sessionId = "1001" sessionType = "G2S_response" > <gamePlayProfile themeId = "ABC_bonusPoker" paytableId = "ABC_bonusPoker0090" maxWagerCredits = "5" progAllowed = "true" secondaryAllowed = "true" > <wagerCategoryList> <wagerCategoryItem wagerCategory = "ABC_pokerBasic" theoPaybackPct = "8900" /> <wagerCategoryItem wagerCategory = "ABC_pokerNominal" theoPaybackPct = "9000" /> </wagerCategoryList> <winLevelList> <winLevelItem winLevelIndex = "0" winLevelCombo = "No Win" /> <winLevelItem winLevelIndex = "1" winLevelCombo = "Royal Flush" progressiveAllowed = "true" /> <winLevelItem winLevelIndex = "2" winLevelCombo = "Straight Flush" progressiveAllowed = "true" /> <winLevelItem winLevelIndex = "3" winLevelCombo = "4 of a Kind" progressiveAllowed = "true" /> <winLevelItem winLevelIndex = "4" winLevelCombo = "Full House" progressiveAllowed = "true" /> <winLevelItem winLevelIndex = "5" winLevelCombo = "Flush" progressiveAllowed = "true" /> <winLevelItem winLevelIndex = "6" winLevelCombo = "Straight" progressiveAllowed = "true" /> <winLevelItem winLevelIndex = "7" winLevelCombo = "3 of a Kind" progressiveAllowed = "true" /> <winLevelItem winLevelIndex = "8" winLevelCombo = "2 Pair" progressiveAllowed = "true" /> <winLevelItem winLevelIndex = "9" winLevelCombo = "Jacks or Better" progressiveAllowed = "true" /> </winLevelList> </gamePlayProfile> </gamePlay> Page 288 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.24.4 Get Game Denomination Command Sequence HOST EGM getGameDenoms gameDenomList The following example illustrates the construction of a getGameDenoms request command sent from a host to an EGM, followed by the gameDenomList response command sent from the EGM to the host. 6.24.4.1 getGameDenoms: Host to EGM <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "2004" sessionId = "1004" sessionType = "G2S_request" > <getGameDenoms /> </gamePlay> 6.24.4.2 gameDenomList: EGM to Host <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "3004" sessionId = "1004" sessionType = "G2S_response" > <gameDenomList> <gameRange denomMin = "1000" denomMax = "5000" active = "false" /> <gameDenom denomId = "10000" active = "false" /> <gameDenom denomId = "25000" active = "false" /> <gameDenom denomId = "50000" active = "false" /> <gameDenom denomId = "100000" active = "false" /> </gameDenomList> </gamePlay> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 289 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.24.5 Set Active Denominations Command Sequence The following example illustrates the construction of a setActiveDenoms request command sent from a host to an EGM, followed by the gameDenomList response command sent from the EGM to the host: HOST EGM setActiveDenoms gameDenomList 6.24.5.1 setActiveDenoms: Host to EGM <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "2005" sessionId = "1005" sessionType = "G2S_request" > <setActiveDenoms> <activeRange denomMin = "1000" denomMax = "5000" /> <activeDenom denomId = "10000" /> <activeDenom denomId = "25000" /> </setActiveDenoms> </gamePlay> 6.24.5.2 gameDenomList: EGM to Host <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "3005" sessionId = "1005" sessionType = "G2S_response" > <gameDenomList> <gameRange denomMin = "1000" denomMax = "5000" active = "true" /> <gameDenom denomId = "10000" active = "true" /> <gameDenom denomId = "25000" active = "true" /> <gameDenom denomId = "50000" active = "false" /> <gameDenom denomId = "100000" active = "false" /> </gameDenomList> </gamePlay> Page 290 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.24.6 getRecallLogStatus The following example illustrates the construction of a getRecallLogStatus request command sent from a host to an EGM, followed by the recallLogStatus response command sent from the EGM to the host: 6.24.6.1 HOST EGM getRecallLogStatus recallLogStatus getRecallLogStatus: Host to EGM <gamePlay deviceId="1" dateTime="2006-02-01T12:34:56.789-5:00" commandId="2006" sessionId="1006" sessionType="G2S_request" > <getRecallLogStatus /> </gamePlay> 6.24.6.2 recallLogStatus: EGM to Host <gamePlay deviceId="1" dateTime="2006-02-01T12:34:56.789-5:00" commandId="3006" sessionId="1006" sessionType="G2S_response" > <recallLogStatus lastSequence="2" totalEntries="2" /> </gamePlay> 6.24.7 getRecallLog The following example illustrates the construction of a getRecallLog request command sent from a host to an EGM, followed by the recallLogList response command sent from the EGM to the host: 6.24.7.1 getRecallLog: Host to EGM HOST EGM getRecallLog recallLogList <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "2007" sessionId = "1007" sessionType = "G2S_request" > <getRecallLog lastSequence = "2" totalEntries = "2" /> </gamePlay> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 291 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.24.7.2 recallLogList: EGM to Host <gamePlay deviceId = "1" dateTime = "2006-02-01T12:34:56.789-5:00" commandId = "3007" sessionId = "1007" sessionType = "G2S_response" > <recallLogList> <recallLog logSequence = "2" deviceId = "1" transactionId = "502" gameDateTime = "2006-02-01T12:34:56.789-5:00" playState = "G2S_gameEnded" playResult = "G2S_gameWon" denomId = "5000" initialWager = "5000" finalWager = "5000" initialWin = "10000" secondaryPlayed = "0" secondaryWager = "0" secondaryWin = "0" finalWin = "10000" /> <recallLog logSequence = "1" deviceId = "1" transactionId = "501" gameDateTime = "2006-02-01T12:34:56.789-5:00" playState = "G2S_gameEnded" playResult = "G2S_gameLost" denomId = "5000" initialWager = "5000" finalWager = "5000" initialWin = "5000" secondaryPlayed = "3" secondaryWager = "35000" secondaryWin = "30000" finalWin = "0" /> </recallLogList> </gamePlay> Page 292 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.25 Game Play Device Option Configuration The following sections identify the G2S-specified configuration option selections for game play devices and provides examples of optionItem elements in Section 6.25.6. Configuration option selections are set using commands from the optionConfig class. The current configuration option selections for a game play device are reported via the gamePlayProfile command. Further descriptions of the sub-parameters can be found under the gamePlayProfile command. 6.25.1 Option Group Definitions optionGroupId optionGroupName 6.25.2 G2S_gamePlayOptions G2S Game Play Options G2S Protocol Option Definitions optionId securityLevel G2S_protocolOptions minSelections G2S_administrator 1 maxSelections 1 duplicates Duplicate Key Parameter Type paramId 6.25.3 n/a n/a Complex G2S_protocolParams paramName G2S Protocol Parameters paramHelp Standard G2S protocol parameters for gamePlay devices G2S Protocol Option Sub-Parameter Definitions Table 6.78 G2S Protocol Option Sub-Parameter Definitions paramId paramName Example paramHelp G2S_configurationId Configuration Identifier 123456 ID assigned by the last successful G2S option configuration G2S_restartStatus Enabled on Restart True hostEnabled attribute status upon EGM restart G2S_useDefaultConfig Use Default Configuration False Use default configuration on restart G2S_requiredForPlay Required For Play True Device is required for game play gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 293 Chapter 6 gamePlay Class G2S™ Message Protocol v1.0.3 6.25.4 Game Play Option Definitions optionId securityLevel G2S_gamePlayOptions minSelections G2S_operator 1 maxSelections 1 duplicates Duplicate Key Parameter Type paramId 6.25.5 n/a n/a Complex G2S_gamePlayParams paramName Game Play Parameters paramHelp Configuration settings for this game play device Game Play Option Sub-Parameter Definitions Table 6.79 Game Play Option Sub-Parameter Definitions paramId paramName Example paramHelp G2S_themeId Theme ID ABC_Wild Ones Theme for this device G2S_paytableId Paytable ID ABC_paytable32 Paytable for this device G2S_maxWagerCredits Max Wager (credits) 3 Maximum wager (in credits) G2S_progAllowed Progressive Allowed True Progressive allowed for this device G2S_secondaryAllowed Secondary Allowed True Secondary game allowed for this device G2S_centralAllowed Central Determination False Outcomes determined by central determination host Page 294 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 6.25.6 Chapter 6 gamePlay Class Example optionItem Elements in optionList The following are examples of optionItem elements, which are used by the EGM to describe its configurable options for game play devices. These elements are sent by the EGM to the host in the optionList command. // G2S Protocol Options <optionItem optionId = "G2S_protocolOptions" securityLevel = "G2S_administrator" minSelections = "1" maxSelections = "1" > <optionParameters> <complexParameter paramId = "G2S_protocolParams" paramName = "G2S Protocol Parameters" paramHelp = "Standard G2S protocol parameters for game play devices" > <integerParameter paramId = "G2S_configurationId" paramName = "Configuration Identifier" paramHelp = "ID assigned by the last successful G2S option configuration" canModLocal = "false" canModRemote = "false" /> <booleanParameter paramId = "G2S_restartStatus" paramName = "Enabled on Restart" paramHelp = "hostEnabled attribute status upon EGM restart" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_useDefaultConfig" paramName = "Use Default Configuration" paramHelp = "Use default configuration on restart" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_requiredForPlay" paramName = "Required For Play" paramHelp = "Device is required for game play" canModLocal = "true" canModRemote = "true" /> <integerParameter paramId = "G2S_timeToLive" paramName = "Time To Live" paramHelp = "Time to live value for requests (in milliseconds)" canModLocal = "true" canModRemote = "true" minIncl = "0" /> </complexParameter> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 123456 </integerValue> <booleanValue paramId = "G2S_restartStatus" > true </booleanValue> <booleanValue paramId = "G2S_useDefaultConfig" > false </booleanValue> <booleanValue paramId = "G2S_requiredForPlay" > true </booleanValue> <integerValue paramId = "G2S_timeToLive" >30000</integerValue> </complexValue> </optionCurrentValues> <optionDefaultValues> <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 0 </integerValue> <booleanValue paramId = "G2S_restartStatus" > true </booleanValue> <booleanValue paramId = "G2S_useDefaultConfig" > false </booleanValue> <booleanValue paramId = "G2S_requiredForPlay" > true </booleanValue> <integerValue paramId = "G2S_timeToLive" >30000</integerValue> </complexValue> </optionDefaultValues> </optionItem> // Game Play Parameters <optionItem optionId = "G2S_gamePlayOptions" securityLevel = "G2S_operator" minSelections = "1" maxSelections = "1" > gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 295 G2S™ Message Protocol v1.0.3 Chapter 6 gamePlay Class <optionParameters> <complexParameter paramId = "G2S_gamePlayParams" paramName = "Game Play Parameters" paramHelp = "Configuration settings for this game play device" > <stringParameter paramId = "G2S_themeId" paramName = "Theme ID" paramHelp = "Theme for this device" minLen = "5" maxLen = "32" canModLocal = "true" canModRemote = "true" /> <stringParameter paramId = "G2S_paytableId" paramName = "Paytable ID" paramHelp = "Paytable for this device" minLen = "5" maxLen = "32" canModLocal = "true" canModRemote = "true" /> <integerParameter paramId = "G2S_maxWagerCredits" paramName = "Max Wager (credits)" paramHelp = "Maximum wager in credits" minIncl = "1" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_progAllowed" paramName = "Progressive Allowed" paramHelp = "Progressive allowed for this device" canModLocal = "false" canModRemote = "false" /> <booleanParameter paramId = "G2S_secondaryAllowed" paramName = "Secondary Allowed" paramHelp = "Secondary game allowed for this device" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_centralAllowed" paramName = "Central Determination" paramHelp = "Central determination support" canModLocal = "true" canModRemote = "true" /> </complexParameter> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_gamePlayParams" > <integerValue paramId = "G2S_configurationId" > 0 </integerValue> <stringValue paramId = "G2S_themeId" > ABC_A Game Theme </stringValue> <stringValue paramId = "G2S_paytableId" > ABC_A Paytable ID 95% </stringValue> <integerValue paramId = "G2S_maxWagerCredits" > 3 </integerValue> <booleanValue paramId = "G2S_progAllowed" > false </booleanValue> <booleanValue paramId = "G2S_secondaryAllowed" > false </booleanValue> <booleanValue paramId = "G2S_centralAllowed" > false </booleanValue> </complexValue> </optionCurrentValues> <optionDefaultValues> <complexValue paramId = "G2S_gamePlayParams" > <integerValue paramId = "G2S_maxWagerCredits" > 1 </integerValue> <booleanValue paramId = "G2S_progAllowed" > false </booleanValue> <booleanValue paramId = "G2S_secondaryAllowed" > false </booleanValue> <booleanValue paramId = "G2S_centralAllowed" > false </booleanValue> </complexValue> </optionDefaultValues> </optionItem> Page 296 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 7 deviceConfiguration Class G2S™ Message Protocol v1.0.3 7 deviceConfig Class [In development] gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 297 G2S™ Message Protocol v1.0.3 Page 298 Chapter 7 deviceConfiguration Class gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 8 commConfig Class 8.1 Introduction Chapter 8 commConfig Class The commConfig class is used to remotely configure the G2S communications setup of an EGM. The class includes commands for setting the list of registered hosts and assigning owners to devices. There is no requirement that an EGM support the commConfig class. Alternatively, options covered by the commConfig class can be set manually through the operator mode of the EGM; however, the commConfig class provides a convenient and efficient mechanism to perform these functions remotely. The commConfig class is a single-device class. The EGM MUST expose only one active comms configuration device. 8.2 commConfig Overview A host system can query the EGM to discover which communications options the EGM supports and whether the host is able to change those options. All EGMs that support this class MUST, at a minimum, report the list of registered hosts and list of device owners. Remotely changing the communication configuration of an EGM through this class is generalized in the diagram below: gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 299 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 Host sends changes to EGM EGM validates changes Pass EGM validation? No Yes Applicable host authorizes EGM to apply changes EGM sends Error code to Host EGM applies changes EGM does not apply changes End Figure 8.1 Remote Configuration Flow NOTE: The pass validation step includes checking for data that is incomplete, inconsistent or otherwise fails the EGM’s validation tests. If the host instructs the EGM to apply such invalid changes, the EGM MUST send the appropriate error code to the host. Page 300 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 8.3 Chapter 8 commConfig Class commConfig Changes: Contents, Apply Conditions, and Sending Rules 8.3.1 Contents A set of changes MAY contain: • changes to the list of registered hosts • changes to device ownerships A set of changes MUST contain: • A transactionId used to uniquely identify the set of changes and is included in all subsequent commands sent by the host or EGM related to the set of changes. The EGM assigns the identifier and MUST generate the transactionId as a monotonically-increasing sequence. The EGM will generate error G2S_CCX007 Transaction Identifier In Use or G2S_CCX008 Invalid Transaction Identifier if a host tries to authorize a set of changes with a transactionId that the EGM has retired or is not aware of. • A configurationId used to uniquely identify the set of changes from the host and is included in all subsequent commands sent by the host or EGM related to the set of changes. The host assigns this identifier for host tracking purposes and this identifier must match the configurationId returned in the profile command for a device. For a set of changes not made by a host, the configurationId MUST be set to 0 (zero). 8.3.2 commConfig Change Host Authorization The commConfig class provides the ability for one or more hosts to authorize a comm change before it occurs. This mechanism may be used by a host to read critical status, logs, or meter data from an EGM before authorizing the comm change to proceed. The change log contains a list of the hosts required to authorize the change so that a host may subscribe to the G2S_CCE103 commConfig Configuration Change Pending and G2S_CCE109 commConfig Configuration Waiting on Authorization events with the affected log included in the subscription. This allows a host to determine if it needs to authorize the device change based upon the event subscription. 8.3.3 Conditions Under Which Changes Can be Applied The following are the conditions under which a set of changes should be applied: • changes can be applied based on a command from the host, • changes can be applied based on an operator action at the EGM, or • changes can be applied automatically during a specified time period. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 301 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.3.4 Rules for Applying Changes That Are Sent from a Host The following rules apply to commConfig changes sent to an EGM: 1. The EGM contains only one set of changes at any time: a. If a host sends a set of changes to the EGM, and the EGM already has a set of validated changes, the previous set is overwritten with the most current set. b. If the EGM contains a set of validated changes from a host that have not been activated and an operator manually changes any settings at the EGM, the host set of changes are aborted and not applied. 2. Until the EGM receives an authorization from the host, the EGM must not apply the set of changes. 3. Until applied, a validated set of changes remains in a pending state on the EGM. 4. The host may cancel a set of changes before they are applied. 5. After a set of changes is applied, affected options can only be changed by either: a. sending and applying a new set of changes, or b. operator action at the EGM. 6. After a set of changes is applied, whether the changes were sent from a host system or entered locally at the EGM, the EGM MUST report the changes to the host. Page 302 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 8.4 Chapter 8 commConfig Class Rules for Changes To Hosts And Device Owners The comms configuration device structure of the EGM includes the list of registered hosts as well as the owners of individual devices. The following rules apply to any changes to the current commConfig structure residing on an EGM: 1. The EGM MUST validate pending host and device ownership changes. 2. The EGM MUST send a commsClosing command to any registered hosts that will be affected by the changes to the updated device structure. 3. The EGM MUST send a commsOnLine command to all newly registered hosts: Example 1: Adding or removing a host that is monitoring an EGM would not require that commsClosing and commsOnLine commands be sent to any host except the host being added or removed. Example 2: Reassigning ownership of a device from one host to another host would require that commsClosing and commsOnLine commands be sent to the two hosts affected by the change, but not to other hosts monitoring the device. 4. The EGM MUST always have at least one registered host. 5. All devices MUST be owned by a registered host. Devices cannot be owned by unregistered hosts. 6. Devices that are not owned by a host can be exposed in the commConfig class as having a hostId set to 0 (zero). Devices that have a hostId of 0 (zero) are considered inactive and are only exposed in the commConfig and deviceConfig classes. 7. Prior to applying host and device ownership changes, the EGM MUST continue to communicate normally with all registered hosts. 8. If a new configuration fails, the EGM MUST continue to communicate with all registered hosts using the existing settings. 8.5 Default Configuration EGMs contain a default configuration in order to establish initial settings. The default configuration must include at least one registered host (see section 1.9.1 for information about device ownership). In the simplest scenario, the default configuration for an EGM would contain one registered host and that host would own all devices within the EGM, including the comms configuration device. Initially, not all host identifiers may have a host system associated with them. These unregistered hosts can be viewed and registered using commands within the commConfig class. Unregistered hosts appear only in the commConfig class. Unregistered hosts do not appear in the communications, meters, and other device classes. To establish communications with a host, the default configuration for the EGM MUST contain the address of the host. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 303 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.6 Request-Response Pairs The following tables organize the commands contained within the commConfig class into request-response pairs: Table 8.1 Commands Originated by EGM Request Response commHostList commHostListAck commChangeStatus commChangeStatusAck Table 8.2 Commands Originated by Host Request Response Owner Guest enterCommConfigMode commConfigModeStatus Yes No getCommConfigModeStatus commConfigModeStatus Yes Yes getCommConfigProfile commConfigProfile Yes Yes getCommHostList commHostList Yes Yes setCommChange commChangeStatus Yes No cancelCommChange commChangeStatus Yes No authorizeCommChange commChangeStatus Yes Yes getCommChangeLogStatus commChangeLogStatus Yes Yes getCommChangeLog commChangeLogList Yes Yes Page 304 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.7 enterCommConfigMode Command This command is used by a host to lock the EGM from play and to control the configuration mode of an EGM. Only the owner of the device can execute this command. The commConfigModeStatus command is sent in response to the enterCommConfigMode command. When enabled, the EGM is placed into a mode that allows communication configuration changes to execute. At the time this mode is enabled, the EGM MUST NOT allow game play on the EGM. Jurisdictional regulations and operator preferences will dictate when this command can be applied by the EGM. Changing the configuration mode on an EGM while the EGM is being played will probably not be permitted in most jurisdictions. For example, an EGM may apply the following logic when executing the enterCommConfigMode command: 1. Wait for credit meter to reach 0 (zero). 2. Wait for the EGM to be idle according to the idleTimePeriod parameter configured in the cabinet class. 3. Apply the enterCommConfigMode command to affect the commConfigModeStatus.enabled attribute. 4. Generate event G2S_CCE101 commConfig Entered Configuration Mode or G2S_CCE102 commConfig Exited Configuration Mode, depending upon the value of the enabled attribute. The exact logic executed by the EGM for this command is dependent on the EGM's configuration and subject to jurisdictional regulations. Table 8.3 enterCommConfigMode Attributes Attribute Restrictions Description enable type: boolean use: optional default: true Indicates whether the comms configuration mode should be enabled or disabled. disableText type: textMessage use: optional default <empty> Optional message to display while the mode is enabled (and game play is disabled). 8.8 getCommConfigModeStatus Command This command is used by a host to request the current status of the comms configuration device from the EGM. The EGM sends a commConfigModeStatus command in response to the getCommConfigModeStatus command. The getCommConfigModeStatus command has no additional attributes or elements. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 305 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.9 commConfigModeStatus Command This command is used by the EGM to send the current status of the comms configuration device to a host. The commConfigModeStatus command is sent in response to the enterCommConfigMode and getCommConfigModeStatus commands. Table 8.4 commConfigModeStatus Attributes Attribute Restrictions Description configurationId type: configurationId use: optional default: 0 Configuration identifier set by the host. enabled type: boolean use: optional default: false Indicates whether the comms configuration mode is enabled by the host. 8.10 getCommConfigProfile Command This command is used by a host to request the profile information. The commConfigProfile command is sent in response to the getCommConfigProfile command. The getCommConfigProfile element contains no additional attributes or elements. Page 306 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.11 commConfigProfile Command This command is used by an EGM to send the profile of the comms configuration device to a host. The profile contains protocol-related configuration options selections for a comms configuration device. The commConfigProfile command is sent in response to the getCommConfigProfile command. Table 8.5 commConfigProfile Attributes Attribute Restrictions configurationId * type: configurationId use: optional default: 0 minLogEntries * noResponseTimer * type: milliseconds use: optional default: 300000 * 8.12 type: int use: optional minIncl: 1 default: 10 Description Last configuration identifier set by a G2S host; set to 0 (zero) when configuration changes are made by hosts other than G2S hosts. Indicates the minimum number of log entries the EGM must maintain in persistent memory. The time a device will wait for an optionListAck before determining the EGM has lost communications with the host. Standard configuration option that MUST be included in the standard option configuration group – G2S_commConfigOptions – for devices within the commConfig class. getCommHostList Command This command is used by a host to request the list of hosts from an EGM. The EGM sends a commHostList command in response to the getCommHostList command. There are no additional attributes or elements for this command. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 307 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.13 commHostList Command This command is used by an EGM to report the current comms configuration structure residing on an EGM. • The commHostList command is sent in response to a getCommHostList command. • It is also sent whenever the list of registered hosts is changed, in which case, only affected hosts MUST be sent. For this circumstance, the commHostListAck is sent in response to the commHostList command. The canModLocal and canModRemote attributes indicate where changes can be performed. • If there is no prohibition against local changes, then the canModLocal attribute MUST be set to true. Likewise, if there is no prohibition against remote changes, then the canModRemote attribute MUST be set to true. Table 8.6 commHostList Elements Element Restrictions Description commHostItem minOcc: 1 Contains information about an individual registered host. See Sections Table 8.7 and Table 8.8 for details. maxOcc: ∞ Table 8.7 commHostItem Attributes (Sheet 1 of 2) Attribute Restrictions Description hostIndex type: int use: required minIncl: 0 Internal index value for the host assigned by the EGM. hostId type: deviceId use: required Identifier assigned to the host by the network administrator; 0 if unregistered. hostLocation type: transportLocation use: required URI or other identifier of the host. hostRegistered type: boolean use: optional default: true Indicates whether the host is a member of the list of registered hosts. useDefaultConfig type: boolean use: optional default: false Indicates whether the default configuration for the device MUST be used when the EGM restarts. Page 308 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 Table 8.7 commHostItem Attributes (Sheet 2 of 2) Attribute Restrictions Description requiredForPlay type: boolean use: optional default: false Indicates whether the EGM MUST be disabled if either egmEnabled or hostEnabled is set to false. timeToLive type: timeToLive use: optional default: 30000 Time-to-live value for requests originated by the device. noResponseTimer type: milliseconds use: optional default: 300000 The no-response timer used to determine whether an EGM has lost communications with a host. allowMulticast type: boolean use: optional default: false Indicates whether the host is authorized to send multicast messages. See Chapter 1 for more information about the multicast transport and message format. canModLocal type: boolean use: optional default: true Indicates whether host selections can be changed at the EGM. displayCommFault type: boolean use: optional default: false Indicates whether a communications fault message should be displayed if the communications channel is unavailable. canModRemote type: boolean use: optional default: true Indicates whether host selections can be changed remotely. Table 8.8 commHostItem Elements Element Restrictions Description ownedDevice minOcc: 0 Details about one device for which the host is registered as owner. See Table 8.9 for attributes. maxOcc: configDevice Details about one option configuration device for which the host is registered as the owner. See Table 8.10. minOcc: 0 maxOcc: guestDevice ∞ ∞ Details about one device for which the host is registered as guest. See Table 8.11 for attributes. minOcc: 0 maxOcc: ∞ Table 8.9 ownedDevice Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class of the device. deviceId type: deviceId use: required Device identifier of the device; assigned by the EGM. deviceActive type: boolean use: required Indicates whether the device is active (true) or inactive (false). gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 309 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 Table 8.10 configDevice Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class of the device. deviceId type: deviceId use: required Device identifier of the device; assigned by the EGM. deviceActive type: boolean use: required Indicates whether the device is active (true) or inactive (false). Table 8.11 guestDevice Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class of the device. deviceId type: deviceId use: required Device identifier of the device; assigned by the EGM. deviceActive type: boolean use: required Indicates whether the device is active (true) or inactive (false). 8.14 commHostListAck Command This command is used by the host to acknowledge that the list of registered hosts has changed. The commHostListAck command is sent in response to the commHostList command. It is not expected that the EGM will wait indefinitely for the host to send this message. In the event that the EGM does not receive the commHostListAck before the noResponseTimer expires, the EGM MUST issue the event G2S_CCE106 commConfig Configuration Changes Applied. There are no additional attributes or elements for this command. 8.15 setCommChange Command This command is used by a host to send a set of comms configuration device changes to an EGM, and a list of hosts that must authorize the changes. The owner must be included in the list of hosts that must approve this change, and optionally a list of additional hosts. Only the owner of the comms configuration device may execute this command. The commChangeStatus command is sent in response to the setCommChange command. Upon receipt of a set of changes, the EGM MUST validate the set of changes. If the set of changes is incomplete, inaccurate, or otherwise cannot be applied by the EGM, the EGM MUST return the appropriate error to the host and reject the entire set. • Sets of changes that pass the EGM’s validation tests, and are accepted by the EGM, MUST be reported through the commConfig change log. • Sets of changes that fail the EGM’s validation, or are otherwise rejected by the EGM, MUST NOT be included in the commConfig change log. Page 310 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 Chapter 8 commConfig Class Attributes within the setCommChange command indicate when and under what conditions the set of changes MUST be applied. The applyCondition attribute indicates which method should be used, whether immediately, when the EGM is disabled, after an operator action at the EGM, or cancelled after validation. The disableCondition attribute indicates under what conditions the EGM MUST disable and apply a set of options, whether immediately, when there are 0 (zero) credits on the credit meter, or when the EGM is idle. This attribute is only used when the applyCondition is set to G2S_disable. The startDateTime and endDateTime attributes provide a window during which the set of changes MUST be applied. These attributes are only used when the applyCondition is set to G2S_disable. The restartAfter attribute is used with all applyCondition settings, and indicates whether the EGM MUST restart itself after applying the set of changes. If the EGM is unable to set the changes within the time window provided, then a G2S_CCE107 event is generated. CommConfig Configuration Aborted The EGM MUST validate the applyCondition, disableCondition, startDateTime, endDateTime, and restartAfter attributes to ensure that they meet the EGM jurisdictional and operational requirements. The EGM MUST reject a set of changes if the conditions under which the changes should be applied do not meet the EGM jurisdictional or operational requirements. When the configuration for a host is changed, the new attributes for the host, the list of owned devices and the list of guest devices overwrite any previous settings for the host. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 311 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 Table 8.12 setCommChange Attributes Attribute Restrictions Description configurationId type: configurationId use: required Identifier assigned by the host to the set of changes. applyCondition type: applyConditions use: required Condition under which the set of changes should be applied; immediately, after EGM is disabled, upon operator action at the EGM, or cancel options after EGM validation. disableCondition type: disableConditions use: optional default: G2S_none Condition for disabling the EGM; only when applyCondition is set to G2S_disable. If applyCondition is not set to G2S_disable, then this value should be set to G2S_none. startDateTime type: dateTime use: optional default: <null> Start date/time for applying the set of changes; only when applyCondition is G2S_disable. endDateTime type: dateTime use: optional default: <null> End date/time for applying the set of changes; only when applyCondition is G2S_disable. restartAfter type: boolean use: optional default: false Indicates whether the EGM MUST restart itself after applying the set of changes. Table 8.13 setCommChange Elements Element Restrictions Description setHostItem minOcc: 1 Contains information about an individual registered host. See Table 8.14 for attributes. See Table 8.8 for element details. maxOcc: authorizeList ∞ minOcc: 0 maxOcc: 1 Contains a list of hosts that must authorize the changes before they can occur. See Table 8.16 for Table 8.17. Table 8.14 setHostItem Attributes (Sheet 1 of 2) Attribute Restrictions Description hostIndex type: int use: required minIncl: 0 Internal index value for the host assigned by the EGM. hostId type: deviceId use: required Identifier assigned by the network administrator to the host. hostLocation type: transportLocation use: required URI or other identifier of the host; value may be blank if hostRegistered is set to false. hostRegistered type: boolean use: optional default: true Indicates whether the host should be a member of the list of registered hosts. useDefaultConfig type: boolean use: optional default: false Indicates whether the default configuration for the device MUST be used when the EGM restarts. Page 312 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 Table 8.14 setHostItem Attributes (Sheet 2 of 2) Attribute Restrictions Description requiredForPlay type: boolean use: optional default: false Indicates whether the EGM MUST be disabled if either egmEnabled or hostEnabled is set to false. timeToLive type: timeToLive use: optional default: 30000 Time-to-live value for requests originated by the device. noResponseTimer type: milliseconds use: optional default: 300000 The no-response timer used to determine whether an EGM has lost communications with a host. allowMulticast type: boolean use: optional default: false Indicates whether the host is authorized to send multicast messages; not required if hostRegistered is set to false. displayCommFault type: boolean use: optional default: false Indicates whether a communications fault message should be displayed if the communications channel is unavailable. Table 8.15 setHostItem Elements Element Restrictions Description ownedDevice minOcc: 0 Details about one device for which the host is registered as owner. See Table 8.9 for attributes. maxOcc: configDevice Details about one option configuration device for which the host is registered as the owner. See Table 8.10. minOcc: 0 maxOcc: guestDevice ∞ ∞ Details about one device for which the host is registered as guest. See Table 8.11 for attributes. minOcc: 0 maxOcc: ∞ Table 8.16 authorizeList Elements Element Restrictions Description authorizeItem minOcc: 1 Contains identifying information on a host that MUST authorize this change before it can occur. See attributes in Table 8.17. maxOcc: ∞ Table 8.17 authorizeItem Attributes Attribute Restrictions Description hostId type: deviceId use: required Host identifier of the host that must authorize this change before it can proceed. timeoutDate type: dateTime use: optional default: <null> Timeout date and time when the EGM should cease to wait for authorization from this host. timeoutAction type: timeoutActionTypes use: optional default: G2S_ignore Action that should occur when the EGM has timed out waiting for authorization from this host. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 313 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.16 cancelCommChange Command This command is used by a host to cancel a set of changes previously sent to an EGM. Only the owner of the comms configuration device may execute this command. The commChangeStatus command is sent in response to the cancelCommChange command. Until applied, validated sets of changes remain in a pending state on the EGM. It is possible for the host to query the EGM for pending changes using the getCommChangeLog command and then to cancel a set of changes before they are applied by using the cancelCommChange command. After being applied, affected options can be restored to their original values only by sending and applying a new set of changes. Table 8.18 cancelCommChange Attributes Attribute Restrictions Description configurationId type: configurationId use: required Configuration change identifier that the host assigned to the set of changes that are to be cancelled. transactionId type: transactionId use: required minIncl: 1 Transaction identifier that the EGM assigned to the set of changes to be cancelled. 8.17 authorizeCommChange Command This command is used by a host to authorize an EGM to apply a set of changes. The set of changes must be authorized by the owner host, and all additional required hosts before the EGM may apply them. A set of changes is applied according to the rules included with the set of changes. If an error occurs in response to the authorizeCommChange command, the set of changes MUST retain the same status as was in existence prior to the authorizeCommChange command. A commChangeStatus command is sent in response to the authorizeCommChange command. Table 8.19 authorizeCommChange Attributes Attribute Restrictions Description configurationId type: configurationId use: required Configuration change identifier that the host assigned to the set of changes it authorizes to be applied. transactionId type: transactionId use: required minIncl: 1 Transaction identifier that the EGM assigned to the set of changes that the host authorizes to be applied. Page 314 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.18 commChangeStatus Command This command is used by an EGM to report the status of a set of changes. • The commChangeStatus command is sent in response to setCommChange, authorizeCommChange, and commands. cancelCommChange • It is also sent whenever the status of a set of changes is updated by the EGM after the EGM has applied the changes. Table 8.20 commChangeStatus Attributes Attribute Restrictions Description configurationId type: configurationId use: required minIncl: 1 Configuration change identifier assigned to the set of changes by the host. transactionId type: transactionId use: required Transaction identifier assigned to the set of changes by the EGM. applyCondition type: applyConditions use: required Condition for applying the set of changes; immediately, upon EGM disable, upon local operator action, or cancel after validation. disableCondition type: disableConditions use: optional default: G2S_none Condition for disabling the EGM; only when applyCondition is set to G2S_disable. If applyCondition is not set to G2S_disable, then this value should be set to G2S_none. startDateTime type: dateTime use: optional default: <null> Start date/time for applying the set of changes; only when applyCondition is set to G2S_disable. endDateTime type: dateTime use: optional default: <null> End date/time for applying the set of changes; only when applyCondition is set to G2S_disable. restartAfter type: boolean use: optional default: false Indicates whether the EGM MUST restart itself after applying the set of changes. changeStatus type: changeStatus use: required Indicates the status of the set of changes. See A. changeDateTime type: dateTime use: required Date/time that the commChangeStatus was last updated. changeException type: commConfigExceptions use: optional default: 0 Exception code used to report the cause of an error condition. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 315 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 Table 8.21 commChangeStatus Elements Element Restrictions Description authorizeStatusList minOcc: 0 maxOcc: 1 Contains a list of hosts that MUST authorize the changes before they can occur. See elements in Table 8.22. Table 8.22 authorizeStatusList Elements Element Restrictions Description authorizeStatus minOcc: 1 Contains the authorization status of the device configuration changes. See attributes in Table 8.23. maxOcc: ∞ Table 8.23 authorizeStatus Attributes Attribute Restrictions Description hostId type: deviceId use: required Host identifier of the host that must authorize this change before it can proceed authorizationState type: authorizationStates use: required Indicates if the Authorization Host has authorized the script or if a timeout has occurred. timeoutDate type: dateTime use: optional default: <null> Timeout value for when the EGM should give up waiting on authorization from this host. 8.19 commChangeStatusAck Command This command is used by the host to acknowledge that the status of a set of changes has been applied by the EGM. The commChangeStatusAck command is sent in response to the commChangeStatus command Table 8.24 commChangeStatusAck Attributes Attribute Restrictions Description configurationId type: configurationId use: required Configuration change identifier assigned to the set of changes by the host. transactionId type: transactionId use: required minIncl: 1 Transaction identifier the EGM assigned to the set of changes. Page 316 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.20 getCommChangeLogStatus Command This command is used by the host to request the current status of the change log from an EGM, including the sequence number of the last transaction and the total number of transactions in the log. A commChangeLogStatus command is sent in response to a getCommChangeLogStatus command. The getCommChangeLogStatus element contains no additional attributes or elements. 8.21 commChangeLogStatus Command This command is used by the EGM to send the current status of the change log to a host. The commChangeLogStatus command is sent in response to the getCommChangeLogStatus command. Table 8.25 commChangeLogStatus Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional minIncl: 0 default: 0 The sequence number of the last transaction within the log. totalEntries type: int use: optional minIncl: 0 default: 0 The total number of transactions within the log. 8.22 getCommChangeLog Command This command is used by the host to request the change history log from an EGM. The commChangeLogList command is sent in response to the getCommChangeLog command. Additional information regarding the use of the lastSequence and totalEntries attributes can be found in Chapter 1. Table 8.26 getCommChangeLog Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional minIncl: 0 default: 0 The sequence number of the transaction that should be the first entry in the list; if set to 0 (zero) then default to the last transaction. totalEntries type: int Use: optional minIncl: 0 default: 0 The total number of transactions that should be included in the list; if set to 0 (zero) then default to all transactions. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 317 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.23 commChangeLogList Command This command is used by the EGM to send its communications configuration change history log to a host. The change history log contains a record of commConfig change requests. The commChangeLogList command is sent in response to the getCommChangeLog command. Table 8.27 commChangeLogList Elements Element Restrictions Description commChangeLog minOcc: 0 maxOcc: ∞ Contains information about a commConfig change request transaction. See attributes in Table 8.28 and elements in Table 8.29. Table 8.28 commChangeLog Attributes (Sheet 1 of 2) Attribute Restrictions Description logSequence type: logSequence use: required Indicates the sequence number of the transaction within the log; a monotonically increasing sequence. deviceId type: deviceId use: required Device identifier of the communications configuration device that generated the transaction. transactionId type: transactionId use: required minIncl: 1 Transaction identifier that the EGM assigned to the set of changes. configurationId type: configurationId use: required Configuration change identifier that the host assigned to the set of changes. applyCondition type: applyConditions use: required Condition for applying the set of changes; immediately, upon EGM disable, upon operator action at the EGM, or cancel options after validation. disableCondition type: disableConditions use: optional default: G2S_none Condition for disabling the EGM; only when applyCondition is set to G2S_disable. If applyCondition is not set to G2S_disable, then this value should be set to G2S_none. startDateTime type: dateTime use: optional default: <null> Start date/time for applying the set of changes; only when applyCondition is set to G2S_disable. endDateTime type: dateTime use: optional default: <null> End date/time for applying the set of changes; only when applyCondition is set to G2S_disable. restartAfter type: boolean use: optional default: false Indicates whether the EGM MUST restart itself after applying the set of changes. changeStatus type: changeStatus use: required Indicates the status of the set of changes: pending, authorized, cancelled, applied, or error detected. Page 318 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 Table 8.28 commChangeLog Attributes (Sheet 2 of 2) Attribute Restrictions Description changeDateTime type: dateTime use: required Date/time that the commChangeStatus was last updated. changeException type: commConfigExceptions use: optional default: 0 Exception code used to report the cause of an error condition. Table 8.29 commChangeLog Elements Element Restrictions Description authorizeStatusList minOcc: 0 maxOcc: 1 Contains a list of hosts that MUST authorize the changes before they can occur. See elements in Table 8.22. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 319 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.24 Data Types The following table lists the data types specific to the commConfig class: Table 8.30 commConfig Class Data Types Data Type Restrictions Description commConfigExceptions type: exceptionCode Change exception codes. See Table 8.31 for valid codes. 8.24.1 commConfigExceptions Enumerations (Exception Codes) The following table lists the valid exception codes for the commConfigExceptions data type: Table 8.31 Enumerations of the commConfigExceptions Data Type Exception Code Description 0 Command successful. 1 Apply window expired. 2 Error applying changes. 3 EGM must be disabled. 4 EGM must have zero credits. 5 EGM must be idle. 6 Host authorization timeout. Page 320 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.25 Error Codes The following table lists the error codes specific to the commConfig class: Table 8.32 commConfig Class Error Codes Error Code Suggested Error Text GSA_CCX001 Invalid Device Class/Device Identifier GSA_CCX002 EGM Must Be Disabled GSA_CCX003 EGM Must Be Idle GSA_CCX004 Transaction Identifier Already In Use GSA_CCX005 Invalid Transaction Identifier GSA_CCX006 Transaction Is Not Pending GSA_CCX007 Invalid Apply Condition GSA_CCX008 Invalid Disable Condition GSA_CCX009 Disable Condition Not Specified GSA_CCX010 Start/End Time Not Specified GSA_CCX011 No Registered Hosts GSA_CCX012 Invalid Host Identifier GSA_CCX013 Device Not Assigned To A Registered Host GSA_CCX014 Invalid Host Transport GSA_CCX015 Invalid Host Location gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 321 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.26 Event Codes The following table summarizes the events that may be generated by the communication configuration device. A full description of each event follows the table. Table 8.33 commConfig Class Event Codes (CC = commConfig, CB = cabinet) Affected Device Logs, Meters, Statuses Event Code and Event Title CC CB G2S_CCE001 commConfig Disabled by EGM S S G2S_CCE002 commConfig Enabled by EGM S G2S_CCE003 commConfig Changed by Host G2S_CCE004 commConfig Changed by Operator G2S_CCE101 commConfig Entered Configuration Mode S G2S_CCE102 commConfig Exited Configuration Mode S G2S_CCE103 commConfig Configuration Change Pending L G2S_CCE104 commConfig Configuration Authorized by Host L G2S_CCE105 commConfig Configuration Cancelled L G2S_CCE106 commConfig Configuration Changes Applied L G2S_CCE107 commConfig Configuration Aborted L G2S_CCE108 commConfig Error L G2S_CCE109 commConfig Configuration Waiting on Authorization L G2S_CCE110 commConfig Configuration Change Authorization Timeout L The following table lists the elements contained within the commConfig class which may be included as affected data with events: Table 8.34 Elements Included With Events Affected Data Element Device Status commConfigModeStatus Change Status commChangeStatus Transaction Record commChangeLog Page 322 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.26.1 evaluate(state) The egmEnabled and egmState attributes are both determined from multiple factors. If all of the faults for a device have been cleared then the egmEnabled attribute for the device can be set to true. If any one fault still exists then the egmEnabled attribute MUST be set to false. Thus, after a fault is cleared, the EGM MUST evaluate all of the attributes that contribute to the state of the egmEnabled attribute. If anyone of them shows a fault then the egmEnabled attribute MUST remain false. This is communicated in the following documentation by using the convention "evaluate(device.egmEnabled)". Likewise, the egmState attribute of the cabinetStatus reflects the aggregate state of all devices in the EGM. If the requiredForPlay attribute in the profile of a device is set to true then if either the egmEnabled or hostEnabled attribute of the device is set to false, the egmState MUST reflect that the EGM is disabled. Similarly, if the egmLocked or hostLocked attribute of a device is set to true then the egmState MUST reflect that the EGM is locked out. If any one device is in such a state then the egmState MUST reflect that the EGM is disabled or locked out, as appropriate. Thus, after a device has been enabled or a lockout has been cleared, the EGM MUST evaluate the state of all active devices within the EGM to determine the proper value of the egmState attribute. At the same time, the deviceClass and deviceId attributes of the cabinetStatus MUST be updated to reflect the appropriate device. This is communicated in the following documentation by using the convention "evaluate(cabinet.egmState)". 8.26.2 G2S_CCE001 commConfig Disabled by EGM This event is sent by the EGM after the comms configuration device has been disabled by the EGM. Table 8.35 G2S_CCE001 Device, Meter, Log Changes, and Related Commands Details Device State Changes commConfig.egmEnabled = "false" (however, all commands functional). evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 8.26.3 G2S_CCE002 commConfig Enabled by EGM This event is sent by the EGM after the comms configuration device has been enabled by the EGM. Table 8.36 G2S_CCE002 Device, Meter, Log Changes, and Related Commands Details Device State Changes commConfig.egmEnabled = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 323 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.26.4 G2S_CCE003 commConfig Changed by Host This event is sent by the EGM after the configuration options for the communication configuration device have been changed by the host via the optionConfig class. The event MUST be sent after the comms configuration device sends the commChangeStatus command. Table 8.37 G2S_CCE003 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands commChangeStatus 8.26.5 G2S_CCE004 commConfig Changed by Operator This event is sent by the EGM after the configuration options for the communication configuration device have been changed locally by an operator. The event MUST NOT be sent until the operator commits the changes or exits the operator menu of the EGM. Table 8.38 G2S_CCE004 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. 8.26.6 G2S_CCE101 commConfig Entered Configuration Mode Processing for this event begins in response to the enterCommConfigMode command from a host instructing the EGM to enter the communications configuration mode. This event should be sent when the EGM has entered the configuration mode. Table 8.39 G2S_CCE101 Device, Meter, Log Changes, and Related Commands Details Device State Changes commConfigModeStatus.enabled = "true". evanluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands enterCommConfigMode. Page 324 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 8.26.7 Chapter 8 commConfig Class G2S_CCE102 commConfig Exited Configuration Mode Processing for this event begins in response to the enterCommConfigMode command from a host instructing the EGM to enter the communications configuration mode. This event should be sent when the EGM has exited the configuration mode. Table 8.40 G2S_CCE102 Device, Meter, Log Changes, and Related Commands Details Device State Changes commConfigModeStatus.enabled = "false". evanluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands enterCommConfigMode. 8.26.8 G2S_CCE103 commConfig Configuration Change Pending This event is sent by the EGM after the configuration options, sent to the EGM in the setCommChange command, have been successfully validated. Table 8.41 G2S_CCE103 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Prior to sending this event, create and initialize a new log record. See Table 8.42. Related Commands None. Table 8.42 G2S_CCE103 Log State Changes – Create commChangeLog Attribute Set to Value ... logSequence Next value in series. deviceId The commConfig class deviceId associated with the setCommChange command. transactionId Next value in series. configurationId Next value in series. applyCondition The applyCondition associated with the setCommChange command. disableCondition The disableCondition associated with the setCommChange command. startDateTime The startDateTime associated with the setCommChange command. changeStatus Reset to either G2S_pending, or one of the possible states from the changeStatus type. changeDateTime Reset. changeException Reset. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 325 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.26.9 G2S_CCE104 commConfig Configuration Authorized by Host This event is sent by the EGM after the configuration options for the comms configuration device have been authorized by the host. Table 8.43 G2S_CCE104 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update commChangeLog and authorizeStatusList. See Table 8.44 and Table 8.45. Related Commands None. Table 8.44 G2S_CCE104 Log State Changes – Update commChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. changeStatus Set to G2S_authorized. changeDateTime Reset. changeException Reset. Table 8.45 G2S_CCE104 Log State Changes – Update authorizeStatus for Each Host Attribute Set to Value ... hostId deviceId authorizationState Current authorization state. timeoutDate Unchanged. Page 326 of authorizing host. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 8.26.10 Chapter 8 commConfig Class G2S_CCE105 commConfig Configuration Cancelled This event is sent by the EGM after the configuration options for the comms configuration device have been cancelled by the host. Table 8.46 G2S_CCE105 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update commChangeLog. See Table 8.47. Related Commands commChangeStatus. Table 8.47 G2S_CCE105 Log State Changes – Update commChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. changeStatus Set to G2S_cancelled. changeDateTime Date and time record was updated. changeException Unchanged. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 327 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.26.11 G2S_CCE106 commConfig Configuration Changes Applied This event is sent by the EGM after the communications configuration changes have been successfully applied by the EGM. Table 8.48 G2S_CCE106 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update commChangeLog to reflect current changeStatus. See Table 8.49. Related Commands enterCommConfigMode. Table 8.49 G2S_CCE106 Log State Changes – Update commChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. changeStatus Set to G2S_applied. changeDateTime Date and time record was updated. changeException Set to 0. Page 328 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 8.26.12 Chapter 8 commConfig Class G2S_CCE107 commConfig Configuration Aborted This event is sent by the EGM if the configuration options for the communication configuration device have been changed locally by an operator and the EGM contains pending changes from a host. This event is also sent if a set of validated changes exists, but have not been applied. Table 8.50 G2S_CCE107 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update commChangeLog. Related Commands commChangeStatus. Table 8.51 G2S_CCE107 Log State Changes – Update commChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. changeStatus Set to G2S_aborted. changeDateTime Date and time record was updated. changeException Set to 0. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 329 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.26.13 G2S_CCE108 commConfig Error This event is sent by the EGM after the communication configuration changes have resulted in an error condition. Table 8.52 G2S_CCE108 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update commChangeLog. See Table 8.53. Related Commands commChangeStatus. Table 8.53 G2S_CCE108 Log State Changes – Update commConfigLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. changeStatus Set to G2S_error. changeDateTime Date and time record was updated. changeException Set to the appropriate exception. Page 330 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 8.26.14 Chapter 8 commConfig Class G2S_CCE109 commConfig Configuration Waiting on Authorization This event is sent by the EGM after the parameters associated with a communication configuration change have been met, but the EGM must wait on the required hosts to authorize the configuration change. Table 8.54 G2S_CCE109 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update commChangeLog. See Table 8.55. Related Commands None. Table 8.55 G2S_CCE109 Log State Changes – Update commConfigLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. changeStatus Set to G2S_pending. changeDateTime Date and time record was updated. changeException Set to the appropriate exception. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 331 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.26.15 G2S_CCE110 commConfig Configuration Change Authorization Timeout This event is sent by the EGM after the communication configuration changes have timed out waiting for authorization from a specific host. Table 8.56 G2S_CCE110 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update commChangeLog and authorizeStatusList. See Table 8.57 and Table 8.58. Related Commands None. Table 8.57 G2S_CCE110 Log State Changes – Update commConfigLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. changeStatus Set to G2S_pending. changeDateTime Date and time record was updated. changeException Set to 6. Table 8.58 G2S_CCE110 Log State Changes – Update authorizeStatus for Each Host Attribute Set to Value ... hostId deviceId authorizationState Current authorization state. timeoutDate Unchanged. Page 332 of authorizing host. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.27 Examples The following diagram shows a typical communications startup sequence for a new connection to a communications configuration host. In the examples following figure, are examples of individual command request-response pairs and command sequences. HOST EGM EGM initializes and connects to commConfig host getCommHostList commHostList Host questions EGM for assigned and unassigned host Items EGM responds with registered host and open slots. Open slots appear as nonrepeating, non zero hostIndexes, with host id = 0 setCommChange Host transmits changes to EGM commChangeStatus EGM validates changes authorizeCommChange commChangeStatus commChangeStatus commChangeStatusAck All authorization hosts authorize changes. EGM sends response to authorization & applies changes when changes have been authorized by all authorization hosts. EGM also notifies this host of affected devices (for this host) gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 333 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.27.1 Host Lists EGM HOST getCommHostList commHostList The following examples illustrate the construction of a getCommHostList request command sent from a host to an EGM, followed by the commHostList response command sent from the EGM to the host: 8.27.1.1 getCommHostList: Host to EGM <commConfig deviceId = "0" dateTime = "2005-02-03T20:10:07.345-05:00" commandId = "2001" sessionId = "1001" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <getCommHostList /> </commConfig> Page 334 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 8.27.1.2 Chapter 8 commConfig Class commHostList: EGM to Host <commConfig deviceId = "0" dateTime = "2005-02-03T20:10:07.456-05:00" commandId = "3001" sessionId = "1001" sessionType = "G2S_response" > <commHostList> <commHostItem hostIndex = "1" hostId = "1" hostLocation = "config.casino.com:8080" hostRegistered = "true" allowMulticast = "false" canModLocal = "true" canModRemote = "true" > <ownedDevice deviceClass = "G2S_commConfig" deviceId = "0" deviceActive = "true" /> </commHostItem> <commHostItem hostIndex = "2" hostId = "2" hostLocation = "multiapp.casino.com:8080" allowMulticast = "false" canModLocal = "true" canModRemote = "true" > <ownedDevice deviceClass = "G2S_voucher" deviceId = "0" deviceActive = "true" /> <ownedDevice deviceClass = "G2S_WAT" deviceId = "0" deviceActive = "true" /> <configDevice deviceClass = "G2S_optionConfig" deviceId = "0" deviceActive = "true" /> <guestDevice deviceClass = "G2S_cabinet" deviceId = "0" deviceActive = "true" /> <guestDevice deviceClass = "G2S_player" deviceId = "0" deviceActive = "true" /> </commHostItem> <commHostItem hostIndex = "3" hostId = "0" hostLocation = "" allowMulticast = "false" canModLocal = "true" canModRemote = "true" /> <commHostItem hostIndex = "4" hostId = "0" hostLocation = "" allowMulticast = "false" canModLocal = "true" canModRemote = "true" /> </commHostList> </commConfig> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 335 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.27.2 Change commConfig Device HOST EGM setCommChange commChangeStatus authorizeCommChange commChangeStatus commChangeStatus commChangeStatusAck Host transmits changes to EGM EGM validates changes Host authorizes changes EGM sends response to authorization & applies changes EGM also notifies this host of affected devices (for this host) The examples in the following sections illustrate the construction of the setCommChange, commChangeStatus, authorizeCommChange, and commChangeStatusAck commands. Page 336 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 8.27.2.1 Chapter 8 commConfig Class setCommChange: Host to EGM <commConfig deviceId = "0" dateTime = "2005-02-03T20:10:10.567-05:00" commandId = "2002" sessionId = "1002" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <setCommChange configurationId = "00005" applyCondition = "G2S_disable" disableCondition = "G2S_idle" startDateTime = "2005-02-04T02:00:00.000-05:00" endDateTime = "2005-02-04T03:59:59.999-05:00" restartAfter = "true" > <setHostItem hostIndex= "2" hostId = "1" hostLocation = "multiapp.casino.com:8080" hostRegistered = "true" > <ownedDevice deviceClass = "G2S_voucher" deviceId = "0" deviceActive = "true" /> <ownedDevice deviceClass = "G2S_WAT" deviceId = "0" deviceActive = "true" /> <configDevice deviceClass = "G2S_optionConfig" deviceId = "0" deviceActive = "true" /> <guestDevice deviceClass = "G2S_cabinet" deviceId = "0" deviceActive = "true" /> <guestDevice deviceClass = "G2S_player" deviceId = "0" deviceActive = "true" /> </setHostItem> </setCommChange> </commConfig> 8.27.2.2 commChangeStatus: EGM to Host <commConfig deviceId = "0" dateTime = "2005-02-03T20:10:07.456-05:00" commandId = "3002" sessionId = "1002" sessionType = "G2S_response" > <commChangeStatus configurationId = "00005" transactionId="21" applyCondition = "G2S_disable" disableCondition = "G2S_idle" startDateTime = "2005-02-04T02:00:00.000-05:00" endDateTime = "2005-02-04T03:59:59.999-05:00" restartAfter = "true" changeStatus = "pending" changeException = "0" changeDateTime = "2005-02-04T03:59:59.999-05:00" /> </commConfig> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 337 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.27.2.3 authorizeCommChange: Host to EGM <commConfig deviceId = "0" dateTime = "2005-02-03T20:10:10.567-05:00" commandId = "2003" sessionId = "1003" sessionType = "G2S_request" timeToLive = "30000" sessionRetry = "0" > <authorizeCommChange configurationId = "00005" transactionId = "21" /> </commConfig> 8.27.2.4 commChangeStatus: EGM to Host <commConfig deviceId = "0" dateTime = "2005-02-03T20:10:11.456-05:00" commandId = "3003" sessionId = "1003" sessionType = "G2S_response" > <commChangeStatus configurationId = "00005" transactionId = "21" applyCondition = "G2S_disable" disableCondition = "G2S_idle" startDateTime = "2005-02-04T02:00:00.000-05:00" endDateTime = "2005-02-04T03:59:59.999-05:00" restartAfter = "true" changeStatus = "G2S_authorized" changeException = "0" changeDateTime = "2005-02-04T03:59:59.999-05:00" /> </commConfig> Page 338 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.28 Communication Configuration Device Option Configuration This section identifies the G2S-specified configuration option selections for communication configuration devices and provides an example of the optionItem element in Section 8.28.4. Configuration option selections are set using commands from the optionConfig class. The current configuration option selections for a communication configuration device are reported via the commConfigProfile command. Further descriptions of the sub-parameters can be found under the commConfigProfile command. 8.28.1 Option Group Definitions optionGroupId optionGroupName 8.28.2 G2S_commConfigOptions G2S Comm Config Options G2S Protocol Option Definitions optionId G2S_protocolOptions securityLevel G2S_administrator minSelections 1 maxSelections 1 duplicates Duplicate Key Parameter Type paramId 8.28.3 n/a n/a Complex G2S_protocolParams paramName G2S Protocol Parameters paramHelp Standard G2S protocol parameters for comm config devices G2S Protocol Option Sub-Parameter Definitions Table 8.59 G2S Protocol Option Sub-Parameter Definitions paramId paramName Example paramHelp G2S_configurationId Configuration Identifier 123456 ID assigned by the last successful G2S option configuration G2S_noResponseTimer No Response Timer 30000 Time to live value for optionListAck (in milliseconds) gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 339 Chapter 8 commConfig Class G2S™ Message Protocol v1.0.3 8.28.4 Example optionItem Elements in optionList The following are examples of optionItem elements used by the EGM to describe its configurable options for the communication configuration device. These elements are sent by the EGM to the host in the optionList command. // G2S Protocol Options <optionItem optionId = "G2S_protocolOptions" securityLevel = "G2S_administrator" minSelections = "1" maxSelections = "1" > <optionParameters> <complexParameter paramId = "G2S_protocolParams" paramName = "G2S Protocol Parameters" paramHelp = "Standard G2S protocol parameters for comm config devices" > <integerParameter paramId = "G2S_configurationId" paramName = "Configuration Identifier" paramHelp = "ID assigned by the last successful G2S option configuration" canModLocal = "false" canModRemote = "false" /> <integerParameter paramId = "G2S_noResponseTimer" paramName = "No Response Timer" paramHelp = "Time to live value for optionListAck (in milliseconds)" canModLocal = "true" canModRemote = "true" /> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 123456 </integerValue> <integerValue paramId = "G2S_noResponseTimer" >30000</integerValue> </complexValue> </optionCurrentValues> <optionDefaultValues> <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 123456 </integerValue> <integerValue paramId = "G2S_noResponseTimer" >30000</integerValue> </complexValue> </optionDefaultValues> </optionItem> Page 340 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 9 optionConfig Class 9.1 Introduction Chapter 9 optionConfig Class The optionConfig class is used to configure options available within an EGM. This class includes commands to change device-specific options excluding device ownerships. There is no requirement that an EGM support the optionConfig class. Alternatively, options covered by the optionConfig class can be set manually through the operator mode of the EGM; however, the optionConfig class provides a convenient and efficient mechanism to remotely configure EGMs. The optionConfig class is a multi-device class. Option configuration devices are assigned a device identifier that is the same as the host identifier assigned to the host. The deviceId of 0 (zero) is reserved for logs. Each host uses their option configuration device to submit option changes to the EGM. There can be only one host with configuration authority for each device within the EGM. The configuration host for each device within the EGM is identified via the configId in the descriptorList (see communications class, Chapter 2, for details). 9.2 optionConfig Overview The set of device-specific options that can be configured through the optionConfig class is defined within each G2S class. The standard options and any extensions to options are controlled by commands in the optionConfig class. A host uses the getOptionList command to obtain a list of current optionConfig settings from the EGM. This document assumes, however, that the EGM-exposed settings meet regulatory and customer expectations/requirements. Thus, before attempting to change the configuration of an EGM, a host system should query the EGM to discover which options the EGM supports and whether the host is able to change those options. Remotely changing the options of an EGM through this class is generalized in the diagram shown in Figure 9.1. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 341 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 Host sends changes to EGM EGM validates changes Pass EGM validation? No Yes Applicable host authorizes EGM to apply changes EGM sends Error code to Host EGM applies changes EGM does not apply changes End Figure 9.1 Remote Configuration Flow NOTE: The pass validation step includes checking for data that is incomplete, inconsistent or otherwise fails the EGM’s validation tests. If the host instructs the EGM to apply such invalid changes, the EGM MUST send an error to the host. Page 342 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 9.3 Chapter 9 optionConfig Class optionConfig Changes: Contents, Apply Conditions, and Sending Rules 9.3.1 Contents A set of changes MUST contain: • A transactionId used to uniquely identify the set of changes. It is included in all subsequent commands sent by the host or EGM related to the set of changes. It is assigned by the EGM and the EGM MUST generate a transactionId as a monotonically-increasing sequence. An error will occur if a host tries to authorize a set of changes with a transactionId that the EGM has retired or is not aware of. • An configurationId used to uniquely identify the set of changes from the host. It is included in all subsequent commands sent by the host or EGM related to the set of changes. It is assigned by the host for host tracking purposes. The EGM MUST persist the configurationId of the last successfully applied configuration change for each device so that it can be reported in subsequent messages describing the device (descriptorList, *Status, *Profile, optionList, and so on). 9.3.2 optionconfig Change Host Authorization The optionConfig class provides the ability for one or more hosts to authorize an option change before it occurs. This mechanism may be used by a host to read critical status, log, or meter data from an EGM before authorizing the option change to proceed. The change log contains a list of the hosts required to authorize the change so that a host may subscribe to the G2S_OCE103 optionConfig Configuration Change Pending and G2S_OCE109 optionConfig Configuration Waiting on Authorization events with the affected log included in the subscription. This allows a host to determine if it needs to authorize the device change based upon the event subscription. 9.3.3 Conditions Under Which Changes Can be Applied Following are the conditions under which the set of changes should be applied: • changes can be applied based on a command from the host, • changes can be applied based on an operator action at the EGM, • changes can be applied automatically during a specified time period, gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 343 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.3.4 Rules for Applying Changes That Are Sent The following rules apply to optionConfig changes sent to an EGM: • The EGM contains only one set of changes from each host at any time: • If a host sends a set of changes and the EGM already has a set of validated changes for that host, the previous set is overwritten with the most current set. • If the EGM contains a set of validated changes from a host that have not been activated and an operator manually changes any settings, all pending sets of changes are aborted and not applied. • Until the EGM receives an authorization from the host(s), the EGM must not apply a set of changes. • Until applied, a validated set of changes remains in a pending state on the EGM. • A host may cancel a set of changes before they are applied (as long as it was the initiator of that set of changes). • After a set of changes are applied, affected options can only be changed by either: • Page 344 • sending and applying a new set of changes or • operator action at the EGM After applying a set of changes, whether the changes were sent from a host system or the changes were entered locally at the EGM, the EGM MUST report the changes via an optionList command to hosts with configuration authority for the devices affected by the change. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.4 Option Groups and Option Items 9.4.1 Option Groups The optionConfig class has been designed so that it can be easily extended to meet the changing needs of manufacturers. Device options are organized into groups. Each device can have multiple groups of options associated with it. Some of these groups are defined by GSA and, thus, are common to all EGMs. Other groups are defined by individual EGM manufacturers. As the need arises, individual manufacturers may add their own option groups to control manufacturer-specific features. To avoid duplicate group identifiers, the group identifiers chosen for manufacturer-specific option groups MUST conform to G2S naming conventions for unique identifiers (see Section 1.11). The group identifiers MUST begin with the manufacturer’s GSA-assigned prefix followed by an underscore character. The group identifiers for all GSA-defined option groups begin with the prefix "G2S_". Each option is uniquely identified by the combination of deviceClass, deviceId, optionGroupId and optionId. • The option identifier, optionId, is specific to an option group. • The option group identifier, optionGroupId, is specific to a device class. It is possible that the same optionId and/or optionGroupId may appear in more than one device class. Thus, to avoid ambiguity, options MUST be fully referenced by deviceClass, deviceId, optionGroupId and optionId. 9.4.2 Option Items A host may query the EGM to discover which option items the EGM supports and the characteristics associated with option item. An optionItem is composed of three distinct groups of data: optionParameters, optionCurrentValues and optionDefaultValues. are used to define the set of parameters used in conjunction with an option. A single option may have a single parameter or many parameters associated with it. optionParameters optionCurrentValues are used to describe the current values of the parameters associated with an option. optionDefaultValues are used to describe the default values of the parameters associated with an option. Options are associated with: • Simple data types: integer, decimal, string or boolean or • Complex data types containing multiple simple data types Complex parameter structures can be represented by constructing complex data types from multiple other complex and simple data types. The optionParameters provide the definitions of the parameters associated with an option. These definitions include parameter name and help message attributes. Other attributes are used to define data-type-specific definitions such as the maximum and minimum values of the parameters. It is also possible to specify an enumeration list for a parameter. Each parameter is also assigned a parameter identifier, paramId. This identifier is used within the optionCurrentValues and optionDefaultValues to map a value to a parameter. The paramId is defined within the optionParameters and then used within the optionCurrentValues and optionDefaultValues to identify the set of attributes used to control the parameter setting. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 345 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.5 Default Configuration EGMs contain a default configuration for options that MUST be persisted. An attribute exists within this class to indicate whether the EGM must restart from its default configuration or from its last working configuration. All remote changes must be applied to the current working configuration. Only changes to the current working configuration are reported by the EGM in the optionList command. Page 346 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.6 Request-Response Pairs The following tables organize the commands contained within the optionConfig class into request-response pairs: Table 9.1 Commands Originated by EGM Request Response optionList optionListAck optionChangeStatus optionChangeStatusAck Table 9.2 Commands Originated by Host Request Response Owner Guest enterOptionConfigMode optionConfigModeStatus Yes No getOptionConfigModeStatus optionConfigModeStatus Yes Yes getOptionConfigProfile optionConfigProfile Yes Yes getOptionList optionList Yes Yes setOptionChange optionChangeStatus Yes No cancelOptionChange optionChangeStatus Yes No authorizeOptionChange optionChangeStatus Yes Yes getOptionChangeLogStatus optionChangeLogStatus Yes Yes getOptionChangeLog optionChangeLogList Yes Yes gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 347 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.7 enterOptionConfigMode Command This command is used by a host to lock the EGM from play and to control the configuration mode of an EGM. Only the owner of the device can execute this command. The optionConfigModeStatus command is sent in response to the enterOptionConfigMode command. When enabled, the EGM is placed into a mode that allows option configuration changes to execute. At the time this mode is enabled, the EGM MUST NOT allow game play on the EGM. Jurisdictional regulations and operator preferences will dictate when this command can be applied by the EGM. Changing the configuration mode on an EGM while the EGM is being played will probably not be permitted in most jurisdictions. For example, an EGM may apply the following logic when executing the enterOptionConfigMode command: 1. Wait for credit meter to reach 0 (zero). 2. Wait for the EGM to be idle according to the idleTimePeriod parameter configured in the cabinet class. 3. Apply the enterOptionConfigMode command to affect the optionConfigModeStatus.enabled attribute. 4. Generate event G2S_OCE101 optionConfig Entered Configuration Mode or G2S_OCE102 optionConfig Exited Configuration Mode, depending upon the value of the enabled attribute. The exact logic executed by the EGM for this command is dependent on the EGM's configuration and subject to jurisdictional regulations. Table 9.3 enterOptionConfigMode Attributes Attribute Restrictions Description enable type: boolean use: optional default: true Indicates whether the option configuration mode should be enabled or disabled. disableText type: textMessage use: optional default: <empty> Optional message to display while mode is enabled (and game play is disabled). 9.8 getOptionConfigModeStatus Command This command is used by a host to request the current status of the option configuration device from the EGM. The EGM sends an optionConfigModeStatus command in response to the getOptionConfigModeStatus command. The getOptionConfigModeStatus command has no additional attributes or elements. Page 348 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.9 optionConfigModeStatus Command This command is used by the EGM to send the current status of the option configuration device to a host. The optionConfigModeStatus command is sent in response to the enterOptionConfigMode and getOptionConfigModeStatus commands. Table 9.4 optionConfigModeStatus Attributes Attribute Restrictions Description configurationId type: configurationId use: optional default: 0 Configuration identifier set by the host. enabled type: boolean use: optional default: false Indicates whether the option configuration mode is enabled by the host. 9.10 getOptionConfigProfile Command This command is used by a host to request the profile information. The optionConfigProfile command is sent in response to the getOptionConfigProfile command. The getOptionConfigProfile element contains no additional attributes or elements. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 349 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.11 optionConfigProfile Command This command is used by an EGM to send the profile of the option configuration device to a host. The profile contains protocol-related configuration options selections for an option configuration device. The optionConfigProfile command is sent in response to the getOptionConfigProfile command. Table 9.5 optionConfigProfile Attributes Element Restrictions Description configurationId * type: configurationId use: optional default: 0 Last configuration identifier set by a G2S host; set to 0 (zero) when configuration changes are made by hosts other than G2S hosts. minLogEntries * Indicates the minimum number of log entries the EGM must maintain in persistent memory. noResponseTimer * type: milliseconds use: optional default: 300000 * 9.12 type: int use: optional minIncl: 1 default: 10 The time a device will wait for an optionListAck before determining the EGM has lost communications with the host. Standard configuration option that MUST be included in the standard option configuration group – G2S_optionConfigOptions – for devices within the optionConfig class. getOptionList Command This command is used by a host to request the list of device options and current settings from an EGM. The optionList command is sent in response to the getOptionList command. Table 9.6 getOptionList Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Used to specify a device class; wildcard G2S_all permitted. deviceId type: deviceId use: required Select a specific device within the device class; wildcard -1 is permitted. optionGroupId type: optionGroupId use: required Option group identifier. The wildcard G2S_all is permitted. optionId type: optionId use: required Option identifier. The wildcard G2S_all is permitted. optionDetail type: boolean use: required Indicates the level of detail an item should return in the response. If set to true, provide all details; otherwise, provide values only. Page 350 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13 optionList Command This command is used by the EGM to send a list of device options to a host. • The optionList command is sent in response to a getOptionList command. If the optionDetail flag is set to true in the getOptionList command, the optionParameters and optionDefaultValues elements must be returned in the optionList command response. • It is also sent to the hosts with configuration authority for the devices affected by the change whenever an option selection is changed by an operator. In this case, only the affected options MUST be sent. Options are divided into groups. Each group may contain multiple options. Each device may contain multiple groups of options. GSA defines certain standard option groups that are common to all EGMs. Other groups can be defined by individual manufacturers to meet their unique requirements. The device options available for an EGM are determined by the EGM. A host cannot change the list of options that are available, only the option settings. The canModLocal and canModRemote attributes indicate where changes can be performed. • If there is no prohibition against local changes, then the canModLocal attribute MUST be set to • Likewise, if there is no prohibition against remote changes, then the canModRemote attribute MUST be set to true. true. The optionList command contains no attributes and only one element, described in the table below. Table 9.7 optionList Elements Element Restrictions Description deviceOptions minOcc: 0 Contains the options for a device. See Section 9.13.1. maxOcc: ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 351 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.1 deviceOptions Table 9.8 deviceOptions Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class of the device. deviceId type: deviceId use: required Device identifier of the device; assigned by the EGM. Table 9.9 deviceOptions elements Element Restrictions Description optionGroup minOcc: 0 Contains the information about an individual option group. See Section 9.13.2. maxOcc: 9.13.2 ∞ optionGroup Table 9.10 optionGroup Attributes Attribute Restrictions Description optionGroupId type: optionGroupId use: required Option group identifier. optionGroupName type: optionGroupName use: optional default: <empty> Description of the option group. Table 9.11 optionGroup elements Element Restrictions Description optionItem minOcc: 0 Contains the information about an individual option. See Section 9.13.3. maxOcc: Page 352 ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.3 optionItem Table 9.12 optionItem Attributes Attribute Restrictions Description optionId type: optionId use: required Option identifier. securityLevel type: securityLevels use: required Security level required to modify the option. minSelections type: int use: optional default: 1 minIncl: 0 Minimum number of selections required. maxSelections type: int use: optional default: 1 minIncl: 1 Maximum number of selections allowed. duplicates type: boolean use: optional default: false Indicates whether duplicate selections are allowed. Table 9.13 optionItem Elements Element Restrictions Description optionParameters minOcc: 0 maxOcc: 1 Contains the option parameter specifics for the type of option. See Section 9.13.4. optionCurrentValues minOcc: 1 maxOcc: 1 List of current value(s) for the option. See Section 9.13.10. optionDefaultValues minOcc: 0 maxOcc: 1 List of default value(s) for the option. See Section 9.13.11. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 353 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.4 optionParameters NOTE: These elements are a choice. Table 9.14 optionParameters Elements Element Restrictions Description integerParameter minOcc: 1 maxOcc: 1 Contains the parameters for an option of type long. See Section 9.13.5. decimalParameter minOcc: 1 maxOcc: 1 Contains the parameters for an option of type decimal. See Section 9.13.6. stringParameter minOcc: 1 maxOcc: 1 Contains the parameters for an option of type string. See Section 9.13.7. booleanParameter minOcc: 1 maxOcc: 1 Contains the parameters for an option of type boolean. See Section 9.13.8. complexParameter minOcc: 1 maxOcc: 1 Contains the parameters for a complex option. See Section 9.13.9. Page 354 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.5 integerParameter Table 9.15 integerParameter Attributes Attribute Restrictions Description paramId type: paramId use: required Option parameter identifier. paramName type: optionName use: optional default: <empty> Parameter name. paramHelp type: egmMessage use: optional default: <empty> Parameter help message. paramKey type: boolean use: optional default: false Indicates whether the parameter is a component of the unique key for an option selection. Only applicable when maxSelections is set to a value greater than 1 (one). Can be used by the host to identify and prevent duplicate option selections. canModLocal type: boolean use: optional default: false Indicates whether the parameter can be changed locally at the EGM. canModRemote type: boolean use: optional default: false Indicates whether the parameter can be changed remotely via the option configuration device. minIncl type: long use: optional default: 0 Minimum value allowed. maxIncl type: long use: optional default: <null> Maximum value allowed. <null> implies no maximum. Table 9.16 integerParameter Elements Element Restrictions Description integerEnum type: long minOcc: 0 Allowed values for the option. maxOcc: ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 355 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.6 decimalParameter Table 9.17 decimalParameter Attributes Attribute Restrictions Description paramId type: paramId use: required Option parameter identifier. paramName type: optionName use: optional default: <empty> Parameter name. paramHelp type: egmMessage use: optional default: <empty> Parameter help message. paramKey type: boolean use: optional default: false Indicates whether the parameter is a component of the unique key for an option selection. Only applicable when maxSelections is set to a value greater than 1 (one). Can be used by the host to identify and prevent duplicate option selections. canModLocal type: boolean use: optional default: false Indicates whether the parameter can be changed locally at the EGM. canModRemote type: boolean use: optional default: false Indicates whether the parameter can be changed remotely via the option configuration device. minIncl type: decimal use: optional default: 0 Minimum value allowed. maxIncl type: decimal use: optional default: <null> Maximum value allowed. <null> implies no maximum. fracDig type: int use: optional default: 0 minIncl: 0 Maximum number of fractional decimal places. Table 9.18 decimalParameter Elements Element Restrictions Description decimalEnum type: decimal minOcc: 0 Allowed values for the option. maxOcc: Page 356 ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.7 stringParameter Table 9.19 stringParameter Attributes Attribute Restrictions Description paramId type: paramId use: required Option parameter identifier. paramName type: optionName use: optional default: <empty> Parameter name. paramHelp type: egmMessage use: optional default: <empty> Parameter help message. paramKey type: boolean use: optional default: false Indicates whether the parameter is a component of the unique key for an option selection. Only applicable when maxSelections is set to a value greater than 1 (one). Can be used by the host to identify and prevent duplicate option selections. canModLocal type: boolean use: optional default: false Indicates whether the parameter can be changed locally at the EGM. canModRemote type: boolean use: optional default: false Indicates whether the parameter can be changed remotely via the option configuration device. minLen type: int use: optional default: 0 minIncl: 0 Minimum string length allowed. maxLen type: int use: optional default: 64 minIncl: 0 Maximum string length allowed. Table 9.20 stringParameter Elements Element Restrictions Description stringEnum type: string minOcc: 0 Allowed values for the option. maxOcc: ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 357 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.8 booleanParameter Table 9.21 booleanParameter Attributes Attribute Restrictions Description paramId type: paramId use: required Option parameter identifier. paramName type: optionName use: optional default: <empty> Parameter name. paramHelp type: egmMessage use: optional default: <empty> Parameter help message. paramKey type: boolean use: optional default: false Indicates whether the parameter is a component of the unique key for an option selection. Only applicable when maxSelections is set to a value greater than 1 (one). Can be used by the host to identify and prevent duplicate option selections. canModLocal type: boolean use: optional default: false Indicates whether the parameter can be changed locally at the EGM. canModRemote type: boolean use: optional default: false Indicates whether the parameter can be changed remotely via the option configuration device. Page 358 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.9 complexParameter The sub-elements in the complexParameter element are identical to the elements within optionParameters, including a complexParameter sub-element which allows the definition of complex parameters within complex parameters, and for parameters of mixed data types. Table 9.22 complexParameter Attributes Attribute Restrictions Description paramId type: paramId use: required Option parameter identifier. paramName type: optionName use: optional default: <empty> Parameter name. paramHelp type: egmMessage use: optional default: <empty> Parameter help message. paramKey type: boolean use: optional default: false Indicates whether the parameter is a component of the unique key for an option selection. Only applicable when maxSelections is set to a value greater than 1 (one). Can be used by the host to identify and prevent duplicate option selections. Table 9.23 complexParameters Elements Element Restrictions Description integerParameter minOcc: 1 maxOcc: 1 Contains the parameters for an option of type long. See Section 9.13.5. decimalParameter minOcc: 1 maxOcc: 1 Contains the parameters for an option of type decimal. See Section 9.13.6. stringParameter minOcc: 1 maxOcc: 1 Contains the parameters for an option of type string. See Section 9.13.7. booleanParameter minOcc: 1 maxOcc: 1 Contains the parameters for an option of type boolean. See Section 9.13.8. complexParameter minOcc: 1 maxOcc: 1 Contains the parameters for a complex option. See Section 9.13.9. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 359 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.10 optionCurrentValues NOTE: These elements are a choice. Table 9.24 optionCurrentValues Elements Element Restrictions Description integerValue minOcc: 0 Value(s) of type long for the option. See attributes in Table 9.25. maxOcc: decimalValue Value(s) of type decimal for the option. See attributes in Table 9.25. minOcc: 0 maxOcc: stringValue ∞ ∞ Value(s) of type string for the option. See attributes in Table 9.25. minOcc: 0 maxOcc: booleanValue Value(s) of type boolean for the option. See attributes in Table 9.25. minOcc: 0 maxOcc: complexValue ∞ ∞ Complex value(s) for the option. See attributes in Table 9.25. minOcc: 0 maxOcc: ∞ Table 9.25 integerValue, decimalValue, stringValue, booleanValue and complexValue Attributes Attribute Restrictions Description paramId type: paramId use: required Option parameter identifier. Page 360 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.13.11 optionDefaultValues NOTE: These elements are a choice. Table 9.26 optionCurrentValues Elements Element Restrictions Description integerValue minOcc: 0 Value(s) of type long for the option. See attributes in Table 9.25. maxOcc: decimalValue minOcc: 0 maxOcc: stringValue ∞ minOcc: 0 maxOcc: complexValue ∞ minOcc: 0 maxOcc: booleanValue ∞ ∞ minOcc: 0 maxOcc: ∞ Value(s) of type decimal for the option. See attributes in Table 9.25. Value(s) of type string for the option. See attributes in Table 9.25. Value(s) of type boolean for the option. See attributes in Table 9.25. Complex value(s) for the option. See attributes in Table 9.25. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 361 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.14 optionListAck Command This command is used by the host to acknowledge that the list of options has changed. The optionListAck command is sent in response to the optionList command. It is not expected that the EGM will wait indefinitely for the host to send this message. In the event that the EGM does not receive the optionListAck before the noResponseTimer expires, the EGM MUST issue the event G2S_OCE106 optionConfig Configuration Change Applied and apply the changes to the EGM. There are no additional attributes or elements for this command. 9.15 setOptionChange Command This command is used by a host to send a set of option changes to an EGM, along with a list of hosts that must authorize the changes. The initiating host must be included in the list of hosts that must approve this change, and optionally a list of additional hosts. Only the host with configuration authority for a device may specify option changes for that device. The optionChangeStatus command is sent in response to the setOptionChange command. Individual options may be constructed from one or more parameters. These parameters may be simple or complex and may form a list of option selections. However, whenever an option is changed, it is the option itself that is being changed. This means that the complete set of parameters that define the option MUST be included in the setOptionChange command. A single parameter cannot be changed without specifying the complete set of parameters for the option being changed. The setOptionChange command is used to change an option—the full set of parameters for the option MUST be included. The canModRemote attribute indicates whether the host can change the value of a parameter. If set to false, the host MUST NOT change the value of the parameter. If such a parameter change is attempted by the host, the EGM MUST reject the change request using error G2S_OCX015 Non-Modifiable Parameter Change Requested By Host. Upon receipt of a set of changes, the EGM MUST validate the set of changes. If the set of changes is incomplete, inaccurate, or otherwise cannot be applied by the EGM, the EGM MUST return an error to the host and reject the entire set. Because it may be difficult to determine which option caused the error, a host may choose to only include a limited number of options in each command. • Sets of changes that pass the EGM’s validation tests, and are accepted by the EGM, MUST be reported through the optionConfig change log. • Sets of changes that fail the EGM’s validation, or are otherwise rejected by the EGM, MUST NOT be included in the optionConfig change log. Attributes within the setOptionChange command indicate when and under what conditions the set of changes MUST be applied. The applyCondition attribute indicates which method should be used, whether options should be applied immediately, after EGM disable, after operator action at the EGM, or cancelled after EGM validation. The disableCondition attribute is used only when the applyCondition is set to G2S_disable and indicates under what conditions the EGM MUST be disabled and the set of options applied, whether immediately, when there are zero credits on the credit meter, or after the EGM is idle. Page 362 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 The startDateTime and endDateTime attributes provide a date/time window during which the set of changes MUST be applied. These attributes are only used when the applyCondition is set to G2S_disable. The restartAfter attribute is used with all applyConditions. This attribute indicates whether the EGM MUST restart itself after applying the set of changes. If the EGM is unable to set the changes within the time window provided, then a G2S_OCE107 Configuration Aborted event is generated. optionConfig Like any options sent to the EGM, the EGM MUST validate the applyCondition, disableCondition, startDateTime, endDateTime, and restartAfter attributes to make sure that they meet jurisdictional and operational requirements of the EGM. The EGM MUST reject a set of changes if the conditions under which the changes should be applied do not meet the jurisdictional or operational requirements of the EGM. Table 9.27 setOptionChange Attributes Attribute Restrictions Description configurationId type: configurationId use: required Configuration change identifier assigned to the set of changes by the host. applyCondition type: applyConditions use: required Condition under which to apply the set of changes; immediately, upon EGM disable, after operator action at EGM, or cancel after EGM validation. disableCondition type: disableConditions use: optional default: G2S_none Condition under which to disable the EGM; used only when applyCondition is G2S_disable. If applyCondition is not set to G2S_disable, then this value should be set to G2S_none. startDateTime type: dateTime use: optional default: <null> Start date/time for applying the set of changes; used only when applyCondition is G2S_disable. endDateTime type: dateTime use: optional default: <null> End date/time for applying the set of changes; used only when applyCondition is G2S_disable. restartAfter type: boolean use: optional default: false Indicates whether the EGM MUST restart itself after applying the set of changes. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 363 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 Table 9.28 setOptionChange Elements Element Restrictions Description option minOcc: 0 Contains information about an individual option selection. See Section 9.15.1. maxOcc: authorizeList 9.15.1 ∞ Contains a list of hosts that MUST authorize the changes before they can occur. See Section 9.15.2. minOcc: 0 maxOcc: 1 option Table 9.29 option Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class. deviceId type: deviceId use: required Device identifier. optionGroupId type: optionGroupId use: required Option group identifier. optionId type: optionId use: required Option identifier. Table 9.30 option Elements Element Restrictions Description optionCurrentValues minOcc: 1 maxOcc: 1 List of current value(s) for the option. The sub-elements of this element are identical to those of the optionCurrentValues element. See Section 9.13.10 for details. 9.15.2 authorizedList Table 9.31 authorizedList Elements Element Restrictions Description authorizeItem minOcc: 0 Contains identifying information on a host that MUST authorize this change before it can occur. maxOcc: ∞ Table 9.32 authorizeItem Attributes Attribute Restrictions Description hostId type: deviceId use: required Host identifier of the host that must authorize this change before it can proceed. timeoutDate type: dateTime use: optional default: <null> Timeout value. Indicates when the EGM should give up waiting on authorization from this host. timeoutAction type: timeoutActionTypes use: optional default: G2S_ignore Action that should occur when the EGM has timed out waiting on authorization from this host. Page 364 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.16 cancelOptionChange Command This command is used by a host to cancel a set of option changes that it previously sent to an EGM. Only the owner of the option configuration device via which the changes were sent to the EGM may execute this command. The optionChangeStatus command is sent in response to the cancelOptionChange command. Until applied, validated sets of changes remain in a pending state on the EGM. It is possible for the host to query the EGM for pending changes and to cancel a set of changes it initiated before they are applied. Once applied, affected options can only be restored to their original values by sending and applying a new set of changes. Table 9.33 cancelOptionChange Attributes Attribute Restrictions Description configurationId type: configurationId use: required Configuration change identifier assigned to the set of changes by the host. transactionId type: transactionId use: required minIncl: 1 Transaction identifier assigned to the set of changes by the EGM. 9.17 authorizeOptionChange Command This command is used by a host to authorize an EGM to apply a set of changes. The set of changes must be authorized by the owner host, and all additional required hosts, before the EGM may apply them. All sets of changes must be authorized before the EGM may apply them. A set of changes is applied according to the rules included with the set of changes. If an error occurs in response to the authorizeOptionChange command, the set of changes MUST retain the same status as was in existence prior to the authorizeOptionChange command. A optionChangeStatus command is sent in response to the authorizeOptionChange command. Table 9.34 authorizeOptionChange Attributes Attribute Restrictions Description configurationId type: configurationId use: required Configuration change identifier assigned to the set of changes by the host. transactionId type: transactionId use: required minIncl: 1 Transaction identifier assigned to the set of changes by the EGM. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 365 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.18 optionChangeStatus Command This command is used by an EGM to report the status of a set of option changes. • The optionChangeStatus command is sent in response to setOptionChange, and cancelOptionChange commands. authorizeOptionChange, • It is also sent when the status of the changes has been updated to its terminal state. Table 9.35 optionChangeStatus Attributes Attribute Restrictions Description configurationId type: configurationId use: required Configuration change identifier assigned to the set of changes by the host. transactionId type: transactionId use: required minIncl: 1 Transaction identifier assigned to the set of changes by the EGM. applyCondition type: applyConditions use: required Condition under which the set of changes should be applied; immediately, after EGM disable, after operator action at the EGM, cancel after EGM validation. disableCondition type: disableConditions use: required default: G2S_none Condition under which the EGM should disable; use only when applyCondition is set to G2S_disable. If applyCondition is not set to G2S_disable, then this value should be set to G2S_none. startDateTime type: dateTime use: optional default: <null> Start date/time for applying the set of changes; use only when applyCondition is set to G2S_disable. endDateTime type: dateTime use: optional default: <null> End date/time for applying the set of changes; use only when applyCondition is set to G2S_disable. restartAfter type: boolean use: optional default: false Indicates whether the EGM MUST restart itself after applying the set of changes. changeStatus type: changeStatus use: required Indicates the status of the set of changes. See Appendix A. changeDateTime type: dateTime use: required Date time that the optionChangeStatus was last updated. changeException type: optionConfigExceptions use: optional default: 0 Exception code used to report the cause of an error condition. Page 366 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 Table 9.36 optionChangeStatus Elements Element Restrictions Description authorizeStatusList minOcc: 0 maxOcc: 1 Contains a list of hosts that MUST authorize the changes before they can occur. See Table 9.37. Table 9.37 authorizeStatusList Elements Element Restrictions Description authorizeStatus minOcc: 1 maxOcc: ∞ Contains the authorization status of the device configuration changes. See attributes in Table 9.38. Table 9.38 authorizeStatus Attributes Attribute Restrictions Description hostId type: deviceId use: required Device identifier assigned to the host that must authorize the change before it can proceed. authorizationState type: authorizationStates use: required Indicates whether the host has authorized the changes. timeoutDate type: dateTime use: optional default: <null> Timeout value for when the EGM should give up waiting on authorization from this host. 9.19 optionChangeStatusAck Command This command is used by the host to acknowledge that the status of a set of changes has been applied by the EGM. The optionChangeStatusAck command is sent in response to the optionChangeStatus command. Table 9.39 optionChangeStatusAck Attributes Attribute Restrictions Description configurationId type: configurationId use: required Configuration change identifier assigned to the set of changes by the host. transactionId type: transactionId use: required minIncl: 1 Transaction identifier assigned to the set of changes by the EGM. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 367 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.20 getOptionChangeLogStatus Command This command is used by the host to request the current status of the change log from an EGM, including the sequence number of the last transaction and the total number of transactions in the log. A optionChangeLogStatus command is sent in response to a getOptionChangeLogStatus command. This command contains no additional attributes or elements. 9.21 optionChangeLogStatus Command This command is used by the EGM to send the current status of the transaction log to a host. The optionChangeLogStatus command is sent in response to the getOptionChangeLogStatus command. Table 9.40 optionChangeLogStatus Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional minIncl: 0 default: 0 The sequence number of the last transaction within the log. totalEntries type: int use: optional minIncl: 0 default: 0 The total number of transactions within the log. 9.22 getOptionChangeLog Command This command is used by the host to request the contents of a transaction log from an EGM. Additional information regarding the use of the lastSequence and totalEntries attributes can be found in Chapter 1. The optionChangeLogList command is sent in response to the getOptionChangeLog command. Table 9.41 getOptionChangeLog Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional minIncl: 0 default: 0 The sequence number of the transaction that should be the first entry in the list; if set to 0 (zero) then default to the last transaction. totalEntries type: int Use: optional minIncl: 0 default: 0 The total number of transactions that should be included in the list; if set to 0 (zero) then default to all transactions. Page 368 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.23 optionChangeLogList Command This command is used by the EGM to send the contents of the transaction log to a host. The change history log contains a record of option configuration device change requests. The optionChangeLogList command is sent in response to the getOptionChangeLog command. Table 9.42 optionChangeLogList Elements Element Restrictions Description optionChangeLog minOcc: 0 maxOcc: ∞ Contains information about a specific transaction. See Section Table 9.43 and Table 9.44. Table 9.43 optionChangeLog Attributes (Sheet 1 of 2) Attribute Restrictions Description logSequence type: logSequence use: required Unique log sequence number assigned by the EGM. deviceId type: deviceId use: required Device identifier of the device that generated the transaction. transactionId type: transactionId use: required minIncl: 1 Unique transaction identifier assigned by the EGM. configurationId type: configurationId use: required Configuration change identifier assigned by the host to the set of changes. applyCondition type: applyConditions use: required Condition under which the set of changes should be applied; immediately, after EGM disable, after operator action at the EGM, cancel after EGM validation. disableCondition type: disableConditions use: optional default: G2S_none Condition under which the EGM should disable; use only when applyCondition is set to G2S_disable. startDateTime type: dateTime use: optional default: <null> Start date/time for applying the set of changes; use only when applyCondition is set to G2S_disable. endDateTime type: dateTime use: optional default: <null> End date/time for applying the set of changes; use only when applyCondition is set to G2S_disable. restartAfter type: boolean use: optional default: false Indicates whether the EGM MUST restart itself after applying the set of changes. changeStatus type: changeStatus use: required Indicates the status of the set of changes: pending, authorized, cancelled, applied, or error. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 369 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 Table 9.43 optionChangeLog Attributes (Sheet 2 of 2) Attribute Restrictions Description changeDateTime type: dateTime use: required Date time that the optionChangeStatus was last updated. changeException type: optionConfigExceptions use: optional default: 0 Exception code used to report the cause of an error condition. Table 9.44 optionChangeLog Elements Element Restrictions Description authorizeStatusList minOcc: 0 maxOcc: 1 Contains a list of hosts that MUST authorize the changes before they can occur. The details about this element are described in Table 9.37 and Table 9.38. Page 370 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.24 Data Types The following table lists the data types specific to the optionConfig class: Table 9.45 optionConfig Class Data Types Data Type Restrictions Description optionConfigExceptions type: exceptionCode Change exception codes. See Section 9.24.1. optionGroupId type: extensibleList enumerations: G2S_all Option group identifier; prefixed by GSA-assigned manufacturer identifier. optionGroupName type: string minLen: 0 maxLen: 64 Option group description. optionId type: extensibleList enumerations: G2S_all Option identifier within an option group. optionName type: string minLen: 0 maxLen: 64 Option description. securityLevels type: string enumerations: G2S_attendant G2S_operator G2S_administrator Option security level. paramId type: uniqueIdentifier64 Option parameter identifier. 9.24.1 optionConfigExceptions: Change Exception Codes The following table lists the valid exception codes for the optionConfigExceptions data type: Table 9.46 optionConfigExceptions Enumerations Exception Code Description 0 Command successful. 1 Apply window expired. 2 Error applying option changes. 3 EGM must be disabled. 4 EGM must have zero credits. 5 EGM must be idle. 6 Host authorization timeout. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 371 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.25 Error Codes The following table lists the error codes specific to the optionConfig class: Table 9.47 optionConfig Class Error Codes Error Code Suggested Error Text G2S_OCX001 Invalid Device Class/Device Identifier G2S_OCX002 EGM Must Be Disabled G2S_OCX003 EGM Must Be Idle G2S_OCX004 Transaction Identifier Already In Use G2S_OCX005 Invalid Transaction Identifier G2S_OCX006 Transaction Is Not Pending G2S_OCX007 Invalid Apply Condition G2S_OCX008 Invalid Disable Condition G2S_OCX009 Disable Condition Not Specified G2S_OCX010 Start/End Time Not Specified G2S_OCX011 Invalid Option Group For Device Class G2S_OCX012 Invalid Option For Option Group G2S_OCX013 Invalid Value Selected For Option G2S_OCX014 Invalid paramId For Option G2S_OCX015 Non-Modifiable Parameter Change Requested By Host Page 372 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.26 Event codes The following table summarizes the events that may be generated the optionConfig class. A full description of each event follows the table. Table 9.48 optionConfig Class Event Codes (OC = optionConfig, CB = cabinet) Affected Device Logs, Meters, Statuses Event Code and Event Title OC CB G2S_OCE001 optionConfig Disabled by EGM S S G2S_OCE002 optionConfig Enabled by EGM S G2S_OCE003 optionConfig Configuration Changed by Host G2S_OCE004 optionConfig Configuration Changed by Operator G2S_OCE101 optionConfig Entered Configuration Mode S G2S_OCE102 optionConfig Exited Configuration Mode S G2S_OCE103 optionConfig Configuration Change Pending L G2S_OCE104 optionConfig Configuration Authorized by Host L G2S_OCE105 optionConfig Configuration Cancelled L G2S_OCE106 optionConfig Configuration Change Applied L G2S_OCE107 optionConfig Configuration Aborted L G2S_OCE108 optionConfig Error L G2S_OCE109 optionConfig Configuration Waiting on Authorization L G2S_OCE110 optionConfig Configuration Change Authorization L Timeout The following table lists the elements contained within the optionConfig class which may be included as affected data with events: Table 9.49 Elements Included With Events Affected Data Element Device Status optionConfigModeStatus Change Status optionChangeStatus Transaction Record optionChangeLog gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 373 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.26.1 evaluate(state) The egmEnabled and egmState attributes are both determined from multiple factors. If all of the faults for a device have been cleared then the egmEnabled attribute for the device can be set to true. If any one fault still exists then the egmEnabled attribute MUST be set to false. Thus, after a fault is cleared, the EGM MUST evaluate all of the attributes that contribute to the state of the egmEnabled attribute. If anyone of them shows a fault then the egmEnabled attribute MUST remain false. This is communicated in the following documentation by using the convention "evaluate(device.egmEnabled)". Likewise, the egmState attribute of the cabinetStatus reflects the aggregate state of all devices in the EGM. If the requiredForPlay attribute in the profile of a device is set to true then if either the egmEnabled or hostEnabled attribute of the device is set to false, the egmState MUST reflect that the EGM is disabled. Similarly, if the egmLocked or hostLocked attribute of a device is set to true then the egmState MUST reflect that the EGM is locked out. If any one device is in such a state then the egmState MUST reflect that the EGM is disabled or locked out, as appropriate. Thus, after a device has been enabled or a lockout has been cleared, the EGM MUST evaluate the state of all active devices within the EGM to determine the proper value of the egmState attribute. At the same time, the deviceClass and deviceId attributes of the cabinetStatus MUST be updated to reflect the appropriate device. This is communicated in the following documentation by using the convention "evaluate(cabinet.egmState)". 9.26.2 G2S_OCE001 optionConfig Disabled by EGM This event is sent by the EGM after option configuration device has been disabled by the EGM. Table 9.50 G2S_OCE001 Device, Meter, Log Changes, and Related Commands Details Device State Changes optionConfig.egmEnabled = "false" (however, all commands functional). evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 9.26.3 G2S_OCE002 optionConfig Enabled by EGM This event is sent by the EGM after the option configuration device has been enabled by the EGM. Table 9.51 G2S_OCE002 Device, Meter, Log Changes, and Related Commands Details Device State Changes optionConfig.egmEnabled = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. Page 374 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 9.26.4 Chapter 9 optionConfig Class G2S_OCE003 optionConfig Configuration Changed by Host This event is sent by the EGM after the configuration options for the option configuration device have been changed by the host via the optionConfig class. The event MUST be sent after the optionChangeStatus command is sent by the option configuration device. Table 9.52 G2S_OCE003 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands optionChangeStatus. 9.26.5 G2S_OCE004 optionConfig Configuration Changed by Operator This event is sent by the EGM after the configuration options for the option configuration device have been changed locally by an operator. The event MUST NOT be sent until the operator commits the changes or exits the operator menu of the EGM. Table 9.53 G2S_OCE004 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes None. Related Commands None. 9.26.6 G2S_OCE101 optionConfig Entered Configuration Mode Processing for this event begins in response to the enterOptionConfigMode command from a host instructing the EGM to enter the option configuration mode. This event should be sent after the EGM has entered the configuration mode. Table 9.54 G2S_OCE101 Device, Meter, Log Changes, and Related Commands Details Device State Changes optionConfigModeStatus.enabled = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands enterOptionConfigMode. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 375 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.26.7 G2S_OCE102 optionConfig Exited Configuration Mode Processing for this event begins in response to the enterOptionConfigMode command from a host instructing the EGM to exit the option configuration mode. This event should be sent after the EGM has exited the configuration mode. Table 9.55 G2S_OCE102 Device, Meter, Log Changes, and Related Commands Details Device State Changes optionConfigModeStatus.enabled = "false". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands enterOptionConfigMode. 9.26.8 G2S_OCE103 optionConfig Configuration Change Pending This event is sent by the EGM after the configuration options, sent to the EGM in the setOptionChange command, have been successfully validated. Table 9.56 G2S_OCE103 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Prior to sending this event, create and initialize optionChangeLog. See Table 9.59. Related Commands None. Table 9.57 G2S_OCE103 Log Changes, Create optionChangeLog Attribute Set to Value ... logSequence Next value in series. deviceId The optionConfig class deviceId associated with the setOptionChange command. transactionId Next value in series. configurationId Next value in series. applyCondition The applyCondition associated with the setOptionChange command. disableCondition The disableCondition associated with the setOptionChange command. startDateTime The startDateTime associated with the setOptionChange command. endDateTime Unchanged restartAfter Unchanged. changeStatus Reset to either G2S_pending, or one of the changeStatus states. changeDateTime Reset. changeException Reset. Page 376 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.26.9 G2S_OCE104 optionConfig Configuration Authorized by Host This event is sent by the EGM after the configuration options for the option configuration device have been authorized by the host. Table 9.58 G2S_OCE104 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update optionChangeLog and authorizeStatusList. See Table 9.59 and Table 9.59. Related Commands optionChangeStatus and authorizeOptionChange. Table 9.59 G2S_OCE104 Log Changes, Update optionChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. endDateTime Unchanged. restartAfter Unchanged. changeStatus Set to G2S_authorized. changeDateTime Updated to the time the record was updated. changeException Unchanged. Table 9.60 G2S_OCE104 Log Changes, Update authorizeStatus for Each Host Attribute Set to Value ... hostId The deviceId of the authorizing host. authorizeState Current authorization state. timeoutDate Unchanged. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 377 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.26.10 G2S_OCE105 optionConfig Configuration Cancelled This event is sent by the EGM after the configuration options for the option configuration device have been canceled by the host. Table 9.61 G2S_OCE105 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update optionChangeLog. See Table 9.62. Related Commands optionChangeStatus. Table 9.62 G2S_OCE105 Log Changes, Update optionChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. endDateTime Unchanged. restartAfter Unchanged. changeStatus Set to G2S_cancelled. changeDateTime Updated to the time the record was updated. changeException Unchanged. Page 378 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.26.11 G2S_OCE106 optionConfig Configuration Change Applied This event is sent by the EGM after the device configuration options, have been successfully applied by the EGM. Table 9.63 G2S_OCE106 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update optionChangeLog. See Table 9.59. Related Commands None. Table 9.64 G2S_OCE106 Log Changes, Create optionChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. endDateTime Unchanged. restartAfter Unchanged. changeStatus Set to G2S_applied. changeDateTime Date and time record was updated. changeException Set to 0. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 379 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.26.12 G2S_OCE107 optionConfig Configuration Aborted This event is sent by the EGM if the configuration options for the option configuration device have been changed locally by an operator and the EGM contains pending changes from a host. This event is also sent if a set of validated changes exists but has not been applied. Table 9.65 G2S_OCE107 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update optionChangeLog. See Table 9.66. Related Commands optionChangeStatus. Table 9.66 G2S_OCE107 Log Changes, Update optionChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. endDateTime Unchanged. restartAfter Unchanged. changeStatus Set to G2S_aborted. changeDateTime Updated to the time the record was updated. changeException Set to 0. Page 380 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 9.26.13 Chapter 9 optionConfig Class G2S_OCE108 optionConfig Error This event is sent by the EGM if the configuration options for the option configuration device have resulted in an error condition. Table 9.67 G2S_OCE108 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update optionChangeLog. See Table 9.68. Related Commands optionChangeStatus. Table 9.68 G2S_OCE108 Log Changes, Update optionChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. endDateTime Unchanged. restartAfter Unchanged. changeStatus Set to G2S_error. changeDateTime Updated to the time the record was updated. changeException Set to the appropriate exception. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 381 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.26.14 G2S_OCE109 optionConfig Configuration Waiting on Authorization This event is sent by the EGM after the parameters associated with an option configuration change have been met, but the EGM must wait on the required hosts to authorize the configuration change. Table 9.69 G2S_OCE109 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update optionChangeLog. See Table 9.68. Related Commands None. Table 9.70 G2S_OCE109 Log Changes, Update optionChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. endDateTime Unchanged. restartAfter Unchanged. changeStatus Set to G2S_pending. changeDateTime Updated to the time the record was updated. changeException Set to the appropriate exception. Page 382 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.26.15 G2S_OCE110 optionConfig Configuration Change Authorization Timeout This event is sent by the EGM after the option configuration changes have timed out waiting for authorization from a specific host. Table 9.71 G2S_OCE110 Device, Meter, Log Changes, and Related Commands Details Device State Changes None. Meter State Changes None. Log State Changes Update optionChangeLog and authorizeStatusList. See Table 9.68 and Table 9.59. Related Commands None. Table 9.72 G2S_OCE110 Log Changes, Update optionChangeLog Attribute Set to Value ... logSequence Unchanged. deviceId Unchanged. transactionId Unchanged. configurationId Unchanged. applyCondition Unchanged. disableCondition Unchanged. startDateTime Unchanged. endDateTime Unchanged. restartAfter Unchanged. changeStatus Set to G2S_pending. changeDateTime Updated to the time the record was updated. changeException Set to 6. Table 9.73 G2S_OCE110 Log Changes, Update authorizeStatus for Each Host Attribute Set to Value ... hostId The deviceId of the authorizing host. authorizeState Current authorization state. timeoutDate Unchanged. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 383 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.27 Examples The following example diagrams list some typical commands for the optionConfig class. 9.27.1 Option List Command Sequence EGM HOST getOptionList optionList 9.27.1.1 getOptionList: Host to EGM <optionConfig deviceId = "1" dateTime = "2005-02-03T20:10:07.345-05:00" commandId = "2001" sessionId = "1001" sessionType = "G2S_request" timeToLive = "30000" > <getOptionList deviceClass = "G2S_noteAcceptor" deviceId= "1" optionGroupId = "G2S_noteAcceptorOptions" optionId = "G2S_noteAcceptorOptions" optionDetail = "true" > </getOptionList> </optionConfig> Page 384 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 9.27.1.2 Chapter 9 optionConfig Class optionList: EGM to Host <optionConfig deviceId = "1" dateTime = "2005-02-03T20:10:09.456-05:00" commandId = "3001" sessionId = "1001" sessionType = "G2S_response" > <optionList> <deviceOptions deviceClass = "G2S_noteAcceptor" deviceId = "1" > <optionGroup optionGroupId = "G2S_noteAcceptorOptions" optionGroupName = "G2S Note Acceptor Options" <optionItem optionId = "G2S_noteAcceptorOptions" securityLevel = "G2S_operator" minSelections = "1" maxSelections = "1" > <optionParameters> <complexParameter paramId = "G2S_noteAcceptorParams" paramName = "Note Acceptor Options" paramHelp = "Options that control note acceptor device functions" > <booleanParameter paramId = "G2S_noteEnabled" paramName = "Notes Enabled" paramHelp = "Note acceptor should accept notes" canModLocal = "true" canModRemote = "true" /> <booleanParameter paramId = "G2S_voucherEnabled" paramName = "Vouchers Enabled" paramHelp = "Note acceptor should accept vouchers" canModLocal = "true" canModRemote = "true" /> </complexParameter> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_noteAcceptorParams" > <booleanValue paramId = "G2S_noteEnabled" > true </booleanValue> <booleanValue paramId = "G2S_voucherEnabled" > true </booleanValue> </complexValue> </optionCurrentValues> <optionDefaultValues> <complexValue paramId = "G2S_noteAcceptorParams" > <booleanValue paramId = "G2S_noteEnabled" > true </booleanValue> <booleanValue paramId = "G2S_voucherEnabled" > false </booleanValue> </complexValue> </optionDefaultValues> </optionItem> </optionGroup> </deviceOptions> </optionList> </optionConfig> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 385 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.27.2 Set Option Command Sequence HOST EGM setOptionChange optionChangeStatus authorizeOptionChange optionChangeStatus 9.27.2.1 Host transmits changes to EGM EGM validates changes Affected host authorizes changes EGM sends response to authorization & applies changes setOptionChange: Host to EGM <optionConfig deviceId = "1" dateTime = "2005-02-03T20:10:10.567-05:00" commandId = "2002" sessionId = "1002" sessionType = "G2S_request" timeToLive = "30000" > <setOptionChange configurationId = "5" applyCondition = "G2S_disable" disableCondition = "G2S_idle" startDateTime = "2005-02-04T02:00:00.000-05:00" endDateTime = "2005-02-04T03:59:59.999-05:00" restartAfter = "true" > <option deviceClass = "G2S_noteAcceptor" deviceId = "1" optionGroupId = " G2S_noteAcceptorOptions" optionId = "G2S_noteAcceptorOptions" > <optionCurrentValues> <complexValue paramId = "G2S_noteAcceptorParams" > <booleanValue paramId = "G2S_noteEnabled" >false</booleanValue> </complexValue> </optionCurrentValues> </option> </setOptionChange> </optionConfig> Page 386 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 9.27.2.2 Chapter 9 optionConfig Class optionChangeStatus: EGM to Host <optionConfig deviceId = "1" dateTime = "2005-02-03T20:10:07.456-05:00" commandId = "3002" sessionId = "1002" sessionType = "G2S_response" > <optionChangeStatus configurationId = "5" transactionId="21" applyCondition = "G2S_disable" disableCondition = "G2S_idle" startDateTime = "2005-02-04T02:00:00.000-05:00" endDateTime = "2005-02-04T03:59:59.999-05:00" restartAfter = "true" changeStatus = "G2S_pending" changeException = "0" changeDateTime = "2005-02-04T03:59:59.999-05:00" /> </optionConfig> 9.27.2.3 authorizeOptionChange: Host to EGM <optionConfig deviceId = "1" dateTime = "2005-02-03T20:10:10.567-05:00" commandId = "2003" sessionId = "1003" sessionType = "G2S_request" timeToLive = "30000" > <authorizeOptionChange configurationId = "5" transactionId = "21" /> </optionConfig > 9.27.2.4 optionChangeStatus: EGM to Host <optionConfig deviceId = "0" dateTime = "2005-02-03T20:10:07.456-05:00" commandId = "3003" sessionId = "1003" sessionType = "G2S_response" > <optionChangeStatus configurationId = "5" transactionId = "21" applyCondition = "G2S_disable" disableCondition = "G2S_idle" startDateTime = "2005-02-04T02:00:00.000-05:00" endDateTime = "2005-02-04T03:59:59.999-05:00" restartAfter = "true" changeStatus = "G2S_authorized" changeException = "0" changeDateTime = "2005-02-04T03:59:59.999-05:00" /> </optionConfig> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 387 Chapter 9 optionConfig Class G2S™ Message Protocol v1.0.3 9.28 Option Configuration Device Option Configuration This section identifies the G2S-specified configuration option selections for option configuration devices and provides an example of the optionItem element in 9.28.4. Configuration option selections are set using commands from the optionConfig class. The current configuration option selections for an option configuration device are reported via the optionConfigProfile command. Further descriptions of the sub-parameters can be found under the optionConfigProfile command. 9.28.1 Option Group Definitions optionGroupId optionGroupName 9.28.2 G2S_optionConfigOptions G2S Option Config Options G2S Protocol Option Definitions optionId G2S_protocolOptions securityLevel G2S_administrator minSelections 1 maxSelections 1 duplicates Duplicate Key Parameter Type paramId 9.28.3 n/a n/a complex G2S_protocolParams paramName G2S Protocol Parameters paramHelp Standard G2S protocol parameters for option config devices G2S Protocol Option Sub-Parameter Definitions Table 9.74 G2S Protocol Option Sub-Parameter Definitions paramId paramName Example paramHelp G2S_configurationId Configuration Identifier 123456 ID assigned by the last successful G2S option configuration G2S_noResponseTimer No Response Timer 30000 Time to live value for optionListAck (in milliseconds) Page 388 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 9.28.4 Chapter 9 optionConfig Class Example optionItem Elements in optionList The following are examples of optionItem elements used by the EGM to describe its configurable options for the option configuration device. These elements are sent by the EGM to the host in the optionList command. // G2S Protocol Options <optionItem optionId = "G2S_protocolOptions" securityLevel = "G2S_administrator" minSelections = "1" maxSelections = "1" > <optionParameters> <complexParameter paramId = "G2S_protocolParams" paramName = "G2S Protocol Parameters" paramHelp = "Standard G2S protocol parameters for option config devices" > <integerParameter paramId = "G2S_configurationId" paramName = "Configuration Identifier" paramHelp = "ID assigned by the last successful G2S option configuration" canModLocal = "false" canModRemote = "false" /> <integerParameter paramId = "G2S_noResponseTimer" paramName = "No Response Timer" paramHelp = "Time to live value for optionListAck (in milliseconds)" canModLocal = "true" canModRemote = "true" /> </optionParameters> <optionCurrentValues> <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 123456 </integerValue> <integerValue paramId = "G2S_noResponseTimer" >30000</integerValue> </complexValue> </optionCurrentValues> <optionDefaultValues> <complexValue paramId = "G2S_protocolParams" > <integerValue paramId = "G2S_configurationId" > 123456 </integerValue> <integerValue paramId = "G2S_noResponseTimer" >30000</integerValue> </complexValue> </optionDefaultValues> </optionItem> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 389 G2S™ Message Protocol v1.0.3 Page 390 Chapter 9 optionConfig Class gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 10 download Class 10.1 Introduction Chapter 10 download Class The download class is used to control software download, upload, installation, and uninstallation related to an EGM. The class includes commands for managing the software content of an EGM, which includes reading the current software content on an EGM, assigning new software content to the EGM, removing unwanted content from an EGM, and specifying when the new content is to be installed or uninstalled. The download class provides a standardized command set that fulfills the following software download activities: • • The G2S download protocol will provide • A standardized protocol to manage the software content on all G2S-compliant EGMs from all G2S-compliant host systems. This includes both download and upload transfer types. • A means for installation of software. • A means for removal of software (uninstall). • A means for creating software packages on the EGM for upload purposes. • A means to schedule the installation and/or uninstallation of software, providing various scheduling options that relate to a specific time, EGM state, or interaction with the host or technician. The G2S message protocol will: • Support reading an inventory of software packages and installed modules. This provides the capability to effectively manage the content on the EGM. • Provide a means to record transaction logs for packages and scripts. This provides an audit capability to determine how content came to be on an EGM. This strategy provides a central point of control, where a consistent and common interface is used to affect software download and upload, with a goal of interoperation among all G2S hosts and all EGM equipment. Additional features provide sequencing of scheduled activities with one or more hosts, providing each host the opportunity to read the EGM’s status, logs and meters. The download class is a single-device class. The EGM MUST expose only one active download device. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 391 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.2 Packages and Modules 10.2.1 Definitions Software download may be too narrow of a definition, so we will define it as the ability to transfer packages between a Software Download Distribution Point and one or more EGMs. A package is a manufacturer-defined element that can be thought of as a single file, which contains: • An optional package header that contains information about the package payload and • The package payload, with the payload being a ZIP file, TAR file, an XML configuration file, a single BIN file or any file format that makes sense. The point is that the specific format of the payload is of no interest to the command and control of the transfer. Every package is uniquely identified by a pkgId, which is a globally unique identifier that represents that package. Manufacturers will typically control this value through their internal release process. The concept of a package requires some explanation. A package may contain data, images, sounds, scripts, executables and other miscellanea to affect modules (defined below) on the EGM. A package may contain multiple modules or module abstracts, effectively allowing interrelated modules to be distributed as a single package. When a package is installed, it is effectively installing every module contained within the package. A module is a manufacturer-defined element that is a uniquely identifiable unit within the EGM. • A module can be a single file, or multiple files which may span multiple directories. For example, a module could be an operating system, a game theme, firmware for a printer, a single WAV sound file that is shared by other modules, or an EGM memory dump that can be uploaded to a host system. • A module can have dependencies or fulfill dependencies of other modules. • A module MUST be replaceable or removable as a single unit that does not orphan related files. Every module is uniquely identified by a modId, which is a globally unique identifier for that module. Manufacturers will typically control this value through their internal release process. Technically speaking, a module is installed on the EGM, but packages are pending transfer or available. After a package has been installed, the resulting installed modules remain independent of the original package. If the package is deleted, the corresponding installed modules remain on the EGM. Any given module may include optional command files that the EGM may execute for installation or uninstallation of the module. This strategy allows the manufacturer complete flexibility when designing their module install and uninstall procedures. In the absence of an install or uninstall command file, the EGM may have default internal procedures for correctly installing or uninstalling a module. Another potential use of a package is to uninstall modules; in other words, a package may contain a module that consists of a command file for uninstalling a module. This strategy may be used to remove pre-download (legacy) era modules that were built without an uninstall command file for uninstalling a module. This provides a means to remove legacy games before installation of newer download era modules. It is preferred that an EGM persist packages that have been transferred; however, an EGM is permitted to store packages in volatile memory. Storing packages in volatile memory will cause the EGM to lose those packages when the EGM is reset or powered off. Additionally, an EGM is permitted to perform some house cleaning of the package storage and purge some packages to free up storage for new package transfers. Page 392 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 10.2.2 Chapter 10 download Class Download Script Rules Overview Installation of packages on the EGM will be controlled via a download script. Similarly, removal (uninstallation) of modules is also controlled from the script. The purpose of the script is to: 1. Define a set of script commands that: a. Execute in a defined sequence without interruption. b. Identify command parameters, to facilitate: 1. package install. 2. package uninstall. 3. module install. 4. module uninstall. 5. system commands. 2. Define conditions for starting execution of the script commands: a. Define the time frame to initiate the script commands. This means that the commands may begin execution within the specified time frame. If no time is specified, the commands can proceed whenever the other conditions are met. The time frames that can be specified are: 1. Between a start and end time and date. 2. After a specific time and date. 3. Before a specific time and date. 4. Anytime all other conditions are met. b. Define the required EGM state before the commands can be initiated. Note: for the purposes of processing the script, disabling the EGM causes the downloadStatus command’s egmLocked attribute to be set to true. Some specific states are: 1. Disable the EGM when Idle (no credits or active game play for a specified time period). 2. Disable the EGM immediately (a cash-out is implied in this case). 3. Disable is not required for the commands to initiate. c. Define what initiating action causes the script commands to execute. The initiating action can be: 1. A manual signal at the EGM from an operator; such as a turn of the attendant key, a keypad entry, or via a menu screen option that is enabled at the EGM. 2. A host initiated command. This will be via a host sent authorizeScript command that indicates the script is cleared to execute and can begin when all the other install conditions have been satisfied. The authorizeScript command is used in conjunction with the authorizeList element of the script. When an authorizeList sub-element with one or more authorizeItem sub-elements exists in the script, the script will pause until all the specified authorization hosts set their authorized attribute to true. This technique may be used to pause the script at a point where each host can read EGM meters, logs or status before the authorization host authorizes the script to execute. Note: an authorization host is permitted to authorize a script at any time, so pre-authorization is allowed—even if meter, logs or status may be changed after pre-authorization. 3. Immediately upon all other script conditions being satisfied. 4. Any other defined condition as specified by the gaming establishment and regulator. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 393 Chapter 10 download Class G2S™ Message Protocol v1.0.3 There are certain other recommendations for download, including: 1. If a script causes the EGM to disable, the EGM SHOULD force a cash-out before disabling. 2. An operating system or EGM control program SHOULD only be installed while the EGM is disabled. 3. If any script command causes the meters to be reset or modified in any way, the EGM SHOULD be disabled before executing the script commands. 4. If the EGM does not fulfill the conditions for the script conditions, the script MUST fail and an appropriate error message MUST be logged. When a script has changed state, the script log is updated to indicate the new state of the script. Some script state changes may also affect the package log. For example: If a script contains a package install command whose deletePkgAfter attribute is set to false then following installation of the package, the package MAY be retained; otherwise, the package MUST be deleted. If the package is deleted, the package log MUST be updated to indicate the package has been deleted. The EGM SHOULD NOT use the contents of a package, except for validation, until the package has been successfully validated. The specifics of package validation are left to the manufacturer. It is recommended that the validation be supplemented with authentication in an effort to comply with the most stringent jurisdictional regulations. The EGM MUST process the script’s commands in the order that they appear within the script. If a script’s command fails, the script MUST stop processing at that point. When a script fails, it is up to the manufacturer to determine whether the EGM is in a locked state until corrective action is taken, if the EGM may continue to operate, or if a complete rollback of the script is applied. Furthermore, following a failed script the EGM MUST allow other scripts to be processed according to their specific conditions. This provides the capability for corrective action to be directed through the download class. 10.2.3 Host Authorized Script The download class contains a facility for one or more hosts to authorize a script. This mechanism may be used by a host to read critical status, logs or meter data from a disabled EGM before authorizing the script to proceed. It is not required that the EGM be disabled while the hosts read the critical data, but disabling the EGM does reduce the chance that the critical data will change before the authorization host authorizes the script. In the event that multiple authorization hosts are specified, all hosts may read the data they are interested in before they provide their individual authorization. After all authorization hosts have authorized the script, the script may proceed. The list of authorization hosts assigned to authorize a script is documented within the setScript command. If the script requires authorization, then the script will check that each configured authorization host has authorized it before initiating execution of the script commands. There are two additional configurable options, both within the G2S_downloadOptions optionGroup: • An option to set a timeout for generating the G2S_DLE207 • An option to set the maximum resends of the G2S_DLE207 event before aborting the install. Script Waiting on Authorization event. Script Waiting on Authorization The script log contains a boolean for each host that is in the configured authorization list, so a host may subscribe to the G2S_DLE207 Script Waiting on Authorization event with the affected log included in the subscription. An authorization host can determine if it needs to authorize the installation based upon the subscribed event. Page 394 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.2.4 Transfer Protocol Undefined The transfer method for the package is not defined within this description. The transfer protocol is purposely undefined so that EGM and host system manufacturers are not needlessly restricted from selecting the best transfer protocol for their needs. It is recommended that EGMs, Software Download Distribution Points, and other transfer hosts support one or more of the common standard transfer protocol types. Table 10.1 lists some common transfer protocol standards: Table 10.1 Common Transfer Protocol Standards Protocol Name URL Scheme Example transferLocation HyperText Transfer Protocol http: http://abc_mfg.com:80/downloadServer HyperText Transfer Protocol, Secure https: https://abc_mfg.com:443/downloadServer File Transfer Protocol ftp: ftp://abc_mfg.com:21/downloadServer Secure File Transfer Protocol sftp: sftp://abc_mfg.com:115/downloadServer gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 395 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.3 Download Network Overview The conceptual visualization of the simplest software download topology contains four parts: 1. an EGM 2. a System Management Point (SMP) 3. a Software Download Distribution Point (SDDP) 4. Optional authorization hosts. Each part plays a major role; however, the EGM is the authority when download activity occurs. The EGM must be in charge of the sequence of operations that affect a download and/or script processing while the System Management Point declares the packages for download and the scripts for processing. The Software Download Distribution Point responds to requests from the EGM. The authorization hosts provide the ability to capture critical data and permit a script to begin processing commands. The primary responsibilities of each part are described in the following sections. 10.3.1 EGM Responsibilities 1. Maintain an inventory of modules and packages on the EGM. 2. Maintain status of packages (such as pending or available) and scripts. 3. Maintain a log of package transfers, validations, creations and deletions; log any script activity. 4. Establish a connection to the System Management Point. 5. Send events to the System Management Point or other subscribed hosts. 6. Process download device enable/disable commands from the System Management Point. 7. Initiate and control package transfer between the Software Download Distribution Point, including resend, retry or restart recovery logic. 8. Validate transferred packages from the System Download Distribution Point. 9. Perform package dependency checks to determine if a package can be installed. Dependencies checks may reference hardware inventory, module inventory and package inventory. 10. Act upon install, uninstall, create and delete directives from the System Management Point. 10.3.2 System Management Point Responsibilities 1. Process and take action on events from the EGM. 2. Obtain an inventory of modules, packages and package status from the EGM. 3. Maintain a log of package transfers, validations, creations and deletions; log any script activity. 4. Direct the EGM to create, delete or add packages. In the case of adding packages, provide the location (Software Download Distribution Point) where to obtain each package. 5. Direct the EGM to execute scripts. The script commands provide package install, package uninstall, module install and module uninstall capabilities. 6. Read and store meters, logs, game recall or any other data as required by regulators. This may include uploading packages, based upon operator and regulator requirements. 7. Authorize script initiation. 8. Optional: Perform dependency checks for packages to be added to the EGM’s inventory. Dependency checks may reference EGM hardware inventory, module inventory and package inventory. Page 396 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) G2S™ Message Protocol v1.0.3 10.3.3 Chapter 10 download Class Software Download Distribution Point Responsibilities 1. Configuration of transfer parameters (such as timeouts and pacing/throttling), as needed, to control impact on the network operating environment. 2. Maintain a log of download activities, as needed, to meet regulatory and customer requirements. 3. Transfer packages as directed by the EGM. NOTE: transfers may be delayed for purposes of optimizing the transfer and network load. 4. Optionally provide a catalog of packages available to the System Management Point. 10.3.4 Authorization Host Responsibilities 1. Process and take action on events from the EGM. 2. Read and store meters, logs, game recall or any other critical data as required by regulators. 3. Authorize script initiation. The interaction between these four parts is illustrated in Figure 10.1. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 397 Chapter 10 download Class G2S™ Message Protocol v1.0.3 All EGM Status, Logs & Meters Download Enable/Disable Authorize Hosts Check Package, Module, & Component Dependencies Package Commands Script Commands Module Commands System Management Point EGM Optional Log Script Activity Log Package Activity Package Catalog Optional Transfer Package Software Download Distribution Point Figure 10.1 Download Network Relationships The System Management Point and EGM will communicate with the G2S download class message set. It is likely that the Software Download Distribution Point and the System Management Point will communicate using a GSA S2S message protocol that is suited to inter-host communications. As stated earlier, the transfer protocol between the Software Download Distribution Point and the EGM is undefined. Page 398 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.4 Package States When a System Management Point has added a package to the EGM’s packageList, the EGM will take the package through various states. Similarly, there are associated state transitions that occur when a package is created on the EGM. Figure 10.2 illustrates the various state transitions that may occur during the lifecycle of a package: Package States Package added pending Transfer / Validation error* error Package Transfer Complete* Package Passed Validation* Package created available Package Aborted* deletePending Package Deleted Note: if package transfer was completed then deletePending, else deleted Note: script installation MAY occur after the package is validated. deleted Figure 10.2 Package State Transitions NOTE: events followed by an asterisk ( * ) are the results of package transfer activity. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 399 Chapter 10 download Class G2S™ Message Protocol v1.0.3 The package may have transfer activity related to either transfer type—download or upload. Both download and upload transfers follow similar transfer states. Figure 10.3 diagrams illustrate the state transitions that may occur during a package transfer: Download Transfer States Upload Transfer States Package Upload Requested Package added pending Package Download Refused Package Download Aborted error Insufficient Storage for Package Download Package Failed Validation pending Package Download Initiatied Package Upload Initiated Package Upload In Progress Package Download In Progress inProgress Package Download Complete transferred inProgress Package Deleted Package Deleted Package Upload Refused Package Upload Aborted error Package Upload Complete transferred Package Passed Validation validated Figure 10.3 State Transitions During Package Transfer Page 400 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.5 Script States When a System Management Point has set a script for a package, the EGM will take the script through various states. Figure 10.4 illustrates the various state transitions that may occur during any script: Script States Note: script error state may occur due to scriptTime Ended. Note: at this point all script conditions have been satisfied, thus starting the script commands. Script set composite script pending states Script inProgress inProgress Script Error error Script Complete completed Script Canceled Note: This transition occurs when the script is cancelled while in one of the pending states. cancelled Note: All terminal conditions (completed, cancelled, error) lead to cancelling of the script. Figure 10.4 Script State Transitions NOTE for Figure 10.5: An EGM MUST attempt to resume execution of a script in progress when it is interrupted by a reset or power down. Furthermore, if a script command fails, the EGM MUST halt execution of the script at the point of failure. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 401 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Composite Script Pending States If package not transferred or not validated, then pendTransfer Script Time Started Note: Authorization Host enable/disable events (A.H. e/d) can occur in most of the pending states, and is not limited pendingAuthorization state. A.H. e/d pendingTransfer Package Transfer Complete If script has start time and not start time yet, then pendDateTime A.H. e/d pendingDateTime Note: if a related package is deleted, the script will automatically be cancelled. Script Time Started If script requires disable and EGM not disabled yet, then pendDisable A.H. e/d pendingDisable Script Disable Started A.H. e/d If script requires authorization and not authorized yet, then pendAuthorization Script Waiting on Authorization pendingAuthorization If script requires initiation and not initiated yet, then pendInitiation Script Waiting on Operator Initiation pendingInitiation Script Initiated Script Cancelled Script Time Ended Figure 10.5 Composite Script Pending States (see previous NOTE on page 401) Page 402 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.6 Request-Response Pairs The following table organizes the commands contained within the download class into request-response pairs: Table 10.2 Commands Originated by EGM Request Response packageStatus packageStatusAck scriptStatus scriptStatusAck Table 10.3 Commands Originated by Host (Owner Host is System Management Point) Request Response Owner Guest setDownloadState downloadStatus Yes No getDownloadStatus downloadStatus Yes Yes getDownloadProfile downloadProfile Yes Yes addPackage packageStatus Yes No createPackage packageStatus Yes No deletePackage packageStatus Yes No uploadPackage packageStatus Yes No getPackageStatus packageStatus Yes Yes readPackageContents packageContents Yes Yes getPackageList packageList Yes Yes getPackageLogStatus packageLogStatus Yes Yes getPackageLog packageLogList Yes Yes setScript scriptStatus Yes No cancelScript scriptStatus Yes No getScriptStatus scriptStatus Yes Yes authorizeScript scriptStatus Yes Yes getScriptList scriptList Yes Yes getScriptLogStatus scriptLogStatus Yes Yes getScriptLog scriptLogList Yes Yes getModuleList moduleList Yes Yes gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 403 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.7 setDownloadState Command This command is used by a host to enable or disable the download functionality of an EGM. Only the owner of the device can execute this command. The downloadStatus command is sent in response to the setDownloadState command. If the download functionality is disabled then only passive commands (commands that do not affect the device or EGM states) and the setDownloadState command will be processed correctly. All other commands will be rejected. Furthermore, download package transfer and script execution will be prevented from starting until the download functionality has been enabled (both hostEnabled and egmEnabled attributes set to true). Package transfers already in progress MAY either continue or abort when the download functionality is disabled. Scripts that are executing MUST continue to execute to completion when the download functionality is disabled. Table 10.4 setDownloadState Attributes Attribute Restrictions Description enable type: boolean use: optional default: true Indicates whether the download functionality should be enabled or disabled. true = enabled and false = disabled. disableText type: textMessage use: optional default: <empty> Text for a message to optionally display why the device was disabled. 10.8 getDownloadStatus Command This command is used by a host to request the current status of the download device from the EGM. The EGM sends a downloadStatus command in response to the getDownloadStatus command. The getDownloadStatus command has no additional attributes or elements. Page 404 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.9 downloadStatus Command This command is used by the EGM to send the current status of the download functionality to a host system. The downloadStatus command is sent in response to the setDownloadState and getDownloadStatus commands. If the download functionality has been disabled then only passive commands (do not affect device or EGM state) and the setDownloadState will be processed correctly. All other commands will be rejected. Furthermore, download package transfer and script execution will be prevented from starting until the download functionality has been enabled (both hostEnabled and egmEnabled attributes set to true). Package transfers already in progress MAY either continue or abort when the download functionality is disabled. Scripts that are executing MUST continue to execute to completion when the download functionality is disabled. Table 10.5 downloadStatus Attributes Attribute Restrictions Description configurationId type: configurationId use: optional default: 0 Configuration identifier set by the host. A 0 (zero) value indicates the current configuration was not set by a host. hostEnabled type: boolean use: optional default: true Indicates whether the download functionality has been enabled by the host. egmEnabled type: boolean use: optional default: true Indicates whether the download functionality has been enabled by the EGM. egmLocked type: boolean use: optional default: false Indicates whether the download device has the EGM in a locked state. 10.10 getDownloadProfile Command This command is used by a host to request the current profile of the download device from the EGM. The EGM sends a downloadProfile command in response to the getDownloadProfile command. The getDownloadProfile command has no additional attributes or elements. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 405 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.11 downloadProfile Command This command is used by the EGM to send the current download profile to a host system. The downloadProfile command is sent in response to the getDownloadProfile command. The download profile contains protocol-related configuration options for the download device. The configuration options can be set locally at the EGM or remotely via the configuration server using commands within the optionConfig class. Table 10.6 downloadProfile Attributes (Sheet 1 of 2) Attribute Restrictions Description configurationId * type: configurationId use: optional default: 0 Last configuration identifier set by a G2S host; set to 0 (zero) when configuration changes are made by hosts other than G2S hosts. restartStatus * type: boolean use: optional default: true Indicates the state of hostEnabled when the EGM restarts. useDefaultConfig * type: boolean use: optional default: false Indicates whether the default configuration for the device MUST be used when the EGM restarts. requiredForPlay * type: boolean use: optional default: false Indicates whether the EGM MUST be disabled if either egmEnabled or hostEnabled is set to false. timeToLive * type: timeToLive use: optional default: 30000 Time-to-live value for requests originated by the device. noResponseTimer * type: milliseconds use: optional default: 0 Maximum amount of time the download device will wait for a response from its owner host before deeming the host to be offline and disabling the download device by setting its hostEnable attribute to false. A 0 (zero) value indicates that the timer is disabled. noMessageTimer * type: milliseconds use: optional default: 0 Maximum amount of time the download device will wait for a message from its owner host before deeming the host to be offline and disabling the download device by setting its hostEnable attribute to false. A 0 (zero) value indicates that the timer is disabled. minPackageLogEntries * type: int use: optional minIncl: 1 default: 35 Indicates the configured minimum number of package log entries the EGM MUST maintain. minScriptLogEntries * type: int use: optional minIncl: 1 default: 35 Indicates the configured minimum number of script log entries the EGM MUST maintain. Page 406 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.6 downloadProfile Attributes (Sheet 2 of 2) Attribute Restrictions Description minPackageListEntries * type: int use: optional minIncl: 1 default: 10 Indicates the configured minimum number of package list entries the EGM MUST maintain. minScriptListEntries * type: int use: optional minIncl: 1 default: 10 Indicates the configured minimum number of script list entries the EGM MUST maintain. authWaitTimeOut * type: milliseconds use: optional default: 60000 Indicates the configured timeout period for retrying the G2S_DLE207 Script Waiting on Authorization event. When expired, the event will be regenerated and sent to subscribed hosts. Every time the event is generated, the timer will be restarted, which will repeat until one of the following occurs: • All authorization hosts have authorized the script. • When the requiredAuthHostRetry count is exceeded. A 0 (zero) value disables the timeout period, causing the EGM to wait indefinitely without retrying. authWaitRetry * type: int use: optional minIncl: 0 default: 2 Indicates the configured maximum number of retries for the G2S_DLE207 Script Waiting on Authorization event. If all required hosts have not authorized after the specified number of retries then the script will fail. downloadEnabled * type: boolean use: optional default: false Indicates whether the device is enabled for download transfers; false if download transfers are not supported. uploadEnabled * type: boolean use: optional default: false Indicates whether the device is enabled for upload transfers; false if upload transfers are not supported. scriptingEnabled * type: boolean use: optional default: false Indicates whether the device is enabled for script processing for the installation or removal of packages and modules; false if script processing is not supported. * * Standard configuration option that MUST be included in the standard option configuration group – G2S_downloadOptions – for devices within the download class. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 407 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.12 addPackage Command This command is used by a host to direct the EGM to add 1 (one) package to its packageList and the location to obtain the package from. The EGM sends a packageStatus command in response to addPackage command. If the EGM is unable to add the package to its packageList, the EGM will respond with error code G2S_DLX004 to indicate the packageList is full. The EGM initiates the request for transfer of the specified packages from the designated Software Download Distribution Point. Packages will be added to the packageList in the order corresponding to the sequence of the associated addPackage and createPackage commands. The packages may be downloaded in any order; however, it is recommended that the EGM request packages for transfer in the order that they appear in the package list. Similarly, an EGM may sequence package transfer requests to occur sequentially, or may request multiple transfers simultaneously, based upon the EGM’s ability to process multiple transfers. Possible error code responses: • If an addPackage command is received for a pkgId that already appears in the packageList, the EGM will generate error code G2S_DLX002 to indicate the package already exists, and disregard the addPackage command. • An error code G2S_DLX012 MAY be sent in response if an addPackage command is received and there is insufficient storage to accommodate the size of the package, based on the pkgSize attribute of the addPackage command. • If the package was being processed (installed or uninstalled via script), the following steps will be performed: a. An error code G2S_DLX003 is generated to indicate the package is currently being processed in a script. b. The addPackage command will be discarded. c. The processing of the package will continue. Table 10.7 addPackage Attributes (Sheet 1 of 2) Attribute Restrictions Description pkgId type:packageId use: required Uniquely identifies the package. transferId type: transferId use: optional default: 0 An optional transfer identifier provided by the host. transferLocation type: transportLocation use: required An IP address:port/path or valid network URI address for the Software Download Distribution Point where the package can be retrieved from. transferParameters type: string use: optional maxLen: 128 default: <empty> A string containing optional parameters required for the transfer of the package. Potential uses include transfer parameters for FTP user name and password. Page 408 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.7 addPackage Attributes (Sheet 2 of 2) Attribute Restrictions Description transferType type: transferTypes use: optional default: G2S_downloadGet Indicates the transfer type; more specifically, this indicates whether the EGM or the host initiates the download to the EGM. pkgSize type: long use: optional minIncl: 0 default: 0 The exact size of the package in bytes as provided by the SMP. A value of 0 (zero) indicates the size is unknown. Note: this may be used by the EGM to determine if sufficient storage space is available before initiating the package transfer. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the transfer. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 409 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.13 createPackage Command This command is used by a host to direct the EGM to create a package and add it to the packageList. The EGM sends a packageStatus command in response to the createPackage command. Created packages will be added to the packageList in the order corresponding to the sequence of the associated addPackage and createPackage commands. If the overwrite attribute is set to true and a newly created package overwrites a package with the same pkgId, the old package will be deleted and the new package will be created and appended to the packageList. Possible error code responses: • If the EGM is unable to create the package because it references a package that already exists and the overwrite attribute is set to false, the EGM will respond with error code G2S_DLX002. • If the EGM is unable to create the package because it references non-existent modules, the EGM will respond with error code G2S_DLX009. • If the EGM is unable to create the package because there is insufficient storage on the EGM, the EGM will respond with error code G2S_DLX012. • If the EGM is unable to add the package to its packageList, the EGM will respond with error code G2S_DLX004 to indicate the packageList is full. Table 10.8 createPackage Attributes Attribute Restrictions Description pkgId type: packageId use: required Uniquely identifies the package to be created. pkgFormat type: pkgFormats use: optional default: G2S_other Indicates the package payload format (ZIP, Tar, etc.) pkgDescription type: descriptionText use: optional default: <empty> An optional text description for the package. overwrite type: boolean use: optional default: false Indicates if the newly created package may overwrite an existent package with the same pkgId. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the package creation. Table 10.9 createPackage Elements Element Restrictions Description moduleSelect minOcc: 1 Identifies a module to be included in the created package. See attributes in Table 10.10. maxOcc: ∞ Table 10.10 moduleSelect Attributes Attribute Restrictions Description modId type: moduleId use: required Uniquely identifies a module. Page 410 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.14 deletePackage Command This command is used by a host to direct the EGM to delete one package from its packageList. The EGM sends a packageStatus command in response to the deletePackage command. The EGM will delete the package only if the package exists in the EGM’s packageList. Possible error code responses: • If the package does not exist in the packageList, the error code G2S_DLX001 will be sent to the System Management Point indicating that a non-existent package is specified. • If the package is being transferred, the transfer MAY abort before completing the transfer. The package will be marked for deletion (G2S_deletePending) if the transfer cannot abort. In either case, the package ultimately will be removed from the packageList following either the aborted transfer or the completion of the transfer. • If the package does exist but is being installed, the error code G2S_DLX003 will be sent to the System Management Point indicating that the package specified is currently being processed in a script. Before deleting the package from the packageList, the EGM MUST delete the package from EGM storage, if it exists. After deleting the package from the packageList, the EGM MUST also update the status of any script that referenced the package. Furthermore, a package that is deleted will remain in the package log with the deleted status, even though it is no longer in the package list. Table 10.11 deletePackage Attributes Attribute Restrictions Description pkgId type: packageId use: required Uniquely identifies the package. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the deletion. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 411 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.15 uploadPackage Command This command is used by a host to direct the EGM to transfer a package from its packageList to the location specified. The EGM sends a packageStatus command in response to the uploadPackage command. Based upon the scheme identified within the transferLocation and the transferType, the EGM will either initiate the transfer or accept the host’s initiation of the transfer. The packages may be uploaded in any order; however, it is recommended that the EGM initiate transfers in the order that they appear in the package list. Similarly, an EGM may sequence package transfer requests to occur sequentially, or may manage multiple transfers simultaneously, based upon the EGM’s ability to process multiple transfers. NOTE: A package contains at most only one packageUploadStatus element, therefore a single package may have at most only one outstanding uploadPackage command. Possible error code responses: • If the package does not exist in the packageList, the error code G2S_DLX001 will be sent to the System Management Point indicating that a non-existent package is specified. • If the EGM does not support the specified transferType, the error code G2S_DLX013 will be sent to the System Management Point indicating that the EGM does not support the transfer type. • If the package has an outstanding upload, the error code G2S_DLX010 will be sent to the System Management Point indicated that additional upload requests will not be processed until the current upload request has completed. Table 10.12 uploadPackage Attributes (Sheet 1 of 2) Attribute Restrictions Description pkgId type: packageId use: required Uniquely identifies the package. transferId type: transferId use: optional default: 0 An optional transfer identifier provided by the host. transferLocation type: transportLocation use: required A host provided IP address:port/path or valid network URI address for the destination of a G2S_uploadPut type of transfer. For G2S_uploadGet type of transfers, this attribute contains information for the EGM to know the transfer scheme with which to accept the transfer request. NOTE: This attribute will be overwritten by the EGM during G2S_uploadGet type of transfers. transferParameters type: string use: optional maxLen: 128 default: <empty> A string containing optional parameters required for the transfer of the package. Potential uses include transfer parameters for FTP user name and password. transferType Indicates the transfer type; more specifically, this indicates whether the EGM or the host initiates the upload from the EGM. Page 412 type: transferTypes use: optional default: G2S_uploadPut gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.12 uploadPackage Attributes (Sheet 2 of 2) Attribute Restrictions Description deleteAfter type: boolean use: optional default: true Indicates whether the package is to be deleted after the upload transfer completes. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the transfer. 10.16 getPackageStatus Command This command is used by a host to request the status of the specified package. The EGM sends a packageStatus command in response to the getPackageStatus command. The EGM will report the status of a package only if the package exists in the EGM’s packageList. Possible error code responses: • If the package does not exist in the packageList, a G2S_DLX001 error message will be sent, indicating that a non-existent package has been specified. Table 10.13 getPackageStatus Attributes Attribute Restrictions Description pkgId type: packageId use: required Uniquely identifies the package. 10.17 packageStatus Command This command is used by the EGM to report the status of a package to a host. • The packageStatus command is sent in response to addPackage, deletePackage, createPackage, uploadPackage and getPackageStatus commands. • The packageStatus command is also sent whenever the pkgState or transferState attributes reach a terminal condition. The packageStatus command is sent for the following conditions: • • transferState = "G2S_transferred". transferState = "G2S_validated" This applies to upload transfers only. and pkgState = "G2S_available". This applies to download transfers only. • transferState = "G2S_error". • pkgState = "G2S_error". • pkgState = "G2S_deleted". G2S_deletePending This applies to download and upload transfers. This applies to downloads that failed validation. This occurs when the pkgState attribute transitions from to G2S_deleted. The packageStatus command has a primary format that indicates the state of the package, and two secondary forms that indicate either a package transfer or package activity. The packageStatus element is always present gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 413 Chapter 10 download Class G2S™ Message Protocol v1.0.3 in the command, and this is the primary form of the command. For secondary forms, at most 1 (one) subelement may be included in the command. See the schema diagram below. This element is also used within the packageList command. Table 10.14 packageStatus Attributes Attribute Restrictions Description pkgId type: packageId use: required Uniquely identifies the package. pkgState type: pkgStates use: required Indicates the status of the package. pkgException type: pkgExceptions use: optional default: 0 Exception code associated with the pkgState. MUST be provided when the pkgState = "G2S_error". Table 10.15 packageStatus Elements Element Restrictions Description packageTransferStatus minOcc: 0 maxOcc: 1 Contains parameters related to package transfers. This sub-element appears only when a transfer operation is pending or otherwise being reported. After a transfer has completed, this sub-element will not appear in the packageStatus command. See Table 10.16. packageActivityStatus minOcc: 0 maxOcc: 1 Contains information related to package creation or deletion activities. This sub-element will appear only when a packageStatus command is sent in response to createPackage and deletePackage commands. See Table 10.17. Page 414 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.16 packageTransferStatus Attributes Attribute Restrictions Description transferId type: transferId use: optional default: 0 An optional transfer identifier provided by the host. transferLocation type: transportLocation use: required An IP address:port/path or valid network URI address for the other (non-EGM) endpoint of the transfer. The transferLocation will identify the source of the transfer for G2S_downloadGet and G2S_downloadPut transfer types. Alternatively, the transferLocation will identify the destination of the transfer for G2S_uploadGet and G2S_uploadPut transfer types. transferParameters type: string use: optional maxLen: 128 default: <empty> A string containing optional parameters required for the transfer of the package. Potential uses include transfer parameters for FTP user name and password. transferType type: transferTypes use: optional default: G2S_downloadGet Indicates the transfer type; more specifically, this indicates whether the EGM or the transfer endpoint initiates the transfer. transferState type: transferStates use: required Indicates the status of the transfer. transferException type: transferExceptions use: optional default: 0 Exception code associated with the transferState. MUST be provided when the transferState = "G2S_error". pkgSize type: long use: optional minIncl: 0 default: 0 The exact size of the package in bytes as provided by the SMP. A value of 0 (zero) indicates the size is unknown. NOTE: this may be used by the EGM to determine if sufficient storage space is available before initiating the package transfer. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the transfer. deleteAfter type: boolean use: optional default: false Specifies if the package is to be deleted after the transfer completes. transferCompleteDateTime type: dateTime use: optional default: <null> Date and time when the package transfer completed. pkgValidateDateTime type: dateTime use: optional default: <null> Date and time when the package validation completed successfully gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 415 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.17 packageActivityStatus Attributes Attribute Restrictions Description activityType type: pkgActivityTypes use: required Indicates the package activity associated with this transaction. overwrite type: boolean use: optional default: false Indicates whether a createPackage command may overwrite a package with the same pkgId. NOTE: Only set to true for packageCreate activity when the createPackage command specified that overwrite was permitted. Always set to false for packageDelete activities. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the package activity. activityDateTime type: dateTime use: optional default: <null> Date and time when the activity occurred. 10.18 packageStatusAck Command This command is sent by a host to acknowledge that the package status has changed. The packageStatusAck command is sent in response to the packageStatus command. There are no additional attributes or elements for this command. 10.19 readPackageContents Command This command is used by a host to direct the EGM to return a list of package contents for the specified package. The EGM sends a packageContents command in response to the readPackageContents command. Possible error code responses: • If the EGM is unable to locate the package because the package does not exist, the EGM will respond with error code G2S_DLX001. • If the EGM is unable to read the package because the package is unreadable (perhaps the package has not been downloaded yet), the EGM will respond with error code G2S_DLX011. Table 10.18 readPackageContents Attributes Attribute Restrictions Description pkgId type: packageId use: required Uniquely identifies the package to be read. Page 416 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.20 packageContents Command This command is used by the EGM to report the contents of a package to a host. The packageContents command is sent in response to a readPackageContents command. The packageContents response contains only a summary of the package, or a ‘table of contents’ related to the package. The actual contents of the package are not returned. Table 10.19 packageContents Attributes Attribute Restrictions Description pkgId type: packageId use: required Uniquely identifies the package. releaseNum type: string use: required Identifies the release number for the package. pkgFormat type: pkgFormats use: optional default: G2S_other Identifies the package payload format such as ZIP or Tar. pkgSize type: long use: required minIncl: 0 The size of the package in bytes. pkgVerifyCode type: string use: optional default: <empty> An optional verification code such as CRC, MAC or hash. pkgDescription type: descriptionText use: optional default: <empty> An optional text description of the package. Table 10.20 packageContents Elements Element Restrictions Description moduleInfo minOcc: 1 Contains information about a single module within the package. See attributes in Table 10.21. maxOcc: ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 417 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.21 moduleInfo Attributes Attribute Restrictions Description modId type: moduleId use: required Uniquely identifies the module. modReleaseNum type: string use: optional default: <empty> maxLen: 32 Module release number. modType type: modTypes use: optional default: G2S_other Contains a module specified type such as G2S_os or G2S_game. modDescription type: descriptionText use: optional default: <empty> Contains an optional description of the module. 10.21 getPackageList Command This command is used by a host to request the list of packages from the EGM. The EGM sends a packageList command in response to the getPackageList command. The getPackageList command has no additional attributes or elements. 10.22 packageList Command This command is used by the EGM to report the list of packages to a host. The packageList command is sent in response to the getPackageList command. Table 10.22 packageList Elements Element Restrictions Description packageStatus minOcc: 0 Contains information for a single package within the package list. See Table 10.14 for details about this element. maxOcc: Page 418 ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.23 getPackageLogStatus Command This command is used by a host to request the current status of the package log status from the EGM. The response includes the sequence number of the last transaction and the total number of transactions in the log. The EGM sends a packageLogStatus command in response to the getPackageLogStatus command. The getPackageLogStatus command has no additional attributes or elements. 10.24 packageLogStatus Command This command is used by the EGM to send the current status of the package log status to a host. The packageLogStatus command is sent in response to a getPackageLogStatus command. Table 10.23 packageLogStatus Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional default: 0 minIncl: 0 The sequence number of the last transaction within the log. totalEntries type: int use: optional default: 0 minIncl: 0 The total number of transactions within the log. 10.25 getPackageLog Command This command is used by a host to request the current package log from the EGM. Additional information regarding the use of the lastSequence and totalEntries attributes can be found in Chapter 1. The EGM sends a packageLogList command in response to the getPackageLog command. Table 10.24 getPackageLog Attributes Attribute Restrictions Description lastSequence type: logSequence use: optional default: 0 minIncl: 0 The sequence number of the transaction that should be the first entry in the list; if set to 0 (zero) then default to the last transaction. totalEntries type: int use: optional default: 0 minIncl: 0 The total number of transactions that should be included in the list; if set to 0 (zero) then default to all transactions. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 419 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.26 packageLogList Command This command is used by the EGM to send the contents of the package log to a host. The packageLogList command is sent in response to a getPackageLog command. The package log contains a record for each transaction that affects a package, such as package transfer, package creation, or package deletion. The following commands MAY cause a new package transaction log record to be created: • addPackage • uploadPackage • createPackage • deletePackage Furthermore, package logs MUST be updated as package transfers sequence through their transfer states. Table 10.25 packageLogList Elements Element Restrictions Description packageLog minOcc: 0 Contains information regarding a change in the package list, including the status of a package within the list. See attributes in Table 10.26 and elements in Table 10.27. maxOcc: ∞ Table 10.26 packageLog Attributes Attribute Restrictions Description logSequence type: logSequence use: required Unique package log sequence number assigned by the EGM. deviceId type: deviceId use: required Device identifier of the download device that generated the package transaction. transactionId type: transactionId use: required minIncl: 1 Unique package transaction identifier assigned by the EGM. pkgId type: packageId use: required Uniquely identifies the package. pkgState type: pkgStates use: required Indicates the status of the package. pkgException type: pkgExceptions use: optional default: 0 Exception code associated with the pkgState. MUST be provided when the pkgState = "G2S_error". Table 10.27 packageLog Elements Element Restrictions Description packageTransferLog minOcc: 0 maxOcc: 1 Contains information regarding the transfer of a package. See attributes in Table 10.28. packageActivityLog minOcc: 0 maxOcc: 1 Contains information regarding the non-transfer activity of a package. See attributes in Table 10.29. Page 420 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.28 packageTransferLog Attributes Attribute Restrictions Description transferId type: transferId use: optional default: 0 An optional transfer identifier provided by the host. transferLocation type: transportLocation use: required An IP address:port/path or valid network URI address for the transfer endpoint. transferParameters type: string use: optional maxLen: 128 default: <empty> A string containing optional parameters required for the transfer of the package. Potential uses include transfer parameters for FTP user name and password. transferType type: transferTypes use: optional default: G2S_downloadGet Indicates the transfer type; more specifically, this indicates whether the EGM or the transfer endpoint initiates the transfer. pkgSize type: long use: optional minIncl: 0 default: 0 The exact size of the package in bytes as provided by the SMP. A value of 0 (zero) indicates the size is unknown. NOTE: this may be used by the EGM to determine if sufficient storage space is available before initiating the package transfer. deleteAfter type: boolean use: optional default: false Indicates whether the package is to be deleted after the transfer completes. transferState type: transferStates use: required Indicates the status of the transfer. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the transfer. transferException type: transferExceptions use: optional default: 0 Exception code associated with the transferState. MUST be provided when the transferState = "G2S_error". transferCompleteDateTime type: dateTime use: optional default: <null> Date and time when the package transfer completed. pkgValidateDateTime Date and time when the package validation completed successfully type: dateTime use: optional default: <null> gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 421 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.29 packageActivityLog Attributes Attribute Restrictions Description reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the package activity. activityType type: pkgActivityTypes use: required Indicates the package activity associated with this transaction. overwrite type: boolean use: optional default: false Indicates whether a createPackage command may overwrite a package with the same pkgId. NOTE: Only set to true for packageCreate activity when the createPackage command specified that overwrite was permitted. Always set to false for packageDelete activities. activityDateTime type: dateTime use: optional default: <null> Date and time when the activity occurred. 10.27 setScript Command This command is used by a host to direct the EGM to set a script for affecting the software content on the EGM. The EGM sends a scriptStatus command in response to the setScript command. The setScript sub-element commandList must contain at least one package, module, or system command. It is recommended that the EGM verify that every package and/or module referenced by the script is in the packageList or moduleList respectively, otherwise the setScript command must be rejected and an error code returned to the host. Possible error code responses: • If the scriptId is already in use, then the EGM will respond with error code G2S_DLX006. • If the EGM is unable to add the script to its scriptList, then the EGM will respond with error code G2S_DLX008 to indicate the scriptList is full. • G2S_DLX001 command references a non-existent package. • G2S_DLX009 command references a non-existent module. • G2S_DLX014 script is too complex. • G2S_DLX015 invalid commandString in command. The EGM implementation is open to include different methods for verifying that the commands can be executed without obvious errors. One possible alternative is for the EGM to maintain an install database containing all installed packages or modules, and then validate the script’s install commands against the package list and validate the script’s uninstall commands against the install database. Page 422 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 A host may not modify a script once it has been accepted by the EGM. To affect a script in the EGM, the host may only delete the original script and send a new (modified) script. Table 10.30 setScript Attributes Attribute Restrictions Description scriptId type: scriptId use: required A host provided identifier that uniquely identifies the script. This value must be unique from other scripts in the EGM’s scriptList. startDateTime type: dateTime use: optional default: <null> Start of the time window during which the script commands will be executed. endDateTime type: dateTime use: optional default: <null> End of the time window during which the script commands will be executed. disableCondition type: disableConditions use: required Conditions where the EGM will disable before script command initiation can occur. applyCondition type: applyConditions use: required Initiation condition that begins script command processing. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the changes specified in the script. Table 10.31 setScript Elements Element Restrictions Description authorizeList minOcc: 0 maxOcc: 1 Contains an optional list of authorization hosts. See elements in Table 10.32. commandList minOcc: 1 maxOcc: 1 Contains a list of script command elements to execute with the script. See elements in Table 10.34. Table 10.32 authorizeList Elements Elements Restrictions Description authorizeItem minOcc: 0 Contains a script authorization item for each required authorization host. See attributes in Table 10.33. maxOcc: ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 423 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.33 authorizeItem Attributes Attribute Restrictions Description hostId type: deviceId use: required Host identifier of the host that must authorize this change before it can proceed. timeoutDate type: dateTime use: optional default: <null> Timeout value. Indicates when the EGM should give up waiting on authorization from this host. timeoutAction type: timeoutActionTypes use: optional default: G2S_ignore Action that should occur when the EGM has timed out waiting on authorization from this host. Table 10.34 commandList Elements AT LEAST ONE ELEMENT REQUIRED Element Restrictions Description packageCmd minOcc: 0 Contains parameters for a package command. See attributes in Table 10.35. maxOcc: moduleCmd Contains parameters for a module command. See attributes in Table 10.36. minOcc: 0 maxOcc: systemCmd ∞ ∞ Contains parameters for a system command. See attributes in Table 10.37. minOcc: 0 maxOcc: ∞ Table 10.35 packageCmd Attributes Attribute Restrictions Description pkgId type: packageId use: required Uniquely identifies the package for the command. operation type: operPackage use: required Contains the specific operation for the command. commandString type: string use: optional maxLen: 256 default: <empty> Contains an optional manufacturer defined command string. NOTE: An EGM MUST validate that the command string is valid before starting the script execution. deletePkgAfter type: boolean use: optional default: false Indicates whether the package should be deleted from the package list (and internal storage) after the command has successfully completed. cmdSequence type: int minIncl: 0 use: required A monotonically increasing sequence number (values begin from 1) used to order this script command with the other commands in the script. The value MUST be unique across all script commands that are subordinate to the commandList element. Page 424 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.36 moduleCmd Attributes Attribute Restrictions Description modId type: moduleId use: required Uniquely identifies the module for the command. operation type: operModule use: required Contains the specific operation for the module command. pkgId type: packageId use: optional default: <null> Identifies the package to install the module from. NOTE: This attribute will only be provided when operation = "G2S_install". cmdSequence type: int minIncl: 0 use: required A monotonically increasing sequence number (values begin from 1 (one)) used to order this script command with the other commands in the script. The value MUST be unique across all script commands that are subordinate to the commandList element. Table 10.37 systemCmd Attributes Attribute Restrictions Description operation type: operSystem use: required Contains the specific operation for the system command. cmdSequence type: int minIncl: 0 use: required A monotonically increasing sequence number (values begin from 1 (one)) used to order this script command with the other commands in the script. The value MUST be unique across all script commands that are subordinate to the commandList element. 10.28 cancelScript Command This command is used by a host to direct the EGM to delete one script from its scriptList. The EGM sends a scriptStatus command in response to the cancelScript command. The EGM will delete the script only if the script exists in the EGM’s scriptList. Possible error code responses: • If the script doesn’t exist in the scriptList, a G2S_DLX005 error message will be sent to the System Management Point, indicating that a non-existent script is specified. • Similarly, if a script is executing (G2S_inProgress), the cancelScript command will be rejected and a G2S_DLX007 error message will be sent to indicate that an executing script may not be deleted. A deleted script will be recorded in the log with a cancelled status, and all commands within the script will also be in the log with a cancelled status. Table 10.38 cancelScript Attributes Attribute Restrictions Description scriptId type: scriptId use: required Unique script identifier that indicates which script is to be deleted. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 425 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.29 authorizeScript Command This command is used by an authorization host to inform the EGM that the host authorizes initiation of the specified script. The EGM sends a scriptStatus command in response to the authorizeScript command. If a script has an authorizeList sub-element with one or more authorizeItem sub-elements, the script initiates when all authorization hosts have authorized the script. For example, if the script requires a G2S_operatorAction initiating event then the script will only execute after all authorization hosts have authorized and the operator has initiated at the EGM. Similarly, if the script specifies G2S_immediate then the script will initiate when the last of the hosts has authorized via the authorizeScript command. An authorization host may revoke its authorization after authorization by issuing an authorizeScript command with the authorized attribute set to false. Revoking authorization may be necessary if an authorization host detects that critical meters or logs have changed sometime after authorizing the script but before script execution. An authorization host may re-authorize a script after recapturing the critical meters or logs by issuing an authorizeScript command with the authorized attribute set to true. An authorization host may subscribe to the G2S_DLE207 event to discover when a script is waiting on host authorization. Possible error code responses: If the command references a non-existent script, a G2S_DLX005 error code will be returned. Table 10.39 authorizeScript Attributes Attribute Restrictions Description scriptId type: scriptId use: required Unique script identifier that indicates which script the command affects. authorized type: boolean use: required Indicates if the authorization host has authorized the script. true = authorized, false = not authorized. 10.30 getScriptStatus Command This command is used by a host to request the status of the specified script. The EGM sends a scriptStatus command in response to the getScriptStatus command. Possible error code responses: • The EGM will report the status of a script only if the script exists in the EGM’s scriptList. If the command references a non-existent script, a G2S_DLX005 error code will be returned. Table 10.40 getScriptStatus Attributes Attribute Restrictions Description scriptId type: scriptId use: required Unique script identifier that indicates which script the command affects. Page 426 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.31 scriptStatus Command This command is used by the EGM to report the status of a script to a host. • The scriptStatus command is sent in response to setScript, cancelScript, authorizeScript, and getScriptStatus commands. • The scriptStatus command is also sent whenever the scriptStatus reaches a terminal condition. The scriptStatus command is sent for the following conditions: scriptStatus = "G2S_completed". scriptStatus = "G2S_error". NOTE: scriptStatus = "G2S_cancelled" is considered a terminal condition, which is the result of processing a cancelScript command. Because the EGM will respond to the cancelScript command with a scriptStatus response, it would be redundant to send an EGM-originated scriptStatus command to indicate the same information; hence, the G2S_cancelled condition is not cause to send an EGM-originated scriptStatus command.) The scriptStatus element is also a sub-element of the scriptList command. Table 10.41 scriptStatus Attributes (Sheet 1 of 2) Attribute Restrictions Description scriptId type: scriptId use: required A host provided identifier that uniquely identifies the script. startDateTime type: dateTime use: optional default: <null> Start of the time window during which the script commands will be executed. endDateTime type: dateTime use: optional default: <null> End of the time window during which the script commands will be executed. disableCondition type: disableConditions use: required Conditions where the EGM will disable before script command initiation can occur. applyCondition type: applyConditions use: required Initiation condition that begins script command execution. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the changes specified in the script. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 427 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.41 scriptStatus Attributes (Sheet 2 of 2) Attribute Restrictions Description scriptStatus type: scriptStates use: required Indicates the current status of the script. scriptException type: scriptExceptions use: optional default: 0 Exception code associated with the scriptStatus. MUST be provided when the scriptStatus = "G2S_error". authorizeDateTime type: dateTime use: optional default: <null> Date and time when the script completed authorization. completeDateTime type: dateTime use: optional default: <null> Date and time when the script completed. Table 10.42 scriptStatus Elements Element Restrictions Description authorizeStatusList minOcc: 0 maxOcc: 1 Contains an optional list of authorize status elements for the script. See elements in Table 10.43. commandStatusList minOcc: 1 maxOcc: 1 Contains a list of script command status elements to execute with the script. See elements in Table 10.45. Table 10.43 authorizeStatusList Elements Element Restrictions Description authorizeStatus minOcc: 0 Contains script authorization status for each required authorization host. See attributes in Table 10.44. maxOcc: ∞ Table 10.44 authorizeStatus Attributes Attribute Restrictions Description hostId type: deviceId use: required Uniquely identifies the authorization host that is required for script authorization. authorizationState type: authorizationStates use: required Indicates the state of the authorization for the associated hostId. timeoutDate type: dateTime use: optional default: <null> Page 428 Timeout value for when the EGM should give up waiting on authorization from this host. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.45 commandStatusList Elements AT LEAST ONE ELEMENT REQUIRED Element Restrictions Description packageCmdStatus minOcc: 0 Contains status for a package command. See attributes in Table 10.46. maxOcc: moduleCmdStatus minOcc: 0 maxOcc: systemCmdStatus ∞ ∞ minOcc: 0 maxOcc: ∞ Contains status for a module command. See attributes in Table 10.47. Contains status for a system command. See attributes in Table 10.48. Table 10.46 packageCmdStatus Attributes Attribute Restrictions Description pkgId type: packageId use: required Uniquely identifies the package for the command. operation type: operPackage use: required Contains the specific operation for the command. commandString type: string use: optional maxLen: 256 default: <empty> Contains an optional manufacturer defined command string. deletePkgAfter type: boolean use: optional default: false Indicates that the package should be deleted from the package list (and internal storage) after the command has successfully completed. status type: operCmdStates use: required Contains the status of the command. exception type: operCmdExceptions use: optional default: 0 Exception code associated with the status. MUST be provided when the status = "G2S_error". cmdSequence type: int minIncl: 0 use: required A monotonically increasing sequence number (values begin from 1 (one)) used to order this script command with the other commands in the script. The value MUST be unique across all script commands that are subordinate to the commandStatusList element. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 429 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.47 moduleCmdStatus Attributes Attribute Restrictions Description pkgId type: packageId use: optional default: <null> Uniquely identifies the package for the command. modId type: moduleId use: required Uniquely identifies the module for the command. operation type: operModule use: required Contains the specific operation for the module command. status type: operCmdStates use: required Contains the status of the command. exception type: operCmdExceptions use: optional default: 0 Exception code associated with the status. MUST be provided when the status = "G2S_error". cmdSequence type: int minIncl: 0 use: required A monotonically increasing sequence number (values begin from 1 (one)) used to order this script command with the other commands in the script. The value MUST be unique across all script commands that are subordinate to the commandStatusList element. Table 10.48 systemCmdStatus Attributes Attribute Restrictions Description operation type: operSystem use: required Contains the specific operation for the system command. status type: operCmdStates use: required Contains the status of the command. exception type: operCmdExceptions use: optional default: 0 Exception code associated with the status. MUST be provided when the status = "G2S_error". cmdSequence type: int minIncl: 0 use: required A monotonically increasing sequence number (values begin from 1 (one)) used to order this script command with the other commands in the script. The value MUST be unique across all script commands that are subordinate to the commandStatusList element. 10.32 scriptStatusAck Command This command is sent by a host to acknowledge that the script status has changed. The scriptStatusAck command is sent in response to the scriptStatus command. There are no additional attributes or elements for this command. Page 430 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.33 getScriptList Command This command is used by a host to request the list of scripts from the EGM. The EGM sends a scriptList command in response to the getScriptList command. The getScriptList command has no additional attributes or elements. 10.34 scriptList Command This command is used by the EGM to report the list of scripts to a host. The scriptList command is sent in response to the getScriptList command. Table 10.49 scriptList Elements Element Restrictions Description scriptStatus minOcc: 0 Contains information for a single script within the script list. For element details, see the scriptStatus command, Section 10.31. maxOcc: 10.35 ∞ getScriptLogStatus Command This command is used by a host to request the current script log status from the EGM. The EGM sends a scriptLogStatus command in response to the getScriptLogStatus command. The getScriptLogStatus command has no additional attributes or elements. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 431 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.36 scriptLogStatus Command This command is used by the EGM to send the current status of the script log to a host. The scriptLogStatus command is sent in response to a getScriptLogStatus command. Table 10.50 scriptLogStatus Attributes Attribute Restrictions Description logSequence type: logSequence use: optional default: 0 minIncl: 0 The sequence number of the last transaction within the log. totalEntries type: int use: optional default: 0 minIncl: 0 The total number of transactions within the log. 10.37 getScriptLog Command This command is used by a host to request the current script log from the EGM. Additional information regarding the use of the lastSequence and totalEntries attributes can be found in Chapter 1. The EGM sends a scriptLogList command in response to the getScriptLog command. Table 10.51 getScriptLog attributes Attribute Restrictions Description logSequence type: logSequence use: optional default: 0 minIncl: 0 The sequence number of the transaction that should be the first entry in the list; if set to 0 (zero) then default to the last transaction. totalEntries type: int use: optional default: 0 minIncl: 0 The total number of transactions that should be included in the list; if set to 0 (zero) then defaults to all transactions. Page 432 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.38 scriptLogList Command This command is used by the EGM to send the contents of the script log to a host. The scriptLogList command is sent in response to a getScriptLog command. Table 10.52 scriptLogList Elements Element Restrictions Description scriptLog minOcc: 0 Contains information regarding a change in the package list, including the status of a package within the list. See attributes in Table 10.53 and elements in Table 10.54. maxOcc: ∞ Table 10.53 scriptLog Attributes (Sheet 1 of 2) Attribute Restrictions Description logSequence type: logSequence use: required Unique script log sequence number assigned by the EGM. deviceId type: deviceId use: required Device identifier of the download device that generated the script transaction. transactionId type: transactionId use: required minIncl: 1 Unique script transaction identifier assigned by the EGM. scriptId type: scriptId use: required A host provided identifier that uniquely identifies the script. startDateTime type: dateTime use: optional default: <null> Start of the time window during which the script commands will be executed. endDateTime type: dateTime use: optional default: <null> End of the time window during which the script commands will be executed. disableCondition type: disableConditions use: required Conditions where the EGM will disable before script command initiation can occur. applyCondition type: applyConditions use: required Initiation condition that begins script command execution. reasonCode type: reasonCodes use: optional default: <empty> An optional code to indicate the reason for the changes specified in the script. scriptStatus type: scriptStates use: required Indicates the current status of the script. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 433 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.53 scriptLog Attributes (Sheet 2 of 2) Attribute Restrictions Description scriptException type: scriptExceptions use: optional default: 0 Exception code associated with the scriptStatus. MUST be provided when the scriptStatus = "G2S_error". authorizeDateTime type: dateTime use: optional default: <null> Date and time when the script completed authorization. completeDateTime type: dateTime use: optional default: <null> Date and time when the script completed. Table 10.54 scriptLog Sub-Elements Element Restrictions Description authorizeStatusList minOcc: 0 maxOcc: 1 Contains an optional list of authorize status elements for the script. See Table 10.43 for element details. commandStatusList minOcc: 1 maxOcc: 1 Contains a list of script command status elements to execute with the script. See Table 10.45 for element details. 10.39 getModuleList Command This command is used by a host to request the list of modules from the EGM. The EGM sends a moduleList command in response to the getModuleList command. The getModuleList command has no additional attributes or elements. Page 434 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.40 moduleList Command This command is used by the EGM to report the list of modules to a host. The moduleList command is sent in response to the getModuleList command. An EGM manufacturer has the option to expose only the modules that it wants to. It is recommended that the EGM expose pertinent modules that may be updated or replaced via the download class. By doing so, the System Management Point has the option to evaluate what modules have outdated revisions (modReleaseNum), or to determine if the dependencies for a new package are already installed. If an EGM doesn’t provide pertinent module information, then the System Management Point may decide to download and install packages that may already be installed on the EGM, which is inefficient use of network resources. Table 10.55 moduleList Elements Element Restrictions Description moduleStatus minOcc: 0 Contains information for a single module within the module list. See attributes in Table 10.56 and elements in Table 10.57. maxOcc: ∞ Table 10.56 moduleStatus Attributes Attribute Restrictions Description modId type: moduleId use: required Uniquely identifies the module. modReleaseNum type: string use: optional default: <empty> maxLen: 32 Module release number. modStatus type: modStates use: required Indicates the current status of the module. modException type: modExceptions use: optional default: 0 Exception code associated with the modStatus. MUST be provided when the modStatus = "G2S_error". modType type: modTypes use: optional default: G2S_other Contains a manufacturer specified type such as OS, gameTheme, gamePaytable, firmware, and so on. modDescription type: descriptionText use: optional default: <empty> Contains an optional description of the module. Table 10.57 module Elements Element Restrictions Description storageUsed minOcc: 0 Storage used. See attributes in Table 10.58. maxOcc: ∞ gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 435 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.58 storageUsed Attributes Attribute Restrictions Description deviceClass type: deviceClass use: required Device class that the storage is associated with. deviceId type: deviceId use: required Device identifier that the storage is associated with. storageId type: storageId use: required A storage identifier that is unique within the device identified by deviceClass/deviceId. storageUsed type: long use: required minIncl: 0 Size of used storage in bytes. This includes any slack storage. storageApp type: storageApplication use: optional default: G2S_other Identifies how the module applies the storage. Page 436 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.41 Data Types The following table lists the data types specific to the download class: Table 10.59 download Class Data Types (Sheet 1 of 2) Data Type Restrictions Description transferId type: int minIncl: 0 A host provided identifier for a transfer. transferTypes type: string enumerations: Indicates the transfer type. See Section 10.41.1 transferStates type: string enumerations: Indicates the status of a package transfer. See Section 10.41.5 transferExceptions type: exceptionCode enumerations: Exception code associated with the transfer status (see transferStates). See Section 10.41.6 packageId type: uniqueIdentifier64 Package identifier. The first three characters should be the GSA-assigned manufacturer identifier. This value must be unique, including when new revisions of a package are created. pkgStates type: string enumerations: Indicates the status of a package. See Section 10.41.2 pkgExceptions type: exceptionCode enumerations: Exception code associated with the package status (see pkgStates). See Section 10.41.3 pkgFormats type: string Indicates format of the package payload. See Section 10.41.4 pkgActivityTypes type: string enumerations: G2S_other G2S_createPackage G2S_deletePackage Package activity. reasonCodes type: string maxLen: 10 Reason code associated with a package action or script. scriptId type: int minIncl: 0 A host provided identifier for a script. scriptStates type: string enumerations: Identifies the status of a script. See Section 10.41.7 scriptExceptions type: exceptionCode enumerations: Exception code associated with the script status (see scriptStates). See Section 10.41.8 operPackage type: string enumerations: Command operations that may be performed on a package. See Section 10.41.9 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 437 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.59 download Class Data Types (Sheet 2 of 2) Data Type Restrictions Description operModule type: string enumerations: Command operations that may be performed on a module. See Section 10.41.10 operSystem type: string enumerations: Command operation that may be performed at the system. See Section 10.41.11 operCmdStates type: string enumerations: Status for the command operation. See Section 10.41.12 operCmdExceptions type: exceptionCode enumerations: Exception code associated with an operation status (see data type operCmdStates). See Section 10.41.13 moduleId type: uniqueIdentifier64 Module identifier. The first three characters should be the GSA-assigned manufacturer ID. modStates type: string enumerations: The state of a module. See Section 10.41.14 modExceptions type: exceptionCode enumerations: Exception code associated with the module status (see data type modStates). See Section 10.41.16 modTypes type: string enumerations: Contains a manufacturer specified type such as etc. OS, gameTheme, gamePaytable, firmware, See Section 10.41.15 storageId type: int minIncl: -1 Storage identifier that is unique within a device. storageApplication type: string Identifies the storage application type for a given module. See Section 10.41.17 descriptionText 10.41.1 type: string maxLen: 128 Text to describe a package or module. TransferTypes Enumerations Table 10.60 transferTypes Data Type Enumerations Enumeration Description G2S_downloadGet The transfer is a download to the EGM, initiated by the EGM. G2S_downloadPut The transfer is a download to the EGM, initiated by the host. G2S_uploadGet The transfer is an upload from the EGM, initiated by the host. G2S_uploadPut The transfer is an upload from the EGM, initiated by the EGM. Page 438 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.41.2 pkgStates Enumerations Table 10.61 pkgStates Data Type Enumerations Enumeration Description G2S_pending The package is not yet present on the EGM, thus the package is not available. G2S_available The package has been either created or downloaded and validated, resulting in a package being available on the EGM. G2S_inUse The package is currently in use. This state may occur during installation or uninstallation of a package. G2S_deletePending The package is marked for deletion. This state indicates that a deletePackage command was applied to this package during package transfer, installation, or uninstallation. When the package completes its transfer, installation, or uninstallation it will be deleted. G2S_deleted The package was deleted by a deletePackage command, or was deleted because the download transfer was refused, failed or aborted. G2S_error The package has an error. 10.41.3 pkgExceptions Enumerations Table 10.62 pkgExceptions Data Type Enumerations Exception Code Description 0 No exceptions. 1 Undefined exception. 9 Validation failed. 10.41.4 pkgFormats Enumerations Table 10.63 pkgFormats Data Type Enumerations Enumeration Description G2S_other The package payload format is not defined. G2S_binary The package payload format is a miscellaneous binary format G2S_tar The package payload format is a standard TAR format. G2S_zip The package payload format is a standard ZIP format. 10.41.5 transferStates Enumerations Table 10.64 transferStates Date Type Enumerations Enumeration Description G2S_pending The package transfer has not started. G2S_inProgress The package transfer has started. This includes partially transferred packages. G2S_transferred The package transfer completed successfully. G2S_validated The package passed validation. G2S_error The package transfer resulted in an error. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 439 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.41.6 transferExceptions Enumerations Table 10.65 transferExceptions Data Type Enumerations Exception Code Description 0 No exceptions. 1 Undefined exception. 2 Transfer refused by transfer host. 3 Transfer aborted by EGM. 4 Transfer aborted by System Management Point. 5 Transfer aborted by transfer host. 6 Transfer failed. Insufficient storage. 7 Transfer failed. Invalid pkgLocation. 8 Transfer failed. Invalid pkgId. 9 Validation failed. 10 Transfer host unreachable. 11 Transfer host cannot be authenticated. 10.41.7 scriptStates Enumerations Table 10.66 scriptStates Data Type Enumerations Enumeration Description G2S_pendingDateTime The script is waiting for the startDateTime, if the script specifies the attribute. G2S_pendingDisable The script is waiting for the EGM to disable. This state implies that the date/time conditions have been met, if specified. G2S_pendingAuthorization The script is waiting for authorization from the authorization host(s). This state implies that the disable conditions have been met and the script contains one or more unfulfilled authorizeItem sub-elements in its authorizeList sub-elements. G2S_pendingOperatorAction The script is waiting for the operator initiation. This state implies that the disable conditions have been met and any required authorizations have been fulfilled. G2S_pendingPackage The script is waiting for a package to be transferred and validated. G2S_inProgress The script is executing its list of commands. G2S_completed The script completed successfully. G2S_cancelled The script was cancelled. G2S_error There was an error during execution of the script. Page 440 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.41.8 scriptExceptions Enumerations Table 10.67 scriptExceptions Data Type Enumerations Exception Code Description 0 No exceptions. 1 Undefined exception. 2 Script aborted by EGM. 3 Script aborted by System Management Point. 4 Script failed. Script time expired. 5 Script failed. Authorization timeout. 6 Script failed. Insufficient storage. 7 Script failed. Command failed. 8 Script failed. Failed dependency check. 10.41.9 operPackage Enumerations Table 10.68 operPackage Data Type Enumerations Enumeration Description G2S_install Install all modules contained in the package. G2S_uninstall Uninstall all modules referenced in the package. G2S_exec Execute a command in the package. 10.41.10 operModule Enumerations Table 10.69 operModule Data Type Enumerations Enumeration Description G2S_install Install the specified module that is contained in the specified package. G2S_uninstall Uninstall the module. 10.41.11 operSystem Enumerations Table 10.70 operSystem Data Type Enumerations Enumeration Description G2S_disableEgm Disable the EGM. G2S_enableEgm Enable the EGM. G2S_resetEgm Reset the EGM. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 441 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.41.12 operCmdStates Enumerations Table 10.71 operCmdStates Data Type Enumerations Enumeration Description G2S_pending The command is pending. G2S_inProgress The command is in the process of executing. G2S_complete The command successfully completed. G2S_cancelled The command was cancelled via cancelScript command. G2S_error An error occurred while executing the associated command. 10.41.13 operCmdExceptions Enumerations Table 10.72 operCmdExceptions Data Type Enumerations Exception Code Description 0 No exceptions. 1 Undefined exception. 2 Package is not available. 3 Unable to execute command, insufficient storage. 4 Unable to execute command, package dependency error. 5 Unable to execute command, package corruption. 6 Unable to execute package commandString. 7 Unable to uninstall package. 8 Module is not available. 9 Unable to uninstall module. 10 Unable to disable EGM. 11 Unable to enable EGM. 12 Unable to reset EGM. 10.41.14 modStates Enumerations Table 10.73 modStates Data Type Enumerations Enumeration Description G2S_disabled The module is installed but is disabled. G2S_enabled The module is installed and enabled. G2S_error There was an error during the installation. Page 442 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.41.15 modTypes Enumerations Table 10.74 modTypes Data Type Enumerations Enumeration Description G2S_other Undefined module type. G2S_boot Module type used to boot the EGM. G2S_os Module associated with EGM’s operating system. G2S_game Module associated with the game such as theme, paytable, language, executable, and so on. G2S_firmware Module associated with peripheral firmware such as printer, note acceptor, and so on. G2S_configuration Module associated with configuration data. 10.41.16 modException Enumerations Table 10.75 modException Data Type Enumerations Exception code Description 0 No exceptions. 1 Undefined exception. 2 Module failed validation. 10.41.17 storageApplication Enumerations Table 10.76 storageApplication Data Type Enumerations Enumeration Description G2S_download Storage application type for a download buffer used to store packages. G2S_boot Storage application type that contains modules associated with the boot partition. G2S_os Storage application type that contains modules associated with the operating system. G2S_game Storage application type that contains modules associated with games (game play devices). G2S_internal Storage application type associated with a peripheral device such as the note acceptor or printer devices. G2S_other Storage application type that doesn’t conform to any of the other types. G2S_configuration Storage application type associated with a configuration data. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 443 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.42 Error Codes The following table lists the error codes for the download class. Table 10.77 download Class Error Codes Error Code Suggested Error Text G2S_DLX001 Command References A Non-Existent Package G2S_DLX002 Command References An Already Existent Package G2S_DLX003 Command References A Package During Script Execution G2S_DLX004 Unable To add Package, The Package List Is Full G2S_DLX005 Command References A Non-Existent Script G2S_DLX006 Command References An Already Existent Script G2S_DLX007 Command References A Script During Execution G2S_DLX008 Unable To Add Script, The Script List Is Full G2S_DLX009 Command References A Non-Existent Module G2S_DLX010 Unable To Process uploadPackage Command, The Package Currently Has An Outstanding Upload Transfer Request G2S_DLX011 Unable To Read Contents Of The Specified Package G2S_DLX012 Insufficient Storage To Create Package Related Command G2S_DLX013 Transfer Type Not Supported G2S_DLX014 Script Too Complex. EGM Unable To Save All Script Commands G2S_DLX015 Script Command Contains An Invalid commandString G2S_DLX016 Cannot Create Package. Unsupported pkgFormat G2S_DLX017 Invalid cmdSequence Values In The setScript Command Page 444 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.43 Event Codes The following table lists the event codes specific to the download class. Table 10.78 download Class Event Codes (Sheet 1 of 2) (DL = download) Affected Device Logs, Meters, Status Event Code and Event Title DL G2S_DLE001 Device Disabled by EGM S G2S_DLE002 Device Enabled by EGM S G2S_DLE003 Device Disabled by Host S G2S_DLE004 Device Enabled by Host S G2S_DLE005 Device Configuration Changed by Host G2S_DLE006 Device Configuration Changed at EGM G2S_DLE007 EGM Locked by Device S G2S_DLE008 EGM Unlocked by Device S G2S_DLE101 Package Added L G2S_DLE102 Package Download Initiated L G2S_DLE103 Package Download Refused L G2S_DLE104 Insufficient Storage for Package Download L G2S_DLE105 Package Download in Progress L G2S_DLE106 Package Download Complete L G2S_DLE107 Package Download Aborted L G2S_DLE108 Package Passed Validation L G2S_DLE109 Package Failed Validation L G2S_DLE110 Package Created L G2S_DLE120 Package Upload Requested L G2S_DLE121 Package Upload Initiated L G2S_DLE122 Package Upload Refused L G2S_DLE123 Package Upload in Progress L G2S_DLE124 Package Upload Complete L G2S_DLE125 Package Upload Aborted L G2S_DLE140 Package Deleted L G2S_DLE201 Script Set L G2S_DLE202 Script Authorization Enabled by Host L G2S_DLE203 Script Authorization Disabled by Host L G2S_DLE204 Script Time Started L G2S_DLE205 Script Time Ended L G2S_DLE206 Script EGM Disable Started L G2S_DLE207 Script Waiting on Authorization L gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 445 Chapter 10 download Class G2S™ Message Protocol v1.0.3 Table 10.78 download Class Event Codes (Sheet 2 of 2) (DL = download) Affected Device Logs, Meters, Status Event Code and Event Title DL G2S_DLE208 Script Waiting on Operator Initiation L G2S_DLE209 Script Initiated, Commands Executing L G2S_DLE210 Script Command Execution In Progress L G2S_DLE211 Script Completed L G2S_DLE212 Script Error L G2S_DLE213 Script Cancelled L G2S_DLE301 Module Added G2S_DLE302 Module Deleted G2S_DLE303 Module Enabled G2S_DLE304 Module Disabled G2S_DLE305 Module Error The following table lists the elements contained within the download class which may be included as affected data with events: Table 10.79 Elements Included With Events Affected Data Element Device Status downloadStatus Package Status packageStatus Script Status scriptStatus Package Record packageLog Script Record scriptLog Page 446 gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.43.1 evaluate(state) The egmEnabled and egmState attributes are both determined from multiple factors. If all of the faults for a device have been cleared then the egmEnabled attribute for the device can be set to true. If any one fault still exists then the egmEnabled attribute MUST be set to false. Thus, after a fault is cleared, the EGM MUST evaluate all of the attributes that contribute to the state of the egmEnabled attribute. If any of them shows a fault then the egmEnabled attribute MUST remain set to false. This is communicated in the following documentation by using the convention "evaluate(device.egmEnabled)". Likewise, the egmState attribute of the cabinetStatus reflects the aggregate state of all devices in the EGM. If the requiredForPlay attribute in the profile of a device is set to true then if either the egmEnabled or hostEnabled attribute of the device is set to false then the egmState MUST reflect that the EGM is disabled. Similarly, if the egmLocked or hostLocked attribute of a device is set to true then the egmState MUST reflect that the EGM is locked out. If any one device is in such a state then the egmState MUST reflect that the EGM is disabled or locked-out, as appropriate. Thus, after a device has been enabled or a lockout has been cleared, the EGM MUST evaluate the state of all active devices within the EGM to determine the proper value of the egmState attribute. At the same time, the deviceClass and deviceId attributes of the cabinetStatus MUST be updated to reflect the appropriate device. This is communicated in the following documentation by using the convention "evaluate(cabinet.egmState)". 10.43.2 G2S_DLE001 Device Disabled by EGM This event is sent by the EGM after the device has been disabled by the EGM. If the device was already disabled by the EGM then no event will be sent. When the download device is disabled, any active transfers and executing scripts MAY continue; however, any pending transfers and scripts will be deferred until the download device is enabled again. Table 10.80 G2S_DLE001 Device, Meter, Log Changes, and Related Commands Details Device State Changes download.egmEnabled = "false"; are functional. evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 10.43.3 however, all of the download commands G2S_DLE002 Device Enabled by EGM This event is sent by the EGM after the device has been enabled by the EGM. If the device was already enabled then no event will be sent. Table 10.81 G2S_DLE002 Device, Meter, Log Changes, and Related Commands Details Device State Changes download.egmEnabled = "true". evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. gsa-p0075.003.01 Released: 2007/04/12 © 2006 - 2007 Gaming Standards Association (GSA) Page 447 Chapter 10 download Class G2S™ Message Protocol v1.0.3 10.43.4 G2S_DLE003 Device Disabled by Host This event is sent by the EGM after the device has been disabled by the host. If the device was already disabled by the host then no event will be sent. When the download device is disabled, any active transfers and executing scripts MAY continue; however, any pending transfers and scripts will be deferred until the download device is enabled again. Table 10.82 G2S_DLE003 Device, Meter, Log Changes, and Related Commands Details Device State Changes download.hostEnabled = "false"; are functional. evaluate(cabinet.egmState). Meter State Changes None. Log State Changes None. Related Commands None. 10.43.5 however, all of the download commands G2S_DLE004 Device Enabled by Host This event is sent by the EGM after the device has been enabled by the host. If the device was already enabled then no event will be sent. Table 10.83 G2S_DLE004 Device, Meter, Log Changes, and Related Commands Details Device State Changes download.hostEnabled = "true". evaluate(cabinet

edoc.site g2s103

Related documents

Add this document to collection(s)

Add this document to saved

Suggest us how to improve StudyLib