WebbotLib AVR library
WebbotLib It just does it
  C++ documentation  C documentation

pwm.h

Provides a generic way of generating a hardware PWM signal.
This can generate a hardware PWM signal on a timer output pin - check the sys/*.h file for your board to see which pins are available. Hardware PWM is useful as it can be used either as a fall back if your specific motor driver is not currently supported or for miscellaneous tasks such as dimming LEDs.
PWM has two main requirements:
1. The frequency: ie the 'off time' + the 'on time'
2. The duty cycle: the percentage of time that that the signal is 'on'
Once the 'frequency' has been set it cannot be changed - whereas the duty cycle will dictate the percentage of the time is spent 'on'. A duty cycle of 0 means that the output is always 'off', 100 means it always 'on' and there is a linear distribution in between these two values. ie a duty cycle of 50% means that it will spend half of its time 'on' and the other half 'off'.
Note that the overall frequency can only be set once per timer - whereas the duty cycle can be varied from 0% to 100% on each pin that is connected to the timer. So if you want multiple PWM outputs using the functions in this section then try to put all of the entries that require the same frequency on pins from the same timer.
For example: if you attempt to set up two pins with one pin requiring a frequency of 1 hertz and the second requiring 1000 hertz then you can run into problems if you use two pins from the same timer. Assuming that you set up the first pin then the timer is set to use 1 hertz and so the request for the second pin to use 1000 hertz cannot be honoured (as it would mess up the first pin).
Also note that the slowest frequency you can set will depend upon the clock speed and whether you are using an 8 bit or 16 bit timer.
For example: if you are using an 8 bit timer (maximum value of TOP = 255) on a 16 MHz board then the slowest frequency the library can create is by using a prescaler of 1024. This gives a frequency of about (16MHz / 1024)/256 = 61Hz. So if you want really low frequencies then you would be better choosing a 16 bit timer instead.
Because these calculations are quite complex then you may want to make the initialisation routines return the 'actual' value into a variable (by using the last parameter). You can then decide if the actual value is close enough to the value you wanted or not.
When using the 'init' functions there are two 'short cuts' that can be used for the required frequency:-
PWM_SLOWEST - Will set up the slowest possible PWM cycle time. Useful for things like blinking LEDs.
PWM_FASTEST - Use the fastest possible PWM cycle time. Useful for dimming LEDs, speech, digital-to-analogue conversion etc.

 

Function

 


boolean pwmInitHertz(const IOPin* pin, uint32_t hertz, DUTY_CYCLE duty, uint32_t* actualHertz)

Initialise PWM using the given frequency in Hertz.
The function will return FALSE if there is a problem - for example if your are trying to use a non-PWM pin or it will return TRUE if everything is ok.
Parameters:
pin - The IOPin to use. Check the sys/*.h file to see what PWM timer output pins are available
hertz - The frequency
duty - The initial setting for the duty cycle (a value between 0 and 100).
actualHertz - The address of an uint32_t variable in your calling code. This variable will be filled in, on return, with the actual frequency that will be used. If you are not interested in this value then you can use null for this parameter.

boolean pwmInitDeciHertz(const IOPin* pin, uint32_t deciHertz, DUTY_CYCLE duty, uint32_t* actualDeciHertz)

Initialise PWM using the given frequency in DeciHertz - tenths of a Hertz - ie 1 = 0.1Hz, 10=1Hz etc.
This function is similar to the other 'init' function but is mainly used to set a frequency of less than 1 Hertz.
The function will return FALSE if there is a problem - for example if your are trying to use a non-PWM pin or it will return TRUE if everything is ok.
Parameters:
pin - The IOPin to use. Check the sys/*.h file to see what PWM timer output pins are available
deciHertz - The frequency in tenths of a Hertz
duty - The initial setting for the duty cycle (a value between 0 and 100).
actualDeciHertz - The address of an uint32_t variable in your calling code. This variable will be filled in, on return, with the actual frequency, in DeciHertz, that will be used. If you are not interested in this value then you can use null for this parameter.

pwmSetDutyCycle(const IOPin* pin, DUTY_CYCLE duty)

Sets the PWM duty cycle on a pin that has already been initialised successfully.
The duty cycle is a percentage, 0 to 100.

DUTY_CYCLE pwmGetDutyCycle(const IOPin* pin)

Returns the current duty cycle for an IO pin that has already been set up for PWM.

pwmOff(const IOPin* pin)

Stop sending the PWM output to a given pin.

Valid XHTML 1.0 Transitional