Class Pwm
Provides methods for software and hardware based PWM services for the GPIO pins. All User GPIO pins support PWM.
Inherited Members
Namespace: Unosquare.PiGpio.NativeMethods
Syntax
public static class PwmMethods
GpioGetPwmDutyCycle(UserGpio)
Gets the PWM duty cycle.
Declaration
public static int GpioGetPwmDutyCycle(UserGpio userGpio)Parameters
| Type | Name | Description |
|---|---|---|
| UserGpio | userGpio | The user gpio. |
Returns
| Type | Description |
|---|---|
| Int32 | The PWM duty cycle. |
GpioGetPwmFrequency(UserGpio)
For normal PWM the frequency will be that defined for the GPIO by GpioSetPwmFrequency(UserGpio, UInt32).
If a hardware clock is active on the GPIO the reported frequency will be that set by GpioHardwareClock(SystemGpio, UInt32).
If hardware PWM is active on the GPIO the reported frequency will be that set by GpioHardwarePwm(SystemGpio, UInt32, UInt32).
Declaration
public static int GpioGetPwmFrequency(UserGpio userGpio)Parameters
| Type | Name | Description |
|---|---|---|
| UserGpio | userGpio | 0-31. |
Returns
| Type | Description |
|---|---|
| Int32 | Returns the frequency (in hertz) used for the GPIO if OK, otherwise PI_BAD_USER_GPIO. |
Examples
f = gpioGetPWMfrequency(23); // Get frequency used for GPIO23.GpioGetPwmRange(UserGpio)
If a hardware clock or hardware PWM is active on the GPIO the reported range will be 1000000 (1M).
Declaration
public static int GpioGetPwmRange(UserGpio userGpio)Parameters
| Type | Name | Description |
|---|---|---|
| UserGpio | userGpio | 0-31. |
Returns
| Type | Description |
|---|---|
| Int32 | Returns the dutycycle range used for the GPIO if OK, otherwise PI_BAD_USER_GPIO. |
Examples
r = gpioGetPWMrange(23);GpioGetPwmRealRange(UserGpio)
If a hardware clock is active on the GPIO the reported real range will be 1000000 (1M).
If hardware PWM is active on the GPIO the reported real range will be approximately 250M divided by the set PWM frequency.
Declaration
public static int GpioGetPwmRealRange(UserGpio userGpio)Parameters
| Type | Name | Description |
|---|---|---|
| UserGpio | userGpio | 0-31. |
Returns
| Type | Description |
|---|---|
| Int32 | Returns the real range used for the GPIO if OK, otherwise PI_BAD_USER_GPIO. |
Examples
rr = gpioGetPWMrealRange(17);GpioGetServoPulseWidth(UserGpio)
Returns 0 (off), 500 (most anti-clockwise) to 2500 (most clockwise).
Declaration
public static int GpioGetServoPulseWidth(UserGpio userGpio)Parameters
| Type | Name | Description |
|---|---|---|
| UserGpio | userGpio | The user gpio. |
Returns
| Type | Description |
|---|---|
| Int32 | The Servo pulse width. |
GpioHardwareClock(SystemGpio, UInt32)
Starts a hardware clock on a GPIO at the specified frequency. Frequencies above 30MHz are unlikely to work.
The same clock is available on multiple GPIO. The latest frequency setting will be used by all GPIO which share a clock.
The GPIO must be one of the following.
Access to clock 1 is protected by a password as its use will likely crash the Pi. The password is given by or'ing 0x5A000000 with the GPIO number.
Declaration
public static ResultCode GpioHardwareClock(SystemGpio gpio, uint clockFrequency)Parameters
| Type | Name | Description |
|---|---|---|
| SystemGpio | gpio | see description. |
| UInt32 | clockFrequency | 0 (off) or 4689-250000000 (250M). |
Returns
| Type | Description |
|---|---|
| ResultCode | Returns 0 if OK, otherwise PI_BAD_GPIO, PI_NOT_HCLK_GPIO, PI_BAD_HCLK_FREQ,or PI_BAD_HCLK_PASS. |
Remarks
4 clock 0 All models 5 clock 1 All models but A and B (reserved for system use) 6 clock 2 All models but A and B 20 clock 0 All models but A and B 21 clock 1 All models but A and Rev.2 B (reserved for system use)
32 clock 0 Compute module only 34 clock 0 Compute module only 42 clock 1 Compute module only (reserved for system use) 43 clock 2 Compute module only 44 clock 1 Compute module only (reserved for system use).
GpioHardwarePwm(SystemGpio, UInt32, UInt32)
Starts hardware PWM on a GPIO at the specified frequency and dutycycle. Frequencies above 30MHz are unlikely to work.
NOTE: Any waveform started by GpioWaveTxSend(UInt32, WaveMode), or GpioWaveChain(Byte[], UInt32) will be cancelled.
This function is only valid if the pigpio main clock is PCM. The main clock defaults to PCM but may be overridden by a call to GpioCfgClock(UInt32, CpuPeripheral).
The same PWM channel is available on multiple GPIO. The latest frequency and dutycycle setting will be used by all GPIO which share a PWM channel.
The GPIO must be one of the following.
The actual number of steps beween off and fully on is the integral part of 250 million divided by PWMfreq.
The actual frequency set is 250 million / steps.
There will only be a million steps for a PWMfreq of 250. Lower frequencies will have more steps and higher frequencies will have fewer steps. PWMduty is automatically scaled to take this into account.
Declaration
public static ResultCode GpioHardwarePwm(SystemGpio gpio, uint pwmFrequency, uint pwmDytuCycle)Parameters
| Type | Name | Description |
|---|---|---|
| SystemGpio | gpio | see description. |
| UInt32 | pwmFrequency | 0 (off) or 1-125000000 (125M). |
| UInt32 | pwmDytuCycle | 0 (off) to 1000000 (1M)(fully on). |
Returns
| Type | Description |
|---|---|
| ResultCode | Returns 0 if OK, otherwise PI_BAD_GPIO, PI_NOT_HPWM_GPIO, PI_BAD_HPWM_DUTY, PI_BAD_HPWM_FREQ, or PI_HPWM_ILLEGAL. |
Remarks
12 PWM channel 0 All models but A and B 13 PWM channel 1 All models but A and B 18 PWM channel 0 All models 19 PWM channel 1 All models but A and B
40 PWM channel 0 Compute module only 41 PWM channel 1 Compute module only 45 PWM channel 1 Compute module only 52 PWM channel 0 Compute module only 53 PWM channel 1 Compute module only.
GpioPwm(UserGpio, UInt32)
Starts PWM on the GPIO, dutycycle between 0 (off) and range (fully on). Range defaults to 255.
Arduino style: analogWrite
This and the servo functionality use the DMA and PWM or PCM peripherals to control and schedule the pulse lengths and dutycycles.
The GpioSetPwmRange(UserGpio, UInt32) function may be used to change the default range of 255.
Declaration
public static ResultCode GpioPwm(UserGpio userGpio, uint dutyCycle)Parameters
| Type | Name | Description |
|---|---|---|
| UserGpio | userGpio | 0-31. |
| UInt32 | dutyCycle | 0-range. |
Returns
| Type | Description |
|---|---|
| ResultCode | Returns 0 if OK, otherwise PI_BAD_USER_GPIO or PI_BAD_DUTYCYCLE. |
Examples
gpioPWM(17, 255); // Sets GPIO17 full on.
gpioPWM(18, 128); // Sets GPIO18 half on.
gpioPWM(23, 0); // Sets GPIO23 full off.GpioServo(UserGpio, UInt32)
Starts servo pulses on the GPIO, 0 (off), 500 (most anti-clockwise) to 2500 (most clockwise).
The range supported by servos varies and should probably be determined by experiment. A value of 1500 should always be safe and represents the mid-point of rotation. You can DAMAGE a servo if you command it to move beyond its limits.
The following causes an on pulse of 1500 microseconds duration to be transmitted on GPIO 17 at a rate of 50 times per second. This will command a servo connected to GPIO 17 to rotate to its mid-point.
OTHER UPDATE RATES:
This function updates servos at 50Hz. If you wish to use a different update frequency you will have to use the PWM functions.
Firstly set the desired PWM frequency using GpioSetPwmFrequency(UserGpio, UInt32).
Then set the PWM range using GpioSetPwmRange(UserGpio, UInt32) to 1E6/frequency. Doing this allows you to use units of microseconds when setting the servo pulsewidth.
E.g. If you want to update a servo connected to GPIO25 at 400Hz
Thereafter use the PWM command to move the servo, e.g. gpioPWM(25, 1500) will set a 1500 us pulse.
Declaration
public static ResultCode GpioServo(UserGpio userGpio, uint pulseWidth)Parameters
| Type | Name | Description |
|---|---|---|
| UserGpio | userGpio | 0-31. |
| UInt32 | pulseWidth | 0, 500-2500. |
Returns
| Type | Description |
|---|---|
| ResultCode | Returns 0 if OK, otherwise PI_BAD_USER_GPIO or PI_BAD_PULSEWIDTH. |
Remarks
PWM Hz 50 100 200 400 500 1E6/Hz 20000 10000 5000 2500 2000 gpioSetPWMfrequency(25, 400);
gpioSetPWMrange(25, 2500);.
Examples
gpioServo(17, 1000); // Move servo to safe position anti-clockwise.
gpioServo(23, 1500); // Move servo to centre position.
gpioServo(25, 2000); // Move servo to safe position clockwise.GpioSetPwmFrequency(UserGpio, UInt32)
Sets the frequency in hertz to be used for the GPIO.
If PWM is currently active on the GPIO it will be switched off and then back on at the new frequency.
Each GPIO can be independently set to one of 18 different PWM frequencies.
The selectable frequencies depend upon the sample rate which may be 1, 2, 4, 5, 8, or 10 microseconds (default 5).
The frequencies for each sample rate are:.
Declaration
public static ResultCode GpioSetPwmFrequency(UserGpio userGpio, uint frequency)Parameters
| Type | Name | Description |
|---|---|---|
| UserGpio | userGpio | 0-31. |
| UInt32 | frequency |
|
Returns
| Type | Description |
|---|---|
| ResultCode | Returns the numerically closest frequency if OK, otherwise PI_BAD_USER_GPIO. |
Remarks
Hertz
1: 40000 20000 10000 8000 5000 4000 2500 2000 1600 1250 1000 800 500 400 250 200 100 50
2: 20000 10000 5000 4000 2500 2000 1250 1000 800 625 500 400 250 200 125 100 50 25
4: 10000 5000 2500 2000 1250 1000 625 500 400 313 250 200 125 100 63 50 25 13 sample rate (us) 5: 8000 4000 2000 1600 1000 800 500 400 320 250 200 160 100 80 50 40 20 10
8: 5000 2500 1250 1000 625 500 313 250 200 156 125 100 63 50 31 25 13 6
10: 4000 2000 1000 800 500 400 250 200 160 125 100 80 50 40 25 20 10 5.
Examples
gpioSetPWMfrequency(23, 0); // Set GPIO23 to lowest frequency.
gpioSetPWMfrequency(24, 500); // Set GPIO24 to 500Hz.
gpioSetPWMfrequency(25, 100000); // Set GPIO25 to highest frequency.GpioSetPwmRange(UserGpio, UInt32)
Selects the dutycycle range to be used for the GPIO. Subsequent calls to gpioPWM will use a dutycycle between 0 (off) and range (fully on).
If PWM is currently active on the GPIO its dutycycle will be scaled to reflect the new range.
The real range, the number of steps between fully off and fully on for each frequency, is given in the following table.
The real value set by GpioPwm(UserGpio, UInt32) is (dutycycle * real range) / range.
Declaration
public static ResultCode GpioSetPwmRange(UserGpio userGpio, uint range)Parameters
| Type | Name | Description |
|---|---|---|
| UserGpio | userGpio | 0-31. |
| UInt32 | range | 25-40000. |
Returns
| Type | Description |
|---|---|
| ResultCode | Returns the real range for the given GPIO's frequency if OK, otherwise PI_BAD_USER_GPIO or PI_BAD_DUTYRANGE. |
Remarks
25, 50, 100, 125, 200, 250, 400, 500, 625, 800, 1000, 1250, 2000, 2500, 4000, 5000, 10000, 20000.
Examples
gpioSetPWMrange(24, 2000); // Now 2000 is fully on
// 1000 is half on
// 500 is quarter on, etc.