PWMWorker

Data Sheet

24-channel PWM controller with I2C interface

PWMWorker is a firmware program for the Raspberry Pi Pico that turns the Pico into a PWM (Pulse-Width Modulation) controller chip, in imitation of dedicated PWM chips like TLC59116 and PCA9685. Like those chips, PWMWorker provides an I2C interface that lets a host microcontroller (for example, another Pico, perhaps running the Pinscape Pico firmware), control a set of output pins with PWM.

The mainstream chips in this class are designed primarily to control arrays of LEDs (indeed, the category where you'll find most of them listed on Mouser and DigiKey is "LED driver chips"), but there's really nothing that limits them to LEDs, since the output ports are ultimately just electronic switches. They can be used to switch almost any sort of device, especially if the output ports are used as inputs to amplifier circuits that increase their current and voltage drive limits. In virtual pinball machines, they can be used to control feedback devices, including lights, solenoids, and motors. And even though the chips are nominally PWM controllers, the PWM capability doesn't have to be exercised for every port; a port can equally well act as a simple on/off switch for a device that doesn't need (or can't use) PWM, simply by limiting the duty cycle settings on that port to 0% and 100%.

PWMWorker was created as part of the Pinscape Pico project, but it's a completely standalone device that can be used in any project that calls for a PWM controller chip. Any host microcontroller compatible with a 3.3V I2C bus can be used, and you don't need any Pinscape software on the host controller, since PWMWorker provides a well-defined and fully documented I2C register interface.

This data sheet documents the Pico PWMWorker system from the perspective of a hardware designer who wishes to use the device as part of a circuit board, in place of one of the more conventional PWM controller chips. It describes how to wire the Pico into your circuit board at the hardware level, and how to access the I2C interface to control the device from your main I/O controller's software. PWMWorker's I2C command set is very similar (intentionally) to the interfaces exposed by most of the commercial PWM controller chips (which are mostly very similar to one another), with the goal of making it relatively easy to adapt a host-side software driver that you've already created for one of those other chips to this new "chip". This design doesn't attempt to be a drop-in replacement for any specific commercial chip, but it's meant to be similar enough to those chips in its conventions that it's a low-effort substitute.

The PWM outputs are implemented as Pico GPIOs, so each output port is a 3.3V push-pull driver capable of sourcing and sinking about 10mA per pin. This makes the device suitable for driving small LEDs directly. Ports can also be used to drive larger loads by connecting them to amplifier circuits that accept logic-level inputs; several examples of suitable booster circuits are presented later in this document. Ports can be configured with active-high or active-low outputs, providing the flexibility to use amplifier circuits that require either kind of trigger level. The ports can be enabled and disabled as a group.

At Pico reset, all GPIO ports (and thus all of the OUTn ports) are configured as inputs, which connects the ports to GND through a high-value resistor (about 50K ohms) internal to the Pico. This is the OUTn port state we refer to as "disabled". This makes it possible to design external booster circuits for glitch-free startup - that is, guaranteeing that all amplified output ports remain OFF throughout the power-up and software initialization process, without even brief activation.

Features, benefits, and tradeoffs:

• DIY-friendly form factor. The Pico comes in a size that's easy to work with for hand-soldering, with standard 0.1" pin headers for all connections. This was the primary motivation for the whole project, in that I couldn't find any commercial PWM controller chips that are easy to solder by hand. All of the chips currently in production come in fine-pitch SMD packages that are challenging to work with if you're not a robot. This easy handling comes at a cost, though, which is that the Pico has a much larger footprint than any of the mainstream chips. That's great for DIYers, but it's a a significant negative point for board designers planning on factory assembly. If you're going to have a robot do the assembly work, then you'll probably prefer using SMD parts, the smaller the better, since that reduces cost by increasing circuit board density.
• Competitive pricing. A Pico retails in single units for about $4, and provides 24 PWM output channels. TLC59116 and PCA9685 sell for about $2 each in retail quantities, but only handle 16 channels, so you'd need 1½ of those chips for each Pico, raising the comparison price to about $3. The Pico, then, is more expensive, but only slightly. On the other hand, when the mainstream chips can be purchased in bulk, their per-unit cost drops significantly, so they'll have a greater cost advantage for commercial manufacturers planning large production runs.
• Ready availability. The Pico has been widely available since its introduction, while some of the dedicated PWM chips have been affected by the general semiconductor shortage of recent years.
• Push-pull output ports. The output ports are implemented as Pico GPIO ports in OUTPUT mode, which function as 3.3V push-pull drivers. This configuration is convenient for some applications and less convenient for others, so this could be a plus or a minus, depending on your use case. Many of the TI PWM chips are available in a constant current sink configuration, which is extremely convenient for driving arrays of identical LEDs, or for driving optocouplers. The push-pull configuration is usable for driving small LEDs, but it's ideally suited for controlling amplifier circuits with high-impedance logic-level inputs, such as MOSFET gate driver chips, and is also good for driving optocouplers and Darlington transistors.
• Digital switching capability. When set to 0% or 100% duty cycle, a port is held continuously at LOW or HIGH level (respectively), with no transient edges at PWM cycle boundaries. In contrast, many of the dedicated PWM chips have unavoidable "blanking" periods between cycles, which prevents them from achieving a true 100% duty cycle. True 0% and 100% duty cycle operation allows ports to be used to control devices that require digital (on/off) switching signals, such as devices with edge-sensitive inputs. Virtual pinball cabinets often have a mix of devices, some needing PWM control and some being simple on/off devices, so the ability to use PWMWorker ports for either type of device improves flexibility. Furthermore, there's no need for any special configuration to designate a port as "digital", since nominal port level settings of 0% and 100% always map to pure 0% and 100% duty cycles on the output pin. A port effectively operates in digital mode whenever the host only assigns it level settings of 0% or 100%.
• Configurable PWM frequency, with a wide range. The host can set the PWM refresh frequency from 8 Hz to 65536 Hz, to optimize for different attached device types. Most of the dedicated chips either have fixed frequencies or have a much more limited range. Adjustability is sometimes useful to mitigate negative interactions between the switching frequency and the physical device, such as mechanical vibration coupling in motors and solenoids, which can cause bothersome audible noise when the PWM frequency is in the range or human hearing.
• High duty-cycle step resolution. PWMWorker automatically chooses the highest available step count based on the frequency setting. The Pico clocks its internal PWM counters at 125 MHz, which means that it can achieve better than 12-bit duty cycle resolution (6250 steps) at 20 kHz. The host interface is limited to 8-bit resolution, following the DOF convention, but the higher internal step resolution is still beneficial when gamma correction is enabled, because it allows for finer gradations of brightness at the low end of the scale, for smoother fades and wider dynamic range.
• Device-side gamma correction. PWMWorker can apply gamma correction on the device side, configurable on a per-port basis. This allows the gamma function to be calculated at higher resolution than the 8-bit space used in the host interface, which provides finer gradations in brightness at the low end of the scale than would be possible if the host applied gamma in its 8-bit space. Gamma correction is beneficial when the output device is an LED or other lighting device, because the gamma function approximates the human eye's logarithmic perception of brightness as a function of power.
• Device-side time limiters. Pinscape's "Flipper Logic" can be configured per port on the PWMWorker side. This feature lets the host set a configurable time limit and power (duty cycle) limit per port, with the device automatically cutting the power on a port to the programmed limit level after the limit has been exceeded continuously for the programmed time limit. This is designed to protect high-power coils from overheating in the event that the host software (either on the PC or on the I/O controller) leaves a port energized at full power for an extended time, such as in the event of a software fault that terminates the host program prematurely while ports are still energized. The Pinscape firmware provides this feature itself, but enforcing it on the PWMWorker side further improves fail-safe reliability by ensuring that the time limit is enforced even if the main Pinscape software crashes, freezes, or otherwise fails. Having the feature on the PWMWorker side also makes it easier for other I/O controllers besides Pinscape to implement Flipper Logic protection, since they need only set the configuration registers appropriately during initial setup, with no further port time monitoring required on the host side.
• Software upgradability. PWMWorker is implemented entirely in software, and the Pico makes it easy for end users to install updates, so the software can be easily upgraded with bug fixes and new features in the future.

Pin Configuration

Detailed pin descriptions

OUT0 through OUT23 are the PWM output ports. These are standard Pico GPIO ports, although note that we use our own labels - these aren't the native GPn lables. Our OUTn port numbering almost matches the Pico's native GPn port numbering, the one exception being GP28, which we label OUT23.

(It seemed more important to number the ports consecutively in the I2C software model than to strictly match the GPn numbering, because (a) this makes the software model more sensible if you approach it strictly at the I2C interface level, and (b) it makes the correspondence between OUTn port numbers and I2C register addresses easy to express arithmetically. Host device driver software would be unnecessarily complicated if it had to work in terms of a discontiguous port numbering scheme. On the other hand, we didn't make the numbering arbitrarily different where it didn't have to be. The only reason that we didn't maintain a perfect correspondence is that the Pico doesn't have an exposed GP23, so there was simply no way to make OUT23 match its GP number no matter which GP we mapped it to.)

The I2C interface allows the host to enable or disable all outputs as a group; at reset, all outputs are disabled, allowing the host to configure outputs before they start driving their connected loads. When outputs are disabled, all of the OUTn pins are configured in INPUT mode, which connects them to GND through a high-value internal resistor in the Pico (about 50K). When ports are enabled, the GPIOs are reconfigured in OUTPUT mode, which makes them push/pull drivers at 3.3V. Each port in OUTPUT mode is capable of sinking or sourcing up to about 10 mA, which makes them suitable for driving small LEDs directly. For larger loads, an amplifier circuit with a logic-level trigger input must be used. The host can configure ports individually to use active high or active low logic, which provides the flexibility to use amplifiers that trigger on either high or low input levels.

GND ports connect to the Pico DC ground, which is also the USB ground (if plugged into USB). These ports should be connected to your carrier board's DC ground.

SDA and SCL are the I2C ports. Connect these to the corresponding ports on your I2C "master" device (typically the main I/O controller in your design, such as a Pinscape Pico). The Pico is a 3.3V device, so the bus must run at 3.3V logic. As always with I2C bus designs, both bus lines must be (separately) pulled up to 3.3V with suitably sized resistors. The exact resistor size required depends upon the overall bus capacitance and the SCL clock speed (400 kHz for this device); on-line calculators are available for figuring the required sizes, but most I2C devices are tolerant enough about timing that you can often get away with choosing something in the 2K to 4K range more or less arbitrarily.

VBUS, VSYS, and 3V3(OUT) are hooks into the Pico's power chain, which is well documented in the Rasbperry Pi Pico Data Sheet; refer to the section titled Powering Pico. The VSYS port can be used to power the Pico as an embedded component, without the need for a USB connection, as long as certain precautions are observed. In particular, the VSYS input must be protected against reverse flow into the power supply when the USB cable is connected. See the Pico data sheet for details. If the Pico is to be plugged into USB at all times, that will supply the Pico with power, so no separate VSYS power input is needed.

3V3_OUT is the output from the Pico's internal 3.3V regulator. This can be used to power other peripherals with 3.3V power. This will typically be left unconnected in a PWMWorker application.

3V3_ENABLE and ADC_VREF should be left unconnected for a PWMWorker application.

USB

No USB connection is required for normal PWMWorker operation. The only time a USB connection is needed is when you're installing or updating the PWMWorker firmware. The Pico communicates with its host I/O controller purely through the I2C bus interface during normal operation, and doesn't use the USB port.

However, there's also no harm in maintaining a continuous USB connection during normal operation. In fact, this is one way that you can provide power to the Pico.

Application Circuit

The diagram below shows a typical application circuit, with the PWMController Pico connected to a host microcontroller. Any type of microcontroller can be used as the host, as long as it's compatible with a 3.3V I2C bus. Microcontrollers with higher or lower logic voltages may also be used, by placing voltage level shifters on the SDA and SCL lines between the Pico and the main bus.

The PWMWorker Pico does not need a USB data connection, since it communicates solely via the I2C bus connection. However, a USB connection can be used as the power source if desired.

• NC = Not Connected. These Pico pins can be left floating.
• Note 1. Output wiring shown for output port #0 only, to simplify the diagram, but in a real application, ports OUT1 through OUT23 would each be wired to an independent output device.

  The output wiring is shown for a simple LED with high-side control, but this can be replaced with any circuit that can be driven by a Pico GPIO output. Pico outputs can drive up to about 10mA at 3.3V directly, and can drive almost any type of load with a suitable amplifier/booster circuit. Several example circuits that can drive higher-current devices are shown in the section below. Each output driver is independent, so you can freely mix and match driver types across the various outputs.

• Note 2. 5VDC power input to the Pico through a Schottky diode, per the Rasbperry Pi Pico Data Sheet (see Powering Pico). This provides power to the Pico without the need for a USB connection, using an external 5VDC power source, such as a PC power supply 5V rail. This can be omitted if the Pico will be always powered through its USB port. The Schottky diode as shown makes it safe to operate the Pico with or without the USB cable connected.
• Note 3. SDA and SCL must be connected to 3.3V through pull-up resistors. The optimal resistor value depends upon the overall capacitance of the I2C bus lines, which is mostly a function of the number and type of devices connected. The I2C specifications provide guidelines, and on-line calculators are available. Values in the 2K to 4K range will work in most designs. Only one set of pull-up resistors is needed for the entire bus; it's not necessary or desirable to fit each device with separate resistors, since multiple resistors on the bus will just combine in parallel.
• Note 4. Optional RUN/RESET line shown, connected to a GPIO port on the host microcontroller. If connected, this allows the host to perform a hard reset on the Pico under software control, by pulling the line LOW. The line must be either driven HIGH or allowed to float during normal operation. The line is pulled to 3.3V through a weak resistor (50K) internal to the Pico, so it can be left unconnected if software reset control isn't required. However, Raspberry Pi recommends connecting the line to a stronger external pull-up (perhaps 10K) anyway, to reduce spurious Pico resets from transient voltages.

Powering the Pico

The Pico can be powered through its USB port, or through the Pico's VSYS power chain input. Various methods for powering the Pico through the VSYS pin are described in the Rasbperry Pi Pico Data Sheet; refer to the section entitled Powering Pico.

If you do choose to power the Pico through VSYS, please pay close attention to the advice in the Pico Data Sheet about protecting against power flowing back into the VSYS supply when USB is also powered. This is most easily accomplished by placing a Shottky diode between the 5V supply and the VSYS input, as shown in the sample application circuit above.

Driving LEDs

Small LEDs can driven directly from the Pico's GPIO ports at up to about 10mA of forward current. GPIO ports in OUTPUT mode act as push/pull drivers at 3.3V, so you can use a Pico port as either a high-side or low-side switch. Since Pico ports will only tolerate 3.3V, they can only directly drive LEDs with forward voltages less than 3.3V. Most red LEDs have forward voltages of 2V or less, but some other colors require 3.4V or higher. LEDs with higher forward voltages will require an amplifier circuit, discussed in the next section.

The Pico's output ports don't provide any current limitation, so you must provide a current-limiting resistor for each LED.

High-side switching: The simplest way to connect an LED is to use the GPIO port as a high-side switch, where the Pico provides the positive supply voltage to the LED's anode, and the LED's cathode is connected to GND.

Low-side switching: The GPIO port can also be used as a pseudo low-side switch, where the Pico provides the ground connection, and the LED's anode is connected to 3.3V power. This configuration is necessary if you're driving a device with multiple channels (e.g., an RGB LED) where the anodes are all wired together, known as the "common-anode" configuration. Since the anodes can't be switched individually, you have to do the switching on the cathode (GND) side.

Low-side switching requires the port to be configured as Active Low using the CONFn port configuration register (see the I2C register list below). In Active Low mode, the port will be driven to 3.3V during the OFF portion of the PWM duty cycle, and 0V during the ON portion. During the OFF portion, then, both ends of the LED are at 3.3V, so there's no voltage potential across the LED, and it turns OFF. During the ON portion of the duty cycle, the port drops to 0V, creating a positive voltage across the LED that allows it to turn ON.

Note that this is only a "pseudo" low-side switch. A true low-side switch would be in high-impedance state during the OFF portion of the duty cycle. In this case, the port is at the 3.3V supply voltage during the OFF portion. When used with a 3.3V device, this acts like a low-side switch, by preventing current from flowing during the OFF phase and allowing it during the ON phase. However, a true low-side switch would be usable with devices with different supply voltages, which this is not; this can only be used with a 3.3V device. Using a device with a supply voltage higher than 3.3V would expose the GPIO port to the higher voltage, which might destroy the Pico, as its ports can only tolerate 3.3V inputs.

Amplifier circuits

An amplifier or "booster" circuit of some kind is required if you wish to use the Pico to drive a load of more than around 10mA or with a supply voltage other than 3.3V.

Since a PWMWorker Pico is physically just an ordinary Pico, any amplifier circuit designed to work with a Pico generically will work. The Pico is a popular device with a great deal of information on it published on the Web, so you should be able to find many examples of circuit designs that will work with it with a little Googling. But to save you some legwork, the sections below provide a few simple but flexible building-block circuits that can be used in many applications.

NPN transistor

The simplest type of booster circuit is an NPN transistor switch. Small-signal transistors like 2N2222 can switch loads up to a few hundred milliamps and 30V to 50V. An NPN works best as a low-side switch, where it connects to the GND end of the load being driven. Note that even though the NPN is acting as a low-side switch, the control input to the switch - which is what the GPIO output port provides - is still Active High: the LED turns ON when the GPIO port output is HIGH. So you'd configure the port in the default Active High mode for this design.

Darlington array

Darlington transistors can control higher currents than small NPN transistors, and there are several chips available that implement multiple channels (typically 8) of Darlington outputs in a single package, such as ULN2803A. ULN2803A is particular convenient for microcontroller applications like this one, because the chip includes internal current-limiting resistors for the input ports, so that the GPIO ports can be directly connected to the Darlington input ports. This reduces the part count, saving money and assembly work.

MOSFET driver

For really high-power devices, like solenoids and motors, you need a MOSFET, specifically a large "power" MOSFET. Many power MOSFETs are available that can switch 10A and up, at 50V or more, which makes the MOSFET the device of choice for controlling anything larger than an LED from a microcontroller. But MOSFETs are somewhat more challenging to control than NPNs and Darlingtons, because most power MOSFETs are all by themselves high-power devices that are above the limits of a Pico GPIO port to control directly. In particular, most power MOSFETs require voltages well above 3.3V for their control input signal, and many also require higher current than a Pico GPIO port can provide, especially when operating at high PWM frequencies. So you need an amplifier to drive your amplifier! There are numerous ways to do this, but the easiest and best is to use one of the many special "gate driver" chips that are purpose-built for this application. One good example is UCC27524P. A circuit based on this chip is shown below. Using a gate driver like this makes the circuit much more forgiving about the MOSFET specs it requires, giving you more flexibility when choosing parts. The circuit here will work with most power MOSFETs, as long as they're safe to use with the 12V gate drive shown (check the V_GS limit in the Absolute Maximum Ratings in the data sheet; most large power MOSFETs have a rating around 20V).

A gate driver chip is particularly beneficial for the Pico because of the high PWM frequencies the Pico is capable of. MOSFETs produce the most heat when they're in their "switching" phase, between fully OFF and fully ON. The time it takes to complete this transition isn't affected by the switching frequency, so when you increase the PWM frequency, you increase the percentage of time the device spends in the heat-producing switching zone, which makes the MOSFET get hotter faster. One way to mitigate this is to reduce the PWM frequency; another is to make the switching time faster. The switching time is a function of the MOSFET's physical properties, and of the gate driver, so one way to make it faster is to make the gate driver faster. That's what gate driver chips like UCC27524P are all about: they're designed specifically to make the MOSFET turn on and off as quickly as possible, by delivering rapid bursts of current at each switching transition. That allows you to operate the MOSFET at higher frequencies with less heating.

Note that this circuit is designed for use with N-channel enhancement-mode MOSFETs only. The other common type, P-channel, is essentially a polarity-reversed version that won't work in this circuit.

Selecting gate resistors R1, R2: 220 Ohms seems to be a good general-purpose choice. The primary purpose of these resistors is to suppress "ringing", which refers to high-frequency current oscillations that occur during the rapid inrush of charge when the MOSFET gate is initially switched on. For that function, you only need a very small resistor, on the order of 10 Ohms. However, the resistors have a second function, which is to protect the UCC27524P chip from excessive current spikes during on/off switching. UCC27524P's entire purpose is to handle high-current spikes, but even so, it has its limits. The chip has to dissipate a certain amount of heat during on/off switching transitions, and since PWM operation is all about rapid on/off switching, high PWM frequencies increase the amount of heat the chip has to dissipate. R1 and R2 limit the current spikes during switching transitions, which in turn reduces the power dissipated by the chip. Higher R1 and R2 values lead to less chip heating, but the trade-off is more MOSFET heating, because they slow down the MOSFET switching time and thus cause more switching power losses. So we have one of those cruel trade-offs: you can either heat up the driver chip, or you can heat up the MOSFET, take your pick. The optimal R1 and R2 values have to balance that tension between faster MOSFET switching (lower R1/R2 values) and safer driver chip operation (higher R1/R2 values). The 220 Ohm recommendation that opened this note was chosen as a one-size-fits-all compromise. It's high enough, experimentally, to protect UCC27524P from damage when using a MOSFET with a high gate charge rating (IRF540N), but it's low enough to handle fast PWM rates (20 kHz) without excessive MOSFET heating due to switching power loss. Note that higher gate charges are more difficult for this circuit to handle, so you'll make it easier on the circuit if you pick a MOSFET with a lower gate charge. (You can find the gate charge listed in the data sheet, usually under the parameter named Q_g.) But MOSFETs with lower gate charge values tend to be more expensive, so the circuit is designed to accommodate a range of devices, to give you some flexibility to be cost-conscious when selecting parts.

See this vpforums thread for some more discussion on the resistor selection: www.vpforums.org/index.php?showtopic=54968&p=543950.

Glitch-free startup

When output ports control mechanical devices, it's desirable to design the output circuits for "glitch-free startup", meaning that the devices are deterministically OFF throughout the initial power-up period. There's necessarily a short time interval between when power is first applied to the device, and when the software has finished initialization and is in control of the output ports. During this time, the software isn't able to control the electronic state of the output ports (since the software isn't fully running yet), so it's up to the hardware design to ensure that devices remain OFF during this time.

The Raspberry Pi Pico has internal circuitry that provides a deterministic electronic state on the ports during the initial power-on reset period. The Pico sets all GPIO ports to INPUT mode at reset; in this state, each GPIO is connected to GND through a high-value (50K ohm) resistor internal to the Pico. Ports remain in this state until the firmware program explicitly reconfigures them.

PWMWorker extends this period of deterministic INPUT port state throughout its own initialization, and through the completion of the host controller's initialization (the host controller is the I2C bus master that's sending commands to the PWMWorker). PWMWorker holds all ports in the initial INPUT state until the host sets the ENABLE OUTPUTS bit (0x01) in Control Register 0 (CTRL0, address 0x18) to '1'. Ports can be configured and set to the desired level while they're still disabled, so the host can ensure that all ports are already in the correct state at the moment they're reconfigured to push-pull (OUTPUT) mode.

