Changeset 774 for firmware/trunk/libraries/pwmout/pwmout.c

Timestamp:

07/31/08 13:16:09 (5 months ago)

Author:

liamstask

Message:

- incorporating additions from #64
- can more easily configure PWM channels - timing, alignment, etc.
- more & better doc for PWM

Files:

• firmware/trunk/libraries/pwmout/pwmout.c (modified) (7 diffs)

firmware/trunk/libraries/pwmout/pwmout.c

@@ -324 +324 @@
 }
 
-/** @}
-*/
-
 int PwmOut_Start( int index )
 {
@@ -445 +442 @@
 }
 
+/**
+  Set the divider A value.
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param val The value (between 0 and 255)
+  @return 0 on success.
+*/
+int PwmOut_SetDividerAValue(int val)
+{
+   if( val < 0 || val > 255 )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+   
+   int v = Pwm_GetDividerA();
+   
+   //strip off the divider Value
+   v &= 0x00000f00;
+   
+   //add on the new Value
+   v |= val;
+
+   return Pwm_SetDividerA( v );
+}
+
+/**
+  Read the divider A value.
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @return the divider A value (0 - 255)
+  @see PwmOut_SetDividerAValue( )
+*/
+int PwmOut_GetDividerAValue()
+{
+  return ( Pwm_GetDividerA() & 0x000000ff );
+}
+
+/**
+  Set the divider A mux value.
+  @param mux The mux value (between 0 and 10)
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @return 0 on success.
+*/
+int PwmOut_SetDividerAMux(int mux)
+{
+   if( mux < 0 || mux > 10 )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+   
+   int v = Pwm_GetDividerA();
+   
+   //strip off the divider Value
+   v &= 0x000000ff;
+   
+   //add on the new Value
+   v |= ( mux << 8 );
+
+   return Pwm_SetDividerA( v );
+}
+/**
+  Read the divider A mux value.
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @return the divider A mux value (0 - 10)
+  @see PwmOut_SetDividerAMux( )
+*/
+int PwmOut_GetDividerAMux()
+{
+  return ( ( Pwm_GetDividerA() >> 8 ) & 0x0000000f );
+}
+
+/**
+  Set the divider B value.
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param val The value (between 0 and 255)
+  @return 0 on success.
+*/
+int PwmOut_SetDividerBValue(int val)
+{
+   if( val < 0 || val > 255 )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+   
+   int v = Pwm_GetDividerB();
+   
+   //strip off the divider Value
+   v &= 0x00000f00;
+   
+   //add on the new Value
+   v |= val;
+
+   return Pwm_SetDividerA( v );
+}
+
+/**
+  Read the divider B value.
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @return the divider B value (0 - 255)
+  @see PwmOut_SetDividerBValue( )
+*/
+int PwmOut_GetDividerBValue()
+{
+  return ( Pwm_GetDividerB() & 0x000000ff );
+}
+
+/**
+  Set the divider B mux value.
+  @param mux The mux value (between 0 and 10)
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @return 0 on success.
+*/
+int PwmOut_SetDividerBMux(int mux)
+{
+   if( mux < 0 || mux > 10 )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+   
+   int v = Pwm_GetDividerB();
+   
+   //strip off the divider Value
+   v &= 0x000000ff;
+   
+   //add on the new Value
+   v |= ( mux << 8 );
+
+   return Pwm_SetDividerB( v );
+}
+
+/**
+  Read the divider B mux value.
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @return the divider B mux value (0 - 10)
+  @see PwmOut_SetDividerBMux( )
+*/
+int PwmOut_GetDividerBMux()
+{
+  return ( ( Pwm_GetDividerB() >> 8 ) & 0x0000000f );
+}
+
+/**
+  Set the alignment of a channel's waveform.
+  Valid values are:
+  - 0 = Left Aligned (default)
+  - 1 = Center Aligned
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param index The PWM channel (0-3) that you'd like to configure.
+  @param val The alignment value, as described above.
+  @return 0 on success.
+*/
+int PwmOut_SetWaveformAlignment(int index, int val)
+{
+  if ( index < 0 || index > 3 )
+    return CONTROLLER_ERROR_ILLEGAL_INDEX;
+  if ( val > 1 || val < 0 )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+
+  int currval = Pwm_GetWaveformProperties( index ) & 0x00000006; //Leave bits 2 & 3 alone
+  currval |= val;
+  return Pwm_SetWaveformProperties( index, currval );
+}
+
+/**
+  Read the configured waveform alignment for a given PWM channel.
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param index The PWM channel (0-3) you'd like to read from.
+  @return the waveform alignment - see PwmOut_SetWaveformAlignment( )
+*/
+int PwmOut_GetWaveformAlignment( int index )
+{
+  int val = Pwm_GetWaveformProperties( index );
+  if ( val < 0 )
+    return val;
+  
+  return val  & 0x00000001;
+}
+
+/**
+  Set the Waveform Polarity for a PWM channel.
+  Valid values are:
+   - 0 = Start Waveform Low
+   - 1 = Start Waveform High (default)
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param index The PWM channel (0-3) that you'd like to configure.
+  @param val The value, as described above.
+  @return 0 on success.
+*/
+int PwmOut_SetWaveformPolarity(int index, int val)
+{
+  if ( index < 0 || index > 3 )
+    return CONTROLLER_ERROR_ILLEGAL_INDEX;
+  if ( val > 1 || val < 0 )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+
+  int currval = Pwm_GetWaveformProperties( index ) & 0x00000005; //Leave bits 3 & 1 alone
+  currval |= (val << 1);
+  return Pwm_SetWaveformProperties( index, currval );
+}
+
+/**
+  Read the waveform polarity for a given channel.
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param index The PWM channel (0-3) that you'd like to read from.
+  @return The configured polarity for that channel.
+  @see PwmOut_SetWaveformPolarity( )
+*/
+int PwmOut_GetWaveformPolarity( int index )
+{
+  int val = Pwm_GetWaveformProperties( index );
+  if ( val < 0 )
+    return val;
+  
+  return val  & 0x00000002;
+}
+
+/** @}
+*/
+
 #ifdef OSC
 
