Merge pull request #527 from worldpeace-germany/main

Fixed class naming duplicate _player in API

docs/code/BCP_Protocol/ball_end.md

@@ -0,0 +1,15 @@
+
+## ball_end (BCP command)
+
+Indicates the ball has ended. Note that this does not necessarily mean that the next player’s turn will start, as this player may have an extra ball which means they’ll shoot again.
+
+## Origin
+Pin controller
+
+## Parameters
+None
+
+## Response
+
+None
+

docs/code/BCP_Protocol/ball_start.md

@@ -0,0 +1,21 @@
+
+# ball_start (BCP command)
+
+Indicates a new ball has started. It passes the player number (1, 2, etc.) and the ball number as parameters. This command will be sent every time a ball starts, even if the same player is shooting again after an extra ball.
+
+## Origin
+Pin controller
+
+## Parameters
+### player_num
+Type: `int`
+
+The player number.
+
+### ball
+Type: `int`
+
+The ball number.
+
+## Response
+None

docs/code/BCP_Protocol/device.md

@@ -0,0 +1,30 @@
+
+# device (BCP command)
+
+## Origin
+Pin controller or media controller
+
+## Parameters
+### type
+
+Type: `string`
+
+The type/class of device (ex: coil).
+
+### name
+Type: `string`
+
+The name of the device.
+
+### changes
+Type: `tuple` (attribute name, old value, new value)
+
+The change to the device state.
+
+### state
+Type: varies (depending upon device type)
+
+The device state.
+
+## Response
+None

docs/code/BCP_Protocol/error.md

@@ -0,0 +1,20 @@
+
+# error (BCP command)
+This is a command used to convey error messages back to the origin of a command.
+
+## Origin
+Pin controller or media controller
+
+## Parameters
+### message
+Type: `string`
+
+The error message.
+
+### command
+Type: `string`
+
+The command that was invalid and caused the error.
+
+## Response
+None

docs/code/BCP_Protocol/goodbye.md

@@ -0,0 +1,12 @@
+
+# goodbye (BCP command)
+Lets one side tell the other than it’s shutting down.
+
+## Origin
+Pin controller or media controller
+
+## Parameters
+None
+
+## Response
+None

docs/code/BCP_Protocol/hello.md

@@ -0,0 +1,26 @@
+
+# hello (BCP command)
+This is the initial handshake command upon first connection. It sends the BCP protocol version that the origin controller speaks.
+
+## Origin
+Pin controller or media controller
+
+## Parameters
+### version
+Type: `string`
+
+The BCP communication specification version implemented in the controller (ex: 1.0).
+
+### controller_name
+Type: `string`
+
+The name of the controller (ex: Mission Pinball Framework).
+
+### controller_version
+Type: `string`
+
+The version of the controller (ex: 0.33.0).
+
+## Response
+
+When received by the media controller, this command automatically triggers a hard “reset”. If the pin controller is sending this command, the media controller will respond with either its own “hello” command, or the error “unknown protocol version.” The pin controller should never respond to this command when it receives it from the media controller; that would trigger an infinite loop.

docs/code/BCP_Protocol/index.md

