oPWMS Object

The oPWMS Object is an I/O Function Object that outputs a Pulse-Width-Modulated clock cycle on a single I/O line. The Pulse that it generates is designed to control a standard RC Servo by generating a High-Going pulse with a width ranging from 0 to 3ms in duration and the output clock cycles at either a frequency 35hz or 70hz. 

The oPWMS Object is capable of positioning an RC Servo anywhere within its 180 degree rotational span.  The position within the 180 degree span is specified by a value and once the servo has reached the specified position, it is held in place until the value changes or the oPWMS Object is turned off. 

The Operate property specifies if the logic-high portion of the clock cycle output is generated.  When the Operate property is set to 1, the oPWMS Object starts generating PWM pulses. When the Operate property is set to 0, the PWM pulses are discontinued and the specified I/O Line is set to 0-Volts.

The Pulse-Width of the logic-high portion of the clock cycle output is expressed in ~0.028ms (1ms/36) increments and is determined by the value of the DutyCycle property plus the value of the Adjust property which is calculated as ((DutyCycle + Adjust) * (1ms / 36)).  If the Invert property is set to 1 then the pulse time is calculated as ((107 - (Value + Center)) * (1/36)).  Note that only the lower 8 bits of the total value of DutyCycle + Adjust is used.  If the total value of DutyCycle + Adjust is equal to 0, then a value of 256 is used instead.

A typical servo with a rotational range of 180 degrees is positioned by the duration of a Logical high-going pulse in the range of .61ms to 2.36ms.  Setting the Adjust property to 22 provides the proper adjustment for timing range of the servo while allowing for fine tuning. ((0+22) * (1/36)) = .61ms  for the lower side of the range and ((63+22) * (1/36)) = 2.36ms for the upper side.  Note that the range for the duty cycle used here is 0 to 64.  The total range is 0 to 255.  Therefore, when driving a servo, care must be taken to not exceed a duty cycle with a pulse of longer than 2.36ms.

The Invert property inverts the pulse around the 1.5ms setting. ((107-(0+22)) * (1/36)) = 2.36ms

Each dimensioned instance of the oPWMS Object shares the Servo Motor Control module (SMCM) which multitasks between all active oPWMS Objects.  The SMCM provides the servo control pulse that is required to electrically refresh a servo motor's position and can output the control pulse on any of the ooPIC's 31 I/O Lines.

The frequency of the output clock cycle is a result of the SM control module being activated 35 times each second, which in turn outputs the PWM Logical high-going pulse for each active oPWMS Object 35 times per second. If the sum of the duration of all PWM Logical high-going pulses from all the active oPWMS Objects totals more than 1/35th of a second, then the refresh cycle time is stretched to accommodate the total time of all the duty cycles combined.  For example; 12 oPWMS objects set to 2.36ms take 28.32 milliseconds to output. (2.36ms * 12 servos = 0.02832 Seconds) which is within the 1/35th of a second (0.02857 Seconds) time frame, therefore, the refresh cycle is not stretched.  But, 21 oPWMS objects set to 2.36ms take 49.56 milliseconds to output. (2.36ms * 21 servos = 0.04956 Seconds) which will stretch the frequency of the output clock cycle to 20.18 times per second.

As of firmware B.2.x, the frequency of the output clock cycle can be set to 70hz.  This mode can be selected by setting the Period property to 1.  When in this mode, all the timing calculations discussed above are adjusted appropriately.

For each cycle of the output clock, the SMCM first looks for the first active oPWMS Objects. (The first oPWMS Object with its Operate property set to 1). That object's I/O line is set to begin the high-going pulse. When the duration of the PWM Logical high-going pulse is met, the I/O line is set to low and the SMCM moves to the next active oPWMS Object. The SMCM will systematically continue through each active oPWMS Object until all have been completed and then repeats the process.

The oServoSP Object uses this object, but modifies the way the Pulse-Width-Modulated clock cycle is output.  This modification evenly distributes the PWM pulse at a rate of ((Value+1) pulses every 3.6 seconds.  For example; a Value of 1 will issue 2 control pulses every 3.6 seconds which evenly distributes to 1 control pulse every 1.8 seconds.  A value of 63 will issue 64 control pulses every 3.6 seconds which evenly distributes to 17.7 control pulses every second.  And a value of 127 will issue 128 control pulses every 3.6 seconds which evenly distributes to 35.5 control pulses every second. 

The following table lists the properties of the oPWMS Object:

Property	Description
DutyCycle	A value that specifies the duty cycle of the PWM output. Object Class:  oByte   Value Range:  0 - 255* Data Type:  Numeric   Default Value:  0 The DutyCycle property is expressed in ~0.028ms (1ms/36) increments.  Note that a value of 0 is evaluated as 256. *The DutyCycle property can be any value from 0 to 255 which gives a pulse width time of 0.28ms to 7.14ms.  This is beyond the range for a typical servo motor which needs a pulse that has a range of .61ms to 2.36ms.
IOLine	A value that specifies which I/O Line is used to output the PWM. Object Class:  oIOLine   Value Range:  0 - 31 Data Type:  Numeric   Default Value:  0 Some I/O Lines have special purposes.  Be sure to see oIOLine help file for details.
Adjust	A value that specifies an adjustment to the duty cycle. Object Class:  oAdjust63   Value Range:  0 - 63 Data Type:  Numeric   Default Value:  0
Invert	A value that selects if the duty cycle timing is to be inverted around a center time of 1.5ms. Object Class:  oSelect0to1L   Value Range:  0 - 1 Data Type:  Numeric   Default Value:  0 Invert Constant Description 0 cvFalse The pulse signal is normal 1 cvTrue The pulse signal is reversed.
Period	A value that selects the cycle frequency of the PWM output. Object Class:  oSelect0to1   Value Range:  0 - 1 Data Type:  Numeric   Default Value:  0 Operate Constant Description 0 cvFalse The cycle frequency is 35 times per second. 1 cvTrue The cycle frequency is 70 times per second.
Operate	A value that specifies whether or not the PWM is outputted. Object Class:  oOperate   Value Range:  0 - 1 Data Type:  Numeric   Default Value:  0 Operate Constant Description 0 cvOff The PWM signal remains Low. 1 cvOn The PWM signal outputs a high pulse with a Duty Cycle determined by the DutyCycle property plus the Adjust property.
Address	Returns a pointer to the address of the oCounter Object instance. Object Class:  oAddress   Value Range:  0 - 127 Data Type: Pointer (Read Only)   Default Value:  Address of Object

Visual Basic Syntax	C and Java Syntax
'This program alternates 'an output between a pulse 'of 0.61ms and 2.36ms Dim S1 As New oPWMS Sub main() S1.IOLine = 31 S1.Adjust = 22 S1.Operate =cvTrue Do S1.DutyCycle = 0 ooPIC.Delay = 150 S1.DutyCycle = 63 ooPIC.Delay = 150 Loop End Sub	// This program alternates // an output between a pulse // of 0.61ms and 2.36ms oPWMS S1 = New oPWMS; Void main(Void){ S1.IOLine = 31; S1.Adjust = 22; S1.Operate = cvTrue; Do{ S1.DutyCycle = 0; ooPIC.Delay = 150; S1.DutyCycle = 63; ooPIC.Delay = 150; } While (1); }
Basic Syntax
'This program alternates 'an output between a pulse 'of 0.61ms and 2.36ms Dim S1 As New oPWMS(31,22,,,,cvOn) Do S1.DutyCycle = 0 ooPIC.Delay = 150 S1.DutyCycle = 63 ooPIC.Delay = 150 Loop

Bugs: Compiler version 5.0.1 will not compile oPWMS objects for Firmware A.2.0. The workaround is to compile as Firmware A.1.7, but you then can't use oSrvSync objects.  Fixed in Compiler version 6.0.0