Uploaded by Евгений Харецкий

edoc.site g2s103

advertisement
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: [email protected]
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:
[!&quot;#$%&amp;&apos;()*+,\-\./0-9:;&lt;=&gt;\[email protected]\[\\\]\^_`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
&
&amp;
Ampersand
<
&lt;
Less Than
>
&gt;
Greater Than
"
&quot;
Quote
'
&apos;
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: reasonC