5.3 Solenoids

Solenoid outputs are used for many purposes. We use the term 'solenoid' or 'coil' generically to refer to any writable, high power output. They could be connected to coils, flashers, or motors. Like the lamps, they are individually controllable.

Unlike the controlled lamps, the core API does not permit you to turn on a solenoid permanently. Instead, you either use a pulsing API, which turns it on for a short period of time (and the system turns it back off for you), or you use a custom driver to control it.

5.3.1 Pulsing

Pulsing is used for solenoids that are operated infrequently, and only for short durations at a time. These are normally used for kickers, poppers, etc. The system queues the requests and executes them one at a time, never in parallel.

The default pulse settings are controlled by the entry in the machine description, in the "drives" section. The time parameter sets the total length of time for the pulse. It can be an integer value in milliseconds, or one of the TIME_xxx values which are in multiples of 16ms. The duty parameter controls the duty cycle; use one of the SOL_DUTY_xxx defines. SOL_DUTY_100 keeps the driver on for the entire interval; SOL_DUTY_50 keeps it on half the time, delivering half the power; and so on. The minimum duty cycle is 1/8th full power.

If you do not specify either of these values, you will get a reasonable, but conservative default. Solenoids and flashers may have different default values. A large portion of getting a new game to work correctly is determining the correct values to use here.

sol_request

Pulse a solenoid, and wait for it to be fired. A request may be delayed for a number of reasons. This should only be used inside of a task context where it is acceptable that the call may block for a while.

sol_request_async

Pulse a solenoid, but don't wait for it to be fired. This is the preferred method to use. This function returns immediately, before the pulse occurs.

sol_req_start_specific

This is the most flexible API, which allows you to specify the exact duty and time parameters that you want, overriding the defaults from the machine config. It is not recommended for ordinary use. It is exposed by test mode to allow you to try different settings to see how they behave.

5.3.2 Flashers

The flashlamp APIs are similar to the solenoid pulse APIs. A flashlamp pulse is always with a 100% duty cycle, but for a much shorter period of time.

Note: it is currently possible to use the solenoid pulse APIs on flashers, but this should not be done. This will likely be enforced in the future.

flasher_pulse

Pulse a flashlamp for a nominal period of time.

flasher_pulse_short

Pulse a flashlamp very quickly.

flasher_start

This is a lower-layer API that allows you to specify the exact duration and duty cycle for a flasher. Times longer than FLASHER_TIME_DEFAULT are not recommended. The duty cycle can be specified using one of the SOL_DUTY_xxx defines to pulse it more dimly than usual.

5.3.3 Custom Drivers

Custom drivers can run for longer periods of time. They are allowed to run in parallel with anything else. They will frequently use duty cycling to avoid keeping the coil 100% active for too long, and thus they often require realtime processing to switch reliably.

These types of drivers are all implemented using templates.