The only thing left that you have to worry about in your hardware design is to ensure that the circuit is configured in such a way that the controlled device remains deterministically OFF whenever the GPIO port is in INPUT state. For amplifier circuits that use HIGH level triggers, such as NPN transistors and N-channel MOSFETs, the Pico's internal weak pull-down resistor might be sufficient by itself, but a stronger external pull-down resistor might still be desirable, especially if the trigger circuit has high capacitance (such as a MOSFET gate). For high-level trigger circuits (P-channel MOSFETs, PNP drivers), a pull-up is required. Choose a pull resistor that's strong enough to override the Pico's internal 50K pull-down, but weak enough for the Pico's 10mA GPIO driver; a value in the 4K to 10K range should work.

The UCC27524P-based MOSFET circuit diagrammed above satisfies the pull resistor requirement through a pull-down resistor built into the UCC27524P.

Status LED

PWMWorker uses the Pico's on-board LED (the small green LED adjacent to the USB port) to show the health and status of the device at a glance:

• Initializing: Solid ON. The device is in this state briefly immediately after reset, until the software finishes initializing and is ready to accept I2C commands. This is usually for such a brief time it won't be visible, so if the LED stays solid ON for any length of time, the software has probably crashed or frozen.
• Standby: Short flashes about once every 2 seconds. This is the initial state after reset and initialization. All output ports are disabled (set to GPIO INPUT mode). The device can also be put back in this mode by an I2C command from the host, which the host might wish to do before powering down or going into sleep/standby mode.
• Normal: Steady on/off alternation about every second. Ports are enabled and the device is operating normally, and no I2C activity is currently occurring.
• I2C Activity: Rapid flashing. An I2C send or receive is in progress.

Flipper Logic

PWMWorker implements a simple form of the Pinscape Pico Flipper Logic system. Flipper Logic allows the user to configure each port individually with a power level limit (i.e., a duty cycle threshold) and a time limit. The port is allowed to exceed the power limit, but only for the time specified in the time limit. After the port has been above the level limit for the specified maximum time, PWMWorker automatically reduces the physical output level on the port to the limit level.

This scheme is designed especially for high-power solenoids, although it can be used with any device. It's common in mechanical pinball machines to operate many of the coils at a power level that they can only sustain briefly before overheating. This allows the machine to achieve a brief burst of high mechanical force from the coil, which is the natural mode of operation for many pinball mechanisms, such as pop bumpers and slingshot kickers. These power levels are safe for the coils as long as they're only applied intermittently, but leaving a coil energized at full power for more than a few seconds can overheat and destroy the coil.

The Flipper Logic time-and-power limiter is designed as a fail-safe, to ensure that an output port will never be left energized for longer than the time limit, even if the host never commands the coil to de-energize. A fail-safe like this is useful in practice because the host software on the PC that ultimately sends us commands is often very complex, and as a general rule, the more complex a piece of software is, the less predictable and reliable it tends to be. The PWM Worker firmware is much simpler than typical PC game software, and simpler even than than the Pinscape Pico I/O controller firmware and the firmware on similar devices. This makes the PWM Worker software an excellent place to implement a last line of defense, since the PWM Worker firmware is likely to be the simplest software element in the overall system, and thus the most predictable.

The name Flipper Logic is a reference to the way that flippers work in mechanical pinball machines. It's one thing to over-power pop bumpers and slingshot coils, which fire only transiently in response to contact with the moving ball. It's quite another to do this with flippers, which are under the direct control of the player, who might choose to trap a ball for an indefinite amount of time, holding the flipper coil continuously energized all the while. Mechanical pinball machines have long dealt with this by using a two-phase system for the flipper coil, with a high-power "lift" phase that overpowers the flipper as it flips upward, and a low-power "hold" phase that kicks in after a brief time and then remains in effect as long as the player keeps pressing the button. This allows high mechanical force during the over-powered initial lift phase, without running the risk of burning up the coil if the player decides to have a long conversation with a friend while holding the ball trapped. Flipper Logic uses a similar strategy, using PWM duty cycle to reduce the power to a safe level after a limited time at high power.

I2C Interface

PWMWorker acts as an I2C slave device, compatible with a standard I2C bus protocol at up to 400 kHz.

Slave address

The default I2C slave address is 011 0000, or 0x30. (We use 7-bit address notation, for consistency with the Pico SDK and Pico I2C hardware modules. There's also an 8-bit notation, which some other device data sheets use, and which some microcontrollers use in their SDKs or hardware register interfaces. The difference between 7-bit and 8-bit addressing is purely notational; the bits sent over the wire are the same in either case. To convert from 7-bit to 8-bit addressing, simply multiply by 2, so our 0x30 default address becomes 0x60 when expressed in 8-bit notation.)

The I2C address can be easily reconfigured to any other valid I2C address. Since each device on an I2C bus must have a unique address, you'll have to reconfigure the address for the second PWMWorker and each additional PWMWorker you add to your setup, to make each one unique. You can also change the address of the first PWMWorker, if address 0x30 is taken by some other I2C chip in your setup. Many chips that implement I2C use fixed addresses that can't be changed, or can only use a limited set of pre-chosen addresses, so it will probably be easier to reconfigure PWMWorker to resolve conflicts than to change the other device's address.

To change a PWMWorker's address:

• Connect the Pico to your Windows PC in Boot Loader mode, using the same procedure used to install new firmware (unplug the Pico from all power and USB, plug it back into USB while pressing and holding the BOOTSEL button on top of the Pico)
• Open a Command Prompt (Windows Terminal) and CD to the Pinscape Pico directory
• Run the command SetPWMWorkerAddr 3A, replacing 3A with the hexadecimal address you wish to assign
• If more than one Pico is in Boot Loader mode, you must also specify the drive letter for the Pico you want to program, as in SetPWMWorkerAddr 3B K:
• The address must be between 08 and F7 (this is the valid range defined by the I2C standards)

The new address is stored in the Pico's flash memory, separately from the PWMWorker firmware program. Once programmed, the Pico will retain this address across resets and power cycles, and even across firmware updates. You can change it again at any time using the same procedure.

I2C Protocol

The Pico implements the standard I2C protocol and electronic interface. These are widely documented, so we won't reiterate that material here. Refer to the RP2040 Data Sheet for full details on the Pico's hardware implementation, and refer to any generic I2C documentation for details on the protocol and signal timing.

Auto-increment addressing

PWMWorker always uses auto-increment register addressing. (Some I2C devices do this all the time, some do it conditionally depending on the address or mode settings, and some don't do it at all. PWMWorker is in the "always" camp.) Each time you read or write a register, the device advances its internal register address counter to the next location. This allows the master to read or write any number of consecutively numbered registers in a single transaction. There are 256 register addresses, numbered 0x00 to 0xFF. The internal address counter automatically wraps back to 0x00 after reading or writing the last register at 0xFF.

Register Set

As with most I2C devices, the I2C interface works in terms of "registers", which are notional memory locations in the device that control how it operates. Reading a register retrieves information on the current device's state; writing a register generally commands the device to do something, or updates the device's configuration settings.

Each register on this device is an 8-bit byte with a unique register address from 0x00 to 0xFF. Not all locations are assigned; unassigned registers are reserved for future use and should not be written to. Some registers are defined as bit maps, where each bit has a defined function; any bits in these registers that aren't assigned specific meanings should be considered reserved, and should be set to '0' when writing and ignored when reading.

A few registers are defined as paired to form a 16-bit value, with a low byte and a high byte. The two registers in these pairs are always at consecutive address, with the low-order (less significant) byte first, which is known as little-endian byte order. When accessing these registers, you should always read or write both bytes of the register together as a pair, in the same I2C transaction, to ensure that the two halves of the 16-bit value are coherent.

Notes on register addressing

The LEVELn ports are all arranged in single contiguous block, from address 0x00 to 0x17. This is intended to allow the host to minimize I2C traffic by consolidating a level update affecting several output ports into a single I2C transaction. The typical usage pattern during normal operation is that the PC host will send the I/O controller updates via USB every few milliseconds, and the I/O controller will put these into physical effect on the PWM devices by sending I2C commands updating the device-side levels. These level updates are typically the only traffic during normal operation, so arranging the level registers in a single block helps minimize I2C traffic by allowing any contiguous block of levels to be updated in a single I2C write transaction, without the need to touch any registers other than the level registers.

The other per-port registers - CONFn, LIMITn, TIMELIMITnL, TIMELIMTnH - are arranged in groups by port. To calculate the address of the register group for OUTn, use 0x20 + 4*n. Then add 0 to get CONFn, 1 to get LIMITn, and 2 to get TIMELIMITnL. The rationale for grouping these registers by port is that all of these registers are for configuring the port rather than setting its output level. The host will often want to update all of the configuration registers for a given port together, so this grouping allows a single port's configuration registers to be updated in a single non-stop I2C write. The grouping makes it equally possible to update all of the configuration registers for all ports, or all of the registers for a contiguous block of ports, in a single write.

Footnotes

• Definition of PWM. PWM, for Pulse-Width Modulation, is a method for controlling the power level delivered through an electronically switched output port, by rapidly switching the port on and off. The port is switched on and off at a fixed rate, called the PWM frequency, and the power is controlled by adjusting the portion of this fixed cycle time that the port is switched ON. The "pulse" of the name refers to the ON portion of the cycle, and the "width" refers to the time duration of the pulse, which is represented as a horizontal width when you plot voltage against time on a graph. (Engineers are so in the habit of visualizing time geometrically as the X axis that they take it for granted that you can talk about a time duration as a "width".) By making the switching frequency too fast for the eye to see, PWM can be used to simulate an analog "dimmer switch" using a purely digital on/off port, to control things like LED brightness, motor speed, and solenoid force.

Copyright and license

PWMWorker software for Raspberry Pi Pico, and accompanying documentation
Copyright 2024 Michael J Roberts
Released under a BSD 3-clause license