====== Advanced mode of digital outputs: PWM ======
The PWM stands for Pulse-Width Modulation. It is for generating a square signal of given frequency and certain duty cycle on a digital output. Typically, it is used for regulating a DC powered component in a way the analog regulation cannot achieve.
;;#
Patron \\
Neuron \\
Axon
;;#
Let's take a 24 V⎓ motor for example. To achieve 100 % RPMs, you have to supply it with 24 V⎓. Logically, to achieve 10 % RPMs, you have to supply it 24/10 = 2.4 V⎓. But if you apply this voltage, the motor will not even start, because of the friction and its load. And if it starts, its torque will be very low. This is one of the downsides of analogue regulation.
The PWM works **only on digital outputs**, that means it can only output 0 V⎓ or 24 V⎓. To achieve the regulation, the PWM generates a square signal of given frequency. That means it will periodically set the output ''ON'' and ''OFF''. The parameter of the regulation is the **duty cycle** - a proportion of the ''ON'' time and ''OFF'' time within one period. When the duty cycle is represented in percents and the value is 50 %, the output signal will be 50 % of the period ''ON'' and the rest will be ''OFF''. If the duty cycle is 66 %, it will be 66 % of the cycle ''ON'' and 34 % ''OFF''.
===== Selecting a frequency =====
One of the parameters you need to set is the frequency of the PWM. You have to set this value according to your regulated system. The rule of thumb is - the slower the system you regulate is, the lower the frequency can be and vice versa. Take for example a large water heater. It can take up to several hours to heat a large tank of water to desired temperature, therefor we don't need high frequency regulation. Even tenths or hundredths of Hz will be sufficient. For regulating a LED light, we need to set the frequency to at least 100 Hz, because lower frequencies would be visible by naked eye.
Another thing considering the frequency is the switching element you are turning ''ON'' and ''OFF''. If it is a mechanical relay, you have to use very low frequency or you could destroy it. If it is SSR relay, MOSFET or IGBT transistor, you can set couple of kHz or even MHz (always referr to the datasheet of the component).
The frequency of the PWM in Unipi depends on the used resolution. See below.
===== Resolution of the PWM =====
Second parameter of the PWM is the **resolution**. This value indicates in **how many steps** we want to divide the regulation. If the resolution is 3, we can set the duty cycle to 3 values: 0 %, 50 % and 100 %. If the resolution is 11, we can set it from 0 % to 100 % in the steps of 10 %.
In Unipi controllers, you can set the resolution up to 65536 steps.
===== The duty cycle =====
The duty cycle, as mentioned above, is the actual value of the regulation. Typically, you will encounter PWM duty cycle represented as a percentage of the ''ON'' time in regard of the period. In the Mervis however, **the duty cycle is represented by the number of resolution steps**. Let's see how to calculate this value.
resolution - 1
duty_cycle [mervis] = ------------------- * duty_cycle [%]
100
The only correct values of duty_cycle [mervis] are between 0 and resolution - 1. These values you will set from the program.
=== 1. example ===
resolution = 101 steps (0-100 % in the step of 1 %)
duty_cycle [%] = 34
resolution - 1 101 - 1
duty_cycle [mervis] = ------------------- * duty_cycle [%] = ------------------- * 34 = 34
100 100
For resolution of 101 steps and desired duty_cycle of 34 % we need to set the duty cycle in Mervis to **34**. That was easy, let's try something more complicated.
=== 2. example ===
resolution = 6 steps (0-100 % in the step of 20 %)
duty_cycle [%] = 40
resolution - 1 6 - 1
duty_cycle [mervis] = ------------------- * duty_cycle [%] = -------------- * 40 = 2
100 100
For resolution of 6 steps and desired duty_cycle of 40 % we need to set the duty cycle in Mervis to **2**.
===== Calculations of Mervis configuration parameters =====
Unfortunatelly, you cannot set the **frequency** and the **resolution** values in the Mervis directly. The variables for configuring PWM in Mervis are called **PWM_Cycle** and **PWM_Prescale** and you need to calculate their values according to desired **resolution** and **frequency**:
PWM_Cycle = resolution - 2
4.8 * 10^7
PWM_Prescale = ------------------------------- - 1
frequency * ( resolution - 1)
The **PWM_Cycle** and **PWM_Prescale** variables are 16 bit words, therefor you can set only integer values 0 - 65535. If the result of your calculations is real number, you need to either round it, or change the parameters **frequency** or **resolution**.
Alternatively, to get the **resolution** and **frequency** from **PWM_Cycle** and **PWM_Prescale** values, use these equations:
resolution = PWM_Cycle + 2
4.8 * 10^7
frequency = ----------------------------------------
( PWM_Cycle + 1) * (PWM_Prescale + 1)
=== 1. example ===
Resolution = 11 (duty cycle 0-100 % with 10 % steps)
Frequency = 4 kHz
PWM_Cycle = resolution - 2 = 11 - 2 = 9
4.8 * 10^7 4.8 * 10^7
PWM_Prescale = ------------------------------- - 1 = --------------------- - 1 = 1199
frequency * ( resolution - 1) 4000 * ( 11 - 1 )
=== 2. example ===
Resolution = 41 (step 2.5 %)
Frequency = 0.1 Hz
PWM_Cycle = resolution - 2 = 41 - 2 = 39
4.8 * 10^7 4.8 * 10^7
PWM_Prescale = ------------------------------- - 1 = ------------------- - 1 = 119999999
frequency * ( resolution - 1) 0.1 * (41 - 1 )
As you can see, with given **resolution** and **frequency**, the **PWM_Prescale** is larger than its maximum value 65535. We either have to increase the **frequency**, **resolution** or **both**.
=== 3. example ===
Resolution = 10001 (step 0.01 %)
Frequency = 0.1 Hz
PWM_Cycle = resolution - 2 = 10001 - 2 = 9999
4.8 * 10^7 4.8 * 10^7
PWM_Prescale = ------------------------------- - 1 = ------------------------- - 1 = 47999
frequency * ( resolution - 1) 0.1 * (10001 - 1 )
With increased resolution, we are able to achieve lower frequencies and vice versa. For high frequency PWM, we need to sacrifice the resolution.
===== Setting the PWM in Mervis =====
The **PWM_Cycle** and **PWM_Prescale** are configuration variables of the Unipi module and cannot be changed from the program. Select the Unipi module in the **Left panel**. In the **Properties panel**, you can find the **PWM_Cycle** and **PWM_Prescale** variables. Set those according to your calculations. We will set it to **PWM_Cycle** = 99 and **PWM_Prescale** = 119. This will set the frequency to 4 kHz with resolution of 101.
{{ :en:sw:01-mervis:pwm-01-selecting-module.png?direct |}}
The change has been done on the prototype of the device, which means it is a change in the PLC module's configuration. To upload the configuration, check the [[en:sw:01-mervis:unipi-configure-module-hidden|Configuration of the Unipi module]] tutorial.
Now let's check which variables we have available for working with PWM. Select the **Variable browser** tab on the **Main window**. Under the **Name** column, enter the **PWM** into the search box. You should see similar list.
{{ :en:sw:01-mervis:pwm-06-searching-for-ports.png?direct |}}
Turn on the **Debugging** and in the column **PLC Value**, you will see the current PWM value of DO ports 1.01-1.04. If you didn't change it previously, you should see zeros. Change the value of **PWM_1.01** to 50 and confirm by clicking on {{:files:dialog-confirm_button_2.png?nolink|}} or submiting with **ENTER**.
We can hook up the oscilloscope to the Unipi's DO 1.01 and check the waveform.
{{ :en:sw:01-mervis:pic_425_2.gif?direct |}}
And we can see the frequency of the wave is 4 kHz with 50 % duty cycle.
===== What is the magical 4.8 * 10^7 constant? =====
In calculations of the **PWM_Prescale**, we use constant 4.8 * 10^7. The constant represents 48MHz clock source for the internal timers/counters which together with PWM_Prescale and PWM_Count set the desired frequency