@@ -0,0 +1,97 @@
+
+# BCP Protocol Specification
+
+This document describes the Backbox Control Protocol, (or “BCP”), a simple, fast protocol for communications between an implementation of a pinball game controller and a multimedia controller.
+
+!!! note
+
+    BCP is how the MPF core engine and the MPF media controller communicate.
+
+BCP transmits semantically relevant information and attempts to isolate specific behaviors and identifiers on both sides. i.e., the pin controller is responsible for telling the media controller “start multiball mode”. The pin controller doesn’t care what the media controller does with that information, and the media controller doesn’t care what happened on the pin controller that caused the multiball mode to start.
+
+BCP is versioned to prevent conflicts. Future versions of the BCP will be designed to be backward compatible to every degree possible. The reference implementation uses a raw TCP socket for communication. On localhost the latency is usually sub-millisecond and on LANs it is under 10 milliseconds. That means that the effect of messages is generally under 1/100th of a second, which should be considered instantaneous from the perspective of human perception.
+
+It is important to note that this document specifies the details of the protocol itself, not necessarily the behaviors of any specific implementations it connects. Thus, there won’t be details about fonts or sounds or images or videos or shaders here; those are up to specific implementation being driven.
+
+!!! warning "Infinite Loops Possible"
+
+    Since the pin controller and media controller are both state machines synchronized through the use of commands, it is possible for the programmer to inadvertently set up infinite loops. These can be halted with the [reset](reset.md) command or [hello](hello.md) described below.
+
+
+## Background
+
+While the BCP protocol was created as part of the MPF project, the intention is that BCP is an open protocol that could connect any pinball controller to any media controller.
+
+
+## Protocol Format
+
+* Commands are human-readable text in a format similar to URLs, e.g. `command?parameter1=value&parameter2=value`
+* Command characters are encoded with the utf-8 character encoding. This allows ad-hoc text for languages that use characters past ASCII-7 bit, such as Japanese Kanji.
+* Command and parameter names are whitespace-trimmed on both ends by the recipient
+* Commands are case-insensitive
+* Parameters are optional. If present, a question mark separates the command from its parameters
+* Parameters are in the format `name=value`
+* Parameter names are case-insensitive
+* Parameter values are case-sensitive
+* Simple parameter values are prefixed with a string that indicates their data type: (`int:`, `float:`, `bool:`, `NoneType:`). For example, the integer 5 would appear in the command string as `int:5`.
+* When a command includes one or more complex value types (list or dict) all parameters are encoded using JSON and the resulting encoded value is assigned to the `json:` parameter.
+* Parameters are separated by an ampersand (`&`)
+* Parameter names and their values are escaped using percent encoding as necessary; (details here).
+* Commands are terminated by a line feed character (`\n`). Carriage return characters (`\r`) should be tolerated but are not significant.
+* A blank line (no command) is ignored
+* Commands beginning with a hash character (`#`) are ignored
+* If a command passes unknown parameters, the recipient should ignore them.
+* The pinball controller and the media controller must be resilient to network problems; if a connection is lost, it can simply re-open it to resume operation. There is no requirement to buffer unsendable commands to transmit on reconnection.
+* Once initial handshaking has completed on the first connection, subsequent re-connects do not have to handshake again.
+* An unrecognized command results in an error response with the message “unknown command”
+
+In all commands referenced below, the `\n` terminator is implicit. Some characters in parameters such as spaces would really be encoded as `%20` (space) in operation, but are left unencoded here for clarity.
+
+## Initial Handshake
+
+When a connection is initially established, the pinball controller transmits the following command:
+
+```
+hello?version=1.0
+```
+
+…where 1.0 is the version of the Backbox protocol it wants to speak. The media controller may reply with one of two responses:
+
+```
+hello?version=1.0
+```
+
+…indicating that it can speak the protocol version named, and reporting the version it speaks, or
+
+```
+error?message=unknown protocol version
+```
+
+…indicating that it cannot. How the pin controller handles this situation is implementation-dependent.
+
+## BCP commands
+
+The following BCP commands have been defined (and implemented) in MPF:
+
+* [ball_end](ball_end.md)
+* [ball_start](ball_start.md)
+* [device](device.md)
+* [error](error.md)
+* [goodbye](goodbye.md)
+* [hello](hello.md)
+* [machine_variable](machine_variable.md)
+* [mode_start](mode_start.md)
+* [mode_stop](mode_stop.md)
+* [monitor_start](monitor_start.md)
+* [monitor_stop](monitor_stop.md)
+* [player_added](player_added.md)
+* [player_turn_start](player_turn_start.md)
+* [player_variable](player_variable.md)
+* [register_trigger](register_trigger.md)
+* [remove_trigger](remove_trigger.md)
+* [reset](reset.md)
+* [reset_complete](reset_complete.md)
+* [switch](switch.md)
+* [trigger](trigger.md)
+
+

docs/code/BCP_Protocol/machine_variable.md