-/** \defgroup PWMOutOSC PWM Out - OSC
+/** \defgroup pwmout_osc PWM Out - OSC
   Generate PWM signals with the Application Board via OSC.
   \ingroup OSC
@@ -463 +673 @@
   
   \section properties Properties
-  Each PWM Out has four properties:
+  Each PWM Out has the following properties:
   - duty
   - invA
   - invB
   - active
-
-  \par Duty
+  - dividerAValue
+  - dividerAMux
+  - dividerBValue
+  - dividerBMux
+  - clockSource
+  - alignment
+  - polarity
+
+  \subsection Duty
   The \b duty property corresponds to the duty at which a load connected to the output is being driven.
   This value can be both read and written.  The range of values expected by the board
   is from 0 - 1023.
-  \par
-  To generate a 75% on PWM signal, send a message like
+
+  To generate a 75% on PWM signal, send a message like
   \verbatim /pwmout/1/duty 768 \endverbatim
   Leave the argument value off to read the duty:
   \verbatim /pwmout/1/duty \endverbatim
   
-  \par invA
+  \subsection invA
   The \b invA property corresponds to the inversion of the A channel of a PWM Out.
   This value can be both read and written, and the range of values expected is simply 
   0 or 1.  1 means inverted and 0 means normal.  0 is the default.
-  \par
+  
   To set the A channel of the second PWM Out as inverted, send the message
   \verbatim /pwmout/1/invA 1 \endverbatim
   Note that the A channel of PWM Out 1 is Digital Out 2.
   
-  \par invB
+  \subsection invB
   The \b invB property corresponds to the inversion of the B channel of a PWM Out.
   This value can be both read and written, and the range of values expected is simply 
   0 or 1.  1 means inverted and 0 means normal.  0 is the default.
-  \par
+  
   To set the B channel of the fourth PWM Out back to normal, send the message
   \verbatim /pwmout/1/invB 0 \endverbatim
   Note that the A channel of PWM Out 1 is Digital Out 7.
   
-  \par Active
+  \subsection Active
   The \b active property corresponds to the active state of the PWM Out.
   If the device is set to be active, no other tasks will be able to
@@ -504 +721 @@
   locked by sending a message like
   \verbatim /pwmout/0/active \endverbatim
-  \par
+  
   If you're no longer using the PWM Out, it's a good idea to free the 2 Digital Outs by 
   sending the message
   \verbatim /pwmout/0/active 0 \endverbatim
+
+  \section p_adjust Period adjustment of the PWM unit
+
+  The below values allow you to adjust the period length to all possible values as supported
+  by the physical limits of the Make Controller.  Before altering the values, it is good to understand
+  a little about the subsustem of the PWM module.  Please see the general introduction in the \ref Pwm section.
+
+  \subsection DividerBValue
+  The \b dividerXValue property corresponds to the linear divider value within clock divider module X of the 
+  PWM Out.  This value can be between 0 and 255, and linearly divides the clock that is fed into it.  You can 
+  change the incomming clock value by altering the DividerAMux parameter.  Higher linear divider values mean 
+  a longer period.
+  
+  Default value of DividerA is 4. Default value of DividerB is 0.
+
+  \subsection divs DividerAMux & DividerBMux
+  The \b dividerAMux and \b dividerBMux properties select the incoming clock value for divider module A or B (respectively)
+  of the PWM Out.  This value ranges between 0 and 10.  This is similar to the clock source value, eg. a DividerAMux 
+  value of 5 = a clock rate of MasterClock/(2^5)
+  
+  Increasing this value will substantially increase the period of the PWM.  Use the DividerXValue parameter 
+  to more finely tune the value of the period.  
+  
+  Default value of MuxA is 4.  Default value of MuxB is 0.        
+
+  \subsection ClockSource
+  The \b clockSource property selects the incoming clock value for the specified PWM channel. A clock 
+  source of \b 0-10 represents the Master clock divided by 2 to the power of the Clock Source Value, eg. a clock 
+  source value of 5 = a clock rate of MasterClock/(2^5).  A value of \b 11 sets the Clock source to be 
+  generated by clock Divider A.  A value of \b 12 sets the Clock source to be generated by clock Divider B
+  
+  The default value is 11 (Divider A).
+
+  \subsection WaveformAlignment
+  The \b waveformAlignment property chooses whether the channel is left aligned or center aligned.
+  The following values are valid:
+   - 0 = Left aligned
+   - 1 = Center aligned
+  
+  A left aligned channel counts up to the maximum duty cycle, then resets the counter.  A center aligned 
+  channel counts up to the maximum duty cycle, then counts down to zero, etc. The default is left aligned.
+
+  \subsection WaveformPolarity
+  The \b polarity property chooses whether the channel begins its period high or low.  The following values are valid:
+   - 0 = Normal Polarity
+   - 1 = Inverted Polarity
+  
+  Normal polarity starts low, then goes high.  Inverted polarity starts high, then goes low.  The default is inverted polarity.
 */
 
@@ -517 +782 @@
 // MUST end in zero
 static char* PwmOutOsc_Name = "pwmout";
-static char* PwmOutOsc_PropertyNames[] = { "active", "duty", "invA", "invB", 0 }; // must have a trailing 0
+static char* PwmOutOsc_PropertyNames[] = { "active", "duty", "invA", "invB", 
+             "dividerAValue", "dividerAMux",
+             "dividerBValue", "dividerBMux",
+             "clockSource", "alignment",
+             "polarity",
+             0 }; // must have a trailing 0
 
 int PwmOutOsc_PropertySet( int index, int property, int value );
@@ -559 +829 @@
       PwmOut_SetInvertB( index, value );
       break;
+    case 4:
+      PwmOut_SetDividerAValue(value);
+      break;
+    case 5:
+      PwmOut_SetDividerAMux(value);
+      break;
+    case 6:
+      PwmOut_SetDividerBValue(value);
+      break;
+    case 7:
+      PwmOut_SetDividerBMux(value);
+      break;
+    case 8:
+      Pwm_SetClockSource( index, value );
+      break;
+    case 9:
+      PwmOut_SetWaveformAlignment( index, value );
+      break;
+    case 10:
+      PwmOut_SetWaveformPolarity( index, value );
+      break;
   }
   return CONTROLLER_OK;
@@ -581 +872 @@
       value = PwmOut_GetInvertB( index );
       break;
+    case 4:
+      value = PwmOut_GetDividerAValue();
+      break;
+    case 5:
+      value = PwmOut_GetDividerAMux();
+      break;
+    case 6:
+      value = PwmOut_GetDividerBValue();
+      break;
+    case 7:
+      value = PwmOut_GetDividerBMux();
+      break;
+    case 8:
+      value = Pwm_GetClockSource( index );
+      break;
+    case 9:
+      value = PwmOut_GetWaveformAlignment( index );
+      break;
+    case 10:
+      value = PwmOut_GetWaveformPolarity( index );
+      break;
   }
   return value;