PWM functions

[Gavin-Perry]

I am using PWM to control a solenoid that can not have full voltage for more than 2ms.
I'm finding limited documentation for analogWriteRange() and analogWriteResolution()
Is there a suggested order for these as they seem do to interact
For example if I have the following driving a Darlington Solenoid driver (UL2803) with 12V output (Common)

#define MyPin 18
#define FULL 100  // 100% 
void setup() {
  analogWriteFreq(30000);   // Get out of audible range
  analogWriteRange(100);  // let me use % for range
  analogWriteResolution(12);  // Should I put Res before Range?
}

void loop() {
  analogWrite(MyPin,FULL);
  delay(2);
  analogWrite(MyPin,FULL/7);     // 1/7 power for hold (1.7V)
    delay(3000);
    digitalWrite(MyPin, LOW); // Make it really off, stop PWM noise
// Is this OK to do or must I use analogWrite(MyPin,0);
}

Because 12 bits is range 0-4095 and I'm only getting fractions of a volt for FULL at 100
It seems that if I ask for 12 bit resolution then Range of 0-100 means all I get is 0 to 100/4096
I thought Range was setting a scale and documentation isn't clear what that means.
If I change FULL to 4095 (or should I use 4096?) I get the expected range (thus why I used FULL/7 instead of 14%)
Should FULL be 4095? Then would I set Range to FULL+1? (or it doesn't matter?)
I read the code in wiring_analog.cpp but it's not straightforward, with lots of scaling games to make things fit, but not as I expected.

Finally, although analogWrite() takes care of everything for the analog output (PWM mode setting...)
do I need to set pinMode(MyPin, OUTPUT); for the digitalWrite() to work? and will that be saved? (looks like it)

Thanks as always for your great support.

[earlephilhower]

Moved to a discussion since it seems more of a question than a bug. If something does fall out we can open specific issues.

You should set the pinMode before using, just like other IOs.

Use either analogWriteRange or analogWriteResolution, not both. They both just define the domain of inputs you'll be passing in to analogWrite and the last one will take precedence.

analogWriteFrequency sets the PWM frequency as best it can given sys_clk.

Note that not all combinations of range and frequency are actually achievable in the HW. For example, at high PWM frequencies you can't actually have very large ranges because the clocking just doesn't work, and vice versa for very low frequencies. Your code can still pass in data with the requested range, but it will be adjusted to what the real HW can perform behind the scenes.

[Gavin-Perry]

Thanks for the clarification. Documentation would be helpful but this would involve coordinating with Arduino.cc
So what does Range mean?
I understand bits of resolution and the clock timing issues. Thus keeping relatively low at 30kHz
I don't really need 12 bits as long as it gets as close as possible. I'm using 10 bits in my actual code but even 1% is enough resolution.
Speed of execution going from 100% to 14% is more critical.

[earlephilhower]

Using range and set it to 100 means that you get the PWM periods evenly split into 100 different positions. analogWriteResolution just lets you pass in log2(bits needed) *i.e. analogWriteResolution(12) === analogWriteRange(4096) for folks who want to pretend there's a physical ADC there with only fixed bit widths available. Resolution is an API leftover from 8-bit AVR Arduino days.

If you want 100 divisions of %age, then your analogWriteRange(100) is all you need. The code will do its best to make those as exact as possible w/in the HW limitations. The values change instantaneously (modulo the simple math in the fast path and obviously ~one PWM cycle).