# pwm_ccp1

hardware PWM control, dedicated to module PWM1

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

Description

    Performs PWM operations on the PWM1 module (of enhanced midrange)
    This file is automatically included by pwm_hardware.jal
    when the target PIC has a PWM1 module.

Notes

    1. This is a heavy refactoring of the original pwm_hardware.jal
              (Stef's lib)
           2. Partly rewritten for JalV2 version 2.4l and Jallib revision 1171.
              Reduced memory occupation. Added procedure for lowres PWM.
           3. Changes dd October 2012 by Rob Hamerling
              - added public procedure to set dutycycle with highest resolution (1023 steps).
              - Make the pwm_set_dutycycle (highres, lowres and unqualified) private
                (preceeded with an underscore). These procedures will be kept. but
                with a 'deprecated' warning recommending to use the procedures for
                relative settings.

Dependencies

No dependency found

## Summary

### Global variables/contants

- `var bit*4 _ccp1con_shadow_ccp1m at _ccp1con_shadow : 0`
- `var byte _ccp1con_shadow = 0b0000_0000`
- `var byte _ccpr1l_shadow = 0`
- `var bit*2 _ccp1con_shadow_dc1b at _ccp1con_shadow : 4`

### Procedures

- `pwm1_set_percent_dutycycle(byte in percent)`
- `pwm1_set_dutycycle_percent(byte in percent)`
- `pwm1_on()`
- `pwm1_off()`
- `pwm1_set_dutycycle(byte in steps)`
- `pwm1_set_dutycycle_highres(word in steps)`
- `pwm1_set_dutycycle_ratio(word in ratio)`
- `pwm1_set_dutycycle_lowres(byte in steps)`

Private

- `_pwm1_set_dutycycle_highres(word in steps)`

### Functions

## API details

### Global variables/contants

- `var bit*4 _ccp1con_shadow_ccp1m at _ccp1con_shadow : 0`

      2 LSbits of duty cycle

- `var byte _ccp1con_shadow = 0b0000_0000`

      shadow

- `var byte _ccpr1l_shadow = 0`

      8 MSbits of duty cycle

- `var bit*2 _ccp1con_shadow_dc1b at _ccp1con_shadow : 4`

      2 LSbits of duty cycle

### Procedures

- `pwm1_set_percent_dutycycle(byte in percent)`

      deprecated procedure

- `pwm1_set_dutycycle_percent(byte in percent)`

      Purpose:   Set duty cycle as a percentage, allowing max 100 PWM steps.
      The duty cycle will be set to the specified percentage of the maximum
      for the current PWM frequency and Fosc.
      Arguments: byte - dutycycle as a percentage (allowed range: 0..100)
      Notes:     - The number of available PWM steps can be lower than 100 with
      (very) high PWM frequencies and low Fosc.
       The steps may not all be equal. The lower the actual resolution
      the bigger the differences between steps may be.
       pin_CCP1_direction should be set to output!

- `pwm1_on()`

      Purpose:   Set PWM on
      Arguments: none
      Notes:     - duty cycle is restored from shadow registers
       pin_PWM1_direction should be set to output

- `pwm1_off()`

      Purpose:   PWM mode off
      Arguments: none

- `pwm1_set_dutycycle(byte in steps)`

      Set dutycycle for 10-bits resolution but allowing only 255 PWM steps.
      This procedure is equivalent to pwm1_set_dutycycle_highres(), but
      the low order 2 bits of the 10-bits duty cycle are set to 0.
      This means that only every 4th of the available 1023 steps can be selected
      and consequently max 255 PWM steps are available.
      This procedure is for user convenience, allowing to specify an 8 bits
      value for the duty cycle is for many applications satisfactory.
      Calling this procedure will also activate PWM.
      Note: pin_CCP1_direction should be set to output!

- `pwm1_set_dutycycle_highres(word in steps)`

      deprecated procedure

- `pwm1_set_dutycycle_ratio(word in ratio)`

      Purpose:   Set duty cycle in the range 0..1023 PWM steps.
      Arguments: word - dutycycle ratio in range 0..1023
      Notes:     - The duty cycle will be set to the specified ratio of the maximum
      value for the current PWM frequency and Fosc.
      Notes:     - The resolution is about 1 pro mille
       The number of available PWM steps can be lower than 1023 with
      high PWM frequencies or low Fosc values.
       pin_CCP1_direction should be set to output!

- `pwm1_set_dutycycle_lowres(byte in steps)`

      Purpose: Set dutycycle with 8-bits resolution allowing 255 PWM steps.
      The 'steps' argument is the 8-bits absolute value for the duty cycle:
      * duty<1:0> are the 2 LSbits
      * duty<7:2> are the 6 MSbits
      Arguments: byte - duty cycle (allowed range 0..255)
      Notes:     This procedure is particularly suitable with higher frequencies
      whereby the PWM resolution is limited to 256 steps or less!

Private

- `_pwm1_set_dutycycle_highres(word in steps)`

      Purpose:   Specify the duty cycle by number of PWM steps.
      The duty cycle is setting is determined by a 10-bits parameter,
      allowing a resolution of 1023 steps.
      The 'steps' argument is a (max) 10-bits absolute value for the duty cycle:
      * steps<1:0> are the 2 LSbits
      * steps<9:2> are the 8 MSbits
      Arguments: word - steps cycle (allowed range 0..1023)
      Notes:     - This is a private procedure, not intended for general use.
      The caller is responsible to specify an acceptable value
      w.r.t. to the chosen PWM frequency.

### Functions

## Related samples

No sample found