5.1 Switches

Switches are present in all pinball games to receive input from the ball and the player.

Switches are numbered from 0 to NUM_SWITCHES-1. How the switch numbers are mapped to actual inputs is platform and machine dependent. The machine description names the switches and defines their physical characteristics.

Each switch entry can declare the following flags, which alter the way that the switching code will manage it. The capitalized name is used in the C code; the lowercase name is the spelling used in the machine config file.

• SW_OPTICAL (opto)

  Says that this is an optical switch, which is active low rather than active high.

• SW_EDGE (edge)

  Says that the event handler (CALLSET_ENTRY) should be thrown in both directions: when it becomes inactive or active. Handlers for edge switches generally need to check which type of transition just happened, by calling switch_poll_logical, and then act accordingly.

  All counting switches in a ball container must be edge switches, so that the device count can be updated correctly. The shooter switch is also usually declared edge.

• SW_IN_GAME (ingame)

  Says that this switch should only be serviced during a game.

• SW_PLAYFIELD

  Says that this switch is on the playfield, and can be activated by a ball, as opposed to cabinet buttons, motor optos, etc. A playfield switch event will normally set the valid playfield flag. It will also cause the any_pf_switch event to be thrown, which is normally used to score during "frenzy" modes. These switches also reset the ball search timer to prevent a search from starting.

  This is the default; use the noplay tag to indicate that a switch is not playfield scoring.

• SW_NOVALID (novalid)

  Set for a SW_PLAYFIELD switch for which the valid playfield flag should not automatically be set. This is used for switches that might unreasonably activate not due to a ball, such as a misaligned jet bumper that continually fires.

  These are the switches that you can trigger at ball start and drain, and still get the ball back.

• SW_IN_TEST (intest)

  Says that this switch handler should also be called in test mode. Normally in test mode handlers are not called, but important switches like cabinet buttons require this. If this flag is set, handlers will need to test the in_test variable to see if we are in test mode, and act accordingly.

In addition to polling their levels, the switch driver will detect when switches have changed state, and invoke their event handlers. The switch entry in the config file names a function to be called when these changes occur. These functions are always called from within their own task context.

The driver performs debouncing, so that rapid open and close are not considered. By default, a switch is processed if it remains active for only 4ms. You can declare a larger debounce time using the debounce tag. A transition that lasts for less time is ignored.

Switch entries can also declare an associated playfield lamp; when this is done, valid activations of the switch will cause a brief flicker of the lamp.

switch_poll

Read the stable, physical state of a switch. Returns nonzero if it has a high level, or zero for a low level.

Switch readings are polled by the switch driver continuously; this API just returns the results of the last time the switch was examined. How often switches are polled is platform-dependent; on WPC, it is every 2ms.

switch_poll_logical

Read the stable, logical state of a switch. Returns nonzero if it is active, or zero for inactive. This is the same as switch_poll but it inverts its result for optos.

rt_switch_poll

Like switch_poll, but only for use inside realtime tasks. It is slightly more efficient. It always returns a physical level; drivers must invert for optos.