setPWM description is incomplete/misleading

[dzalf]

According to the library reference this function sets the start and end of the high segment of the pulse.

In the provided example, the pair (1024, 3072) produces a high pulse at 25% (1024) and then remains low for the last 25% of the pulse. It should be clarified and or emphasised that this refers to the HIGH PULSE effectively producing a 50% total duty, cycle, as seen in the following DSO capture (please pay attention to the cursors):

HOWEVER the PWM train should be observed as the following wave (pay attention to the new location of the cursors):

which is in line with the textual description:

"The following example will cause channel 15 to start low, go high around 25% into the pulse (tick 1024 out of 4096), transition back to low 75% into the pulse (tick 3072), and remain low for the last 25% of the pulse"

It is prone to confuse newcomers and somewhat advanced users.

This is what the device spits out with the debug mode enabled:

So, if you want to implement a function to set a duty cycle from 0% to 100%, you could do something like this:

/**
 * @brief Set the duty cycle for any channel
 *
 * @param pin [0,15] port to drive
 * @param duty [0,100] 12-bit driving value
 * 
 */
void setLowSideDuty(uint8_t pin, uint8_t duty) {

  double onDuty, offDuty;

  onDuty = ceil(LO_SIDE_ON_DUTY * (duty / 100.0));    // LO_SIDE_ON_DUTY is 4096
  offDuty = ceil(LO_SIDE_ON_DUTY - onDuty);

#ifdef DEBUG_ENABLE

  Serial.print("Desired duty:");
  Serial.print(duty);
  Serial.println("%");

  Serial.print("On:");
  Serial.println((uint16_t)onDuty);

  Serial.print("Off:");
  Serial.println((uint16_t)offDuty);
  
#endif

  controller.pwm.setPWM(pin, 0, (uint16_t)onDuty);
  
}

then simply use:

 setLowSideDuty(15, 42);  

Perhaps, a couple of voltammograms along with a clearer description might help a lot.

Cheers

EDIT: Added a comment on the macro value I used in my example code