# pwm_common

Hardware PWM control, common procedures

Author | Stef Mientki, Copyright © 2002..2024, all rights reserved.
Adapted-by | Sebastien Lelong, Rob Hamerling, Rob Jansen
Compiler | 2.5r8

Description

    This lib handles common operations on PWM, regardless the channel number.
    It is used in combination with one or more pwm_ccp libraries
    (eg. pwm_ccp1.jal, pwm_ccp2.jal, etc.). These libraries are included
    automatically dependent of the configuration of the target PIC.

Notes

    This is a heavy refactoring of the original pwm_hardware.jal (Stef's lib).
    For 10-bit PWM Timer2 is always used, also when different timers can be assigned.

Dependencies

No dependency found

## Summary

### Global variables/contants

### Procedures

- `pwm_max_resolution(byte in prescaler)`
- `pwm_set_frequency(dword in freq)`

### Functions

- `pwm_get_resolution() return word`

## API details

### Global variables/contants

### Procedures

- `pwm_max_resolution(byte in prescaler)`

      Purpose:   Set all(!) CCP modules for max (10-bits) PWM resolution.
      Arguments: byte - prescaler value for Timer2
      Notes:     - Allowed values of input parameter:
      For PICs with 2 prescaler bits: 1, 4, 16 or 64
      For PICs with 3 prescaler bits: 1, 2, 4, 8, 16, 32, 64 or 128
      In case of an incorrect argument the highest prescaler value
      will be used. Timer 2 will be running.
      .
      While setting maximum resolution, the Timer2 prescaler can be used to adjust
      frequency to some extent with the Timer2 parameter.
      Below a table showing the PWM frequencies for common clock speeds and different
      Timer2 prescaler values for PIC with 2 prescaler bits (1..64) using Fosc/4.
      Note that 10-bit PWM use Fosc/4 and 16-bit PWM use Fosc. Some 10-bit PWM and all
      16-bit PWM have 3 prescaler bits (1..128), see the datasheet of your PIC.

      ||*Prescale*||  *4MHz*  ||  *8MHz*  || *10MHz*  ||  *20MHz*  ||  *32MHz*  ||  *48MHz*  ||
      ||     1    || 3.90 kHz || 7.81 kHz || 9.77 kHz || 19.53 kHz || 31.25 kHz || 46.88 kHz ||
      ||     4    ||  976  Hz || 1.95 kHz || 2.44 kHz ||  4.88 kHz ||  7.81 kHz || 11.72 kHz ||
      ||    16    ||  244  Hz ||  488  Hz ||  610 Hz  ||  1.22 kHz ||  1.95 kHz ||  2.93 kHz ||
      ||    64    ||   61  Hz ||  122  Hz ||  152 Hz  ||   305 Hz  ||   488 Hz  ||   732 Hz  ||

      For 10-bit PWM PICs with more than one CCP module you should realize that all CCP
      modules use Timer2 and PR2 for PWM operations. This means that the PWM
      period (frequency) of all PWM output pins is the same.
      Only the duty cycle can vary between one and another PWM pin.
      PICs with 16-bits PWM have indepent PWM timers so the PWM frequency can be set
      differently for each individual PWM channel.

- `pwm_set_frequency(dword in freq)`

      Purpose:   Set all(!) CCP 10-bit modules for a specific PWM frequency.
      Arguments: Input:  dword - PWM frequency
      Output: none
      Notes:     - User may check bit TIMER2_TMR2ON to see if call successful
      TRUE:  Timer2 ON, PWM frequency set
      FALSE: Timer2 OFF, no PWM signal (frequency too high or too low
      with current Fosc)
      The minimum and maximum allowed PWM frequencies depend on the clock speed.
      When specifying a value beyond the limits PWM will not be enabled.
      .
      The chosen frequency may enforce a limit on the PWM resolution (number of steps).
      The application program should not specify a higher value for the duty cycle
      than this limit. When exceeding this limit the dutycycle will probably result
      in a 'weird' value.
      Use the procedures pwm?_set_dutycycle_percent() and pwm?_set_dutycycle_ratio()
      to set the desired duty cycle.

### Functions

- `pwm_get_resolution() return word`

      Purpose:   Obtain actual number of 10-bit PWM steps
      Arguments: (none)
      Returns:   word = actual number of 10-bit PWM steps

## Related samples

No sample found