@@ -0,0 +1,30 @@
+
+# machine_variable (BCP command)
+This is a generic “catch all” which sends machine variables to the media controller any time they change. Machine variables are like player variables, except they’re maintained machine-wide instead of per-player or per-game. Since the pin controller will most likely track hundreds of variables (with many being internal things that the media controller doesn’t care about), it’ s recommended that the pin controller has a way to filter which machine variables are sent to the media controller.
+
+## Origin
+Pin controller
+
+## Parameters
+### name
+Type: `string`
+
+This is the name of the machine variable.
+
+### value
+Type: Varies depending upon the variable type.
+
+This is the new value of the machine variable.
+
+### prev_value
+Type: Varies depending upon the variable type.
+
+This is the previous value of the machine variable.
+
+### change
+Type: Varies depending upon the variable type.
+
+If the machine variable just changed, this will be the amount of the change. If it’s not possible to determine a numeric change (for example, if this machine variable is a string), then this change value will be set to the boolean True.
+
+## Response
+None

docs/code/BCP_Protocol/mode_start.md

@@ -0,0 +1,20 @@
+
+# mode_start (BCP command)
+A game mode has just started. The mode is passed via the name parameter, and the mode’s priority is passed as an integer via the priority.
+
+## Origin
+Pin controller
+
+## Parameters
+### name
+Type: `string`
+
+The mode name.
+
+### priority
+Type: `int`
+
+The mode priority.
+
+## Response
+None

docs/code/BCP_Protocol/mode_stop.md

@@ -0,0 +1,16 @@
+
+# mode_stop (BCP command)
+Indicates the mode has stopped.
+
+## Origin
+Pin controller
+
+## Parameters
+### name
+
+Type: `string`
+
+The mode name.
+
+## Response
+None

docs/code/BCP_Protocol/monitor_start.md

@@ -0,0 +1,26 @@
+
+# monitor_start (BCP command)
+
+New in version 0.33.
+
+Request from the media controller to the pin controller to begin monitoring events in the specified category. Events will not be automatically sent to the media controller from the pin controller via BCP unless they are requested using the monitor_start or register_trigger commands.
+
+## Origin
+Media controller
+
+## Parameters
+### category
+Single string value, type: one of the following options: events, devices, machine_vars, player_vars, switches, modes, ball, or timer.
+
+The value of category determines the category of events to begin monitoring. Options for category are:
+
+* `events` - All events in the pin controller
+* `devices` - All device state changes
+* `machine_vars` - All machine variable changes
+* `player_vars` - All player variable changes
+* `switches` - All switch state changes
+* `modes` - All mode events (start, stop)
+* `core_events` - Core MPF events (ball handing, player turn, etc.)
+
+## Response
+None

docs/code/BCP_Protocol/monitor_stop.md

@@ -0,0 +1,26 @@
+
+# monitor_stop (BCP command)
+
+New in version 0.33.
+
+Request from the media controller to the pin controller to stop monitoring events in the specified category. Once a monitor has been started, events will continue to be automatically sent to the media controller from the pin controller via BCP until they are stopped using the monitor_stop or remove_trigger commands.
+
+## Origin
+Media controller
+
+## Parameters
+### category
+Single string value, type: one of the following options: events, devices, machine_vars, player_vars, switches, modes, ball, or timer.
+
+The value of category determines the category of events to stop monitoring. Options for category are:
+
+* `events` - All events in the pin controller
+* `devices` - All device state changes
+* `machine_vars` - All machine variable changes
+* `player_vars` - All player variable changes
+* `switches` - All switch state changes
+* `modes` - All mode events (start, stop)
+* `core_events` - Core MPF events (ball handing, player turn, etc.)
+
+## Response
+None

docs/code/BCP_Protocol/player_added.md

@@ -0,0 +1,15 @@
+
+# player_added (BCP command)
+A player has just been added, with the player number passed via the player_num parameter. Typically these commands only occur during Ball 1.
+
+## Origin
+Pin controller
+
+## Parameters
+### player_num
+Type: `int`
+
+The player number just added.
+
+## Response
+None

docs/code/BCP_Protocol/player_turn_start.md

@@ -0,0 +1,15 @@
+
+# player_turn_start (BCP command)
+A new player’s turn has begun. If a player has an extra ball, this command will not be sent between balls. However, a new ball_start command will be sent when the same player’s additional balls start.
+
+## Origin
+Pin controller
+
+## Parameters
+### player_num
+Type: `int`
+
+The player number.
+
+## Response
+None