C# Class CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider

A GPIO provider that implements the PCA9685 16-channel, 12-bit PWM I2C-bus LED/Servo controller as native MonoPi GPIO pins. The PCA9685 is connected via I2C connection to the Raspberry Pi and provides 16 PWM pins that can be used for PWM output.
More information about the PCA9685 can be found here:
PCA9685.pdf

And especially about the board here:
Adafruit 16-Channel 12-bit PWM/Servo Driver
Inheritance: IDisposable
Mostra file Open project: cyrusbuilt/MonoPi Class Usage Examples

Public Methods

Method Description
CalcOffPosForPulseDuration ( Int32 duration ) : Int32

Calculates the OFF position for the specified pulse duration.
Dispose ( ) : void

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Call Dispose when you are finished using the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider. The Dispose method leaves the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider in an unusable state. After calling Dispose, you must release all references to the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider so the garbage collector can reclaim the memory that the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider was occupying.

GetPin ( IPCA9685Pin pin ) : IPCA9685Pin

Gets the specified pin from the pin cache. If the specified pin does not already exist in the cache, it will be cached first, then returned to the caller.
GetPwmOnOffValues ( IPCA9685Pin pin ) : Int32>.Tuple

Gets the PWM on/off values for the specified pin.
HasPin ( IPCA9685Pin pin ) : System.Boolean

Determines whether this instance has pin the specified pin in the internal pin cache.
PCA9685GpioProvider ( BoardRevision rev, Int32 address ) : System

Initializes a new instance of the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider class with the Raspberry Pi board revision and address of the PCA9685 on the I2C bus.
PCA9685GpioProvider ( II2CBus bus, Int32 address ) : System

Initializes a new instance of the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider class with the I2C bus device and bus address of PCA9685 device. This overload uses the default target frequency value.
PCA9685GpioProvider ( II2CBus bus, Int32 address, Decimal targetFreq ) : System

Initializes a new instance of the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider class with the I2C bus device, bus address of PCA9685 device, and target frequency.
PCA9685GpioProvider ( II2CBus bus, Int32 address, Decimal targetFreq, Decimal freqCorrectionFactor ) : System

Initializes a new instance of the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider class with the I2C bus device, bus address of PCA9685 device, target frequency, and frequency correction factor.
Reset ( ) : void

Resets all outputs (set to always OFF).
SetAlwaysOff ( IPCA9685Pin pin ) : void

Sets the always off.
SetAlwaysOn ( IPCA9685Pin pin ) : void

Permanently sets the output to HIGH (no PWM anymore).
The LEDn_ON_H output control bit 4, when set to logic 1, causes the output to be always ON.
SetFrequency ( Decimal freq ) : void

Sets the target frequency (accuracy is around +/- 5%!).
SetFrequency ( Decimal targetFreq, Decimal freqCorrectionFactor ) : void

The built-in oscillator runs at ~25MHz. For better accuracy, this method can be used to provide a correction factor to meet desired frequency.

Note: Correction is limited to a certain degree because the calculated prescale value has to be rounded to an integer value!
Example:
Target frequency: 50Hz
Actual frequency: 52.93Hz
Correction factor: 52.93 / 50 = 1.0586

SetPWM ( IPCA9685Pin pin, Int32 duration ) : void

Sets the pulse duration in microseconds.
Make sure duration doesn't exceed period time (1,000,000/freq)!
SetPWM ( IPCA9685Pin pin, Int32 onPos, Int32 offPos ) : void

Sets the PWM values for the specified pin. The LEDn_ON and LEDn_OFF counts can vary from 0 to 4095 max.
The LEDn_ON and LEDn_OFF count registers should never be programmed with the same values.

Because the loading of the LEDn_ON and LEDn_OFF registers is via I2C-bus, and asynchronous to the internal oscillator, it is best to ensure that there are no visual artifacts of changing the ON and OFF values. This is achieved by updating the changes at the end of the LOW cycle.

Private Methods

Method Description
CachePinValues ( IPCA9685Pin pin, Int32 onPosition, Int32 offPosition ) : void

Caches the pin values.
CalcPeriodDuration ( ) : Int32

Calculates the duration of the period.
CalcPrescale ( Decimal freqCorrectionFactor ) : Int32

Calculates the prescale based on the internal clock frequency and the specified frequency correction factor.
ValidateFrequency ( Decimal freq ) : void

Validates the frequency. Throws an ArgumentOutOfRangeException if the frequency is not in range.
ValidatePin ( IPCA9685Pin pin, Int32 onPosition, Int32 offPosition ) : void

Validates the specified pin and throws an exception if invalid.
ValidatePwmDuration ( Int32 duration ) : void

Validates the duration of the PWM.
ValidatePwmValueInRange ( Int32 pwm ) : void

Validates the specified PWM value and throws an ArgumentOutOfRangeException if the value is not in range..

Method Details

CalcOffPosForPulseDuration() public method

Calculates the OFF position for the specified pulse duration.
/// The duration is less than 1 or less than or equal to the period duration. ///
public CalcOffPosForPulseDuration ( Int32 duration ) : Int32
duration System.Int32 /// Pulse duration in microseconds. ///
return System.Int32

Dispose() public method

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
Call Dispose when you are finished using the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider. The Dispose method leaves the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider in an unusable state. After calling Dispose, you must release all references to the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider so the garbage collector can reclaim the memory that the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider was occupying.
public Dispose ( ) : void
return void

GetPin() public method

Gets the specified pin from the pin cache. If the specified pin does not already exist in the cache, it will be cached first, then returned to the caller.
public GetPin ( IPCA9685Pin pin ) : IPCA9685Pin
pin IPCA9685Pin /// The pin to get from the cache. ///
return IPCA9685Pin

GetPwmOnOffValues() public method

Gets the PWM on/off values for the specified pin.
public GetPwmOnOffValues ( IPCA9685Pin pin ) : Int32>.Tuple
pin IPCA9685Pin /// The pin to get the on/off values for (Channel 0 .. 15). ///
return Int32>.Tuple

HasPin() public method

Determines whether this instance has pin the specified pin in the internal pin cache.
public HasPin ( IPCA9685Pin pin ) : System.Boolean
pin IPCA9685Pin /// The pin to check for. ///
return System.Boolean

PCA9685GpioProvider() public method

Initializes a new instance of the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider class with the Raspberry Pi board revision and address of the PCA9685 on the I2C bus.
/// An I/O error occurred. The specified address is inacessible or the /// I2C transaction failed. ///
public PCA9685GpioProvider ( BoardRevision rev, Int32 address ) : System
rev BoardRevision /// The Raspiberry Pi board revision being used. This is used to determine /// which bus to use for I2C. ///
address System.Int32 /// The address of the PCA9685 on the I2C bus. ///
return System

PCA9685GpioProvider() public method

Initializes a new instance of the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider class with the I2C bus device and bus address of PCA9685 device. This overload uses the default target frequency value.
/// The specified I2C bus instance has been disposed and can no longer be used. /// /// An I/O error occurred. The specified address is inacessible or the /// I2C transaction failed. ///
public PCA9685GpioProvider ( II2CBus bus, Int32 address ) : System
bus II2CBus /// The I2C bus device used to communicate with the PCA9685 chip. ///
address System.Int32 /// The address of the PCA9685 on the I2C bus. ///
return System

PCA9685GpioProvider() public method

Initializes a new instance of the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider class with the I2C bus device, bus address of PCA9685 device, and target frequency.
/// must be between 40Hz and 1000Hz. /// /// The specified I2C bus instance has been disposed and can no longer be used. /// /// An I/O error occurred. The specified address is inacessible or the /// I2C transaction failed. ///
public PCA9685GpioProvider ( II2CBus bus, Int32 address, Decimal targetFreq ) : System
bus II2CBus /// The I2C bus device used to communicate with the PCA9685 chip. ///
address System.Int32 /// The address of the PCA9685 on the I2C bus. ///
targetFreq Decimal /// The target PWM frequency to set. ///
return System

PCA9685GpioProvider() public method

Initializes a new instance of the CyrusBuilt.MonoPi.IO.PCA.PCA9685GpioProvider class with the I2C bus device, bus address of PCA9685 device, target frequency, and frequency correction factor.
/// cannot be null. /// /// must be between 40Hz and 1000Hz. /// /// The specified I2C bus instance has been disposed and can no longer be used. /// /// An I/O error occurred. The specified address is inacessible or the /// I2C transaction failed. ///
public PCA9685GpioProvider ( II2CBus bus, Int32 address, Decimal targetFreq, Decimal freqCorrectionFactor ) : System
bus II2CBus /// The I2C bus device used to communicate with the PCA9685 chip. ///
address System.Int32 /// The address of the PCA9685 on the I2C bus. ///
targetFreq Decimal /// The target PWM frequency to set. ///
freqCorrectionFactor Decimal /// The PWM frequency correction factor. ///
return System

Reset() public method

Resets all outputs (set to always OFF).
public Reset ( ) : void
return void

SetAlwaysOff() public method

Sets the always off.
/// cannot be null. /// /// does not exist in the pin cache. /// /// The specified pin is not in PWM mode. /// /// Unable to write to the specified channel (pin address). ///
public SetAlwaysOff ( IPCA9685Pin pin ) : void
pin IPCA9685Pin /// The pin to set always off (Channel 0 .. 15). ///
return void

SetAlwaysOn() public method

Permanently sets the output to HIGH (no PWM anymore).
The LEDn_ON_H output control bit 4, when set to logic 1, causes the output to be always ON.
/// cannot be null. /// /// does not exist in the pin cache. /// /// The specified pin is not in PWM mode. /// /// Unable to write to the specified channel (pin address). ///
public SetAlwaysOn ( IPCA9685Pin pin ) : void
pin IPCA9685Pin /// The pin to set always on (Channel 0 .. 15). ///
return void

SetFrequency() public method

Sets the target frequency (accuracy is around +/- 5%!).
/// must be between 40Hz and 1000Hz. /// /// No open connection to the PCA9585 I2C device. /// /// An I/O error occurred while trying to access I2C address. ///
public SetFrequency ( Decimal freq ) : void
freq Decimal /// The desired PWM frequency. ///
return void

SetFrequency() public method

The built-in oscillator runs at ~25MHz. For better accuracy, this method can be used to provide a correction factor to meet desired frequency.
Note: Correction is limited to a certain degree because the calculated prescale value has to be rounded to an integer value!
Example:
Target frequency: 50Hz
Actual frequency: 52.93Hz
Correction factor: 52.93 / 50 = 1.0586
/// must be between 40Hz and 1000Hz. /// /// No open connection to the PCA9585 I2C device. /// /// An I/O error occurred while trying to access I2C address. ///
public SetFrequency ( Decimal targetFreq, Decimal freqCorrectionFactor ) : void
targetFreq Decimal /// The desired frequency. ///
freqCorrectionFactor Decimal /// Actual frequency/target frequency. ///
return void

SetPWM() public method

Sets the pulse duration in microseconds.
Make sure duration doesn't exceed period time (1,000,000/freq)!
/// cannot be null. /// /// does not exist in the pin cache. /// /// The specified pin is not in PWM mode. /// /// Unable to write to the specified channel (pin address). ///
public SetPWM ( IPCA9685Pin pin, Int32 duration ) : void
pin IPCA9685Pin /// The pin to set the pulse duration for (Channel 0 .. 15). ///
duration System.Int32 /// Pulse duration in microseconds. ///
return void

SetPWM() public method

Sets the PWM values for the specified pin. The LEDn_ON and LEDn_OFF counts can vary from 0 to 4095 max.
The LEDn_ON and LEDn_OFF count registers should never be programmed with the same values.

Because the loading of the LEDn_ON and LEDn_OFF registers is via I2C-bus, and asynchronous to the internal oscillator, it is best to ensure that there are no visual artifacts of changing the ON and OFF values. This is achieved by updating the changes at the end of the LOW cycle.
/// cannot be null. /// /// does not exist in the pin cache. - or - /// and are equal. /// /// The specified pin is not in PWM mode. /// /// Unable to write to the specified channel (pin address). ///
public SetPWM ( IPCA9685Pin pin, Int32 onPos, Int32 offPos ) : void
pin IPCA9685Pin /// The pin to set the PWM values for (Channel 0 .. 15). ///
onPos System.Int32 /// The PWM threshold to consider the pin "on" (value between 0 and 4095). ///
offPos System.Int32 /// The PWM threshold to consider the pin "off" (value between 0 and 4095). ///
return void