PWM

Syntax: PWM Pin, Duty, Duration

Function

Convert a digital value to analog output via pulse-width modulation.

• Pin is a variable/constant/expression* (0 - 15) that specifies the I/O pin to use. This pin will be set to output mode initially then set to input mode when the command finishes.
• Duty is a variable/constant/expression* (0 - 255) that specifies the analog output level as a number of 256^ths of 5 V (0 to 4.98 V).
• Duration is a variable/constant/expression* (0 - 255) that specifies the duration of the PWM output.

* Note: expressions are not allowed as arguments on the BS1. The range of the Pin argument on the BS1 is 0–7.

Quick Facts

Explanation

Pulse-width modulation (PWM) allows the BASIC Stamp (a purely digital device) to generate an analog voltage. The basic idea is this: If you make a pin output high, the voltage at that pin will be close to 5 V. Output low is close to 0 V. What if you switched the pin rapidly between high and low so that it was high half the time and low half the time? The average voltage over time would be halfway between 0 and 5 V (2.5 V). PWM emits a burst of 1s and 0s whose ratio is proportional to the duty value you specify.

The proportion of 1s to 0s in PWM is called the duty cycle. The duty cycle controls the analog voltage in a very direct way; the higher the duty cycle the higher the voltage. In the case of the BASIC Stamp, the duty cycle can range from 0 to 255. Duty is literally the proportion of 1s to 0s output by the PWM command. To determine the proportional PWM output voltage, use this formula: (Duty ÷ 256) x 5 V. For example, if Duty is 100, (100 ÷ 256) x 5 V = 1.953 V; PWM outputs a train of pulses whose average voltage is 1.953 V.

In order to convert PWM into an analog voltage we have to filter out the pulses and store the average voltage. The resistor/capacitor combination shown below will do the job. The capacitor will hold the voltage set by PWM even after the instruction has finished. How long it will hold the voltage depends on how much current is drawn from it by external circuitry, and the internal leakage of the capacitor. In order to hold the voltage relatively steady, a program must periodically repeat the PWM instruction to give the capacitor a fresh charge.

Just as it takes time to discharge a capacitor, it also takes time to charge it in the first place. The PWM command lets you specify the charging time in terms of PWM duration. The timing for the units in Duration is shown in in the table above. So, on the BS2, to charge a capacitor for five milliseconds, you would specify five units in Duration.

How do you determine how long to charge a capacitor? Use this rule-of-thumb formula: Charge time = 5 x R x C. For instance, the circuit below uses a 10 kΩ (10 x 10³ ohm) resistor and a 1 µF (1 x 10^-6 F) capacitor:

Charge time = 5 x 10 x 10³ x 1 x 10^-6 = 50 x 10^-3 seconds, or 50 milliseconds.

Since, on the BS2, each unit in Duration is approximately a millisecond, it would take at least 50 units to charge the capacitor. Assuming the circuit is connected to P0, here's the complete PWM instruction:

  PWM 0, 100, 50                        ' Put a 1.96V charge on cap (BS2, BS2e)

To charge the same circuit to the same level using a BS2sx, the Durationwould require adjustment as follows:

  PWM 0, 100, 125                       ' Put a 1.96V charge on cap (BS2sx) 

After outputting the PWM pulses, the BASIC Stamp leaves the pin in input mode (0 in the corresponding bit of DIRS). In input mode, the pin's output driver is effectively disconnected. If it were not, the steady output state of the pin would change the voltage on the capacitor and undo the voltage setting established by PWM. Keep in mind that leakage currents of up to 1 µA can flow into or out of this "disconnected" pin. Over time, these small currents will cause the voltage on the capacitor to drift. The same applies for leakage current from an op-amp's input, as well as the capacitor's own internal leakage. Executing PWM occasionally will reset the capacitor voltage to the intended value.

PWM charges the capacitor; the load presented by your circuit discharges it. How long the charge lasts (and therefore how often your program should repeat the PWM command to refresh the charge) depends on how much current the circuit draws, and how stable the voltage must be. You may need to buffer PWMoutput with a simple op-amp follower if your load or stability requirements are more than the passive circuit can handle.

The term "PWM" applies only loosely to the action of the BASIC Stamp's PWM command. Most systems that output PWM do so by splitting a fixed period of time into an on time (1) and an off time (0). Suppose the interval is 1 ms and the duty cycle is 100 ÷ 256. Conventional PWM would turn the output on for 0.39 ms and off for 0.61 ms, repeating this process each millisecond. The main advantage of this kind of PWM is its predictability; you know the exact frequency of the pulses (in this case, 1 kHz), and their widths are controlled by the duty cycle.

BASIC Stamp's PWM does not work this way. It outputs a rapid sequence of on/off pulses, as short as 1.6 µs in duration, whose overall proportion over the course of a full PWM cycle of approximately a millisecond is equal to the duty cycle. This has the advantage of very quickly zeroing in on the desired output voltage, but it does not produce the neat, orderly pulses that you might expect. All BS2 modules also uses this high-speed PWMtechnique to generate pseudo-sine wave tones with the DTMFOUT and FREQOUT instructions.