Skip to content

Commit a679869

Browse files
BREAKING - analogWriteRange 8-bit default (#7456)
Matching standard Arduino cores, make the default analogWrite() take values from 0...255. Users can always use the analogWriteRange() call to change to a different setup. Add a `analogWriteResolution` which takes a number of bits and sets the range from 0...(1<<bits)-1, part of the standard Arduino API. Remove the PWMRANGE define. It's non-standard and not generally valid (i.e. it's fixed at 1024 of 256, but the real range varies depending on what you last set). Also add note about the change and how to fix pre 3.0 applications. Fixes #2895
1 parent 3308386 commit a679869

File tree

3 files changed

+28
-8
lines changed

3 files changed

+28
-8
lines changed

cores/esp8266/Arduino.h

+1-2
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,6 @@ extern "C" {
4343
#define HIGH 0x1
4444
#define LOW 0x0
4545

46-
#define PWMRANGE 1023
47-
4846
//GPIO FUNCTIONS
4947
#define INPUT 0x00
5048
#define INPUT_PULLUP 0x02
@@ -176,6 +174,7 @@ int analogRead(uint8_t pin);
176174
void analogReference(uint8_t mode);
177175
void analogWrite(uint8_t pin, int val);
178176
void analogWriteFreq(uint32_t freq);
177+
void analogWriteResolution(int res);
179178
void analogWriteRange(uint32_t range);
180179

181180
unsigned long millis(void);

cores/esp8266/core_esp8266_wiring_pwm.cpp

+13-2
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,21 @@
2727
extern "C" {
2828

2929
static uint32_t analogMap = 0;
30-
static int32_t analogScale = PWMRANGE;
30+
static int32_t analogScale = 255; // Match upstream default, breaking change from 2.x.x
3131
static uint16_t analogFreq = 1000;
3232

3333
extern void __analogWriteRange(uint32_t range) {
34-
if (range > 0) {
34+
if ((range >= 15) && (range <= 65535)) {
3535
analogScale = range;
3636
}
3737
}
3838

39+
extern void __analogWriteResolution(int res) {
40+
if ((res >= 4) && (res <= 16)) {
41+
analogScale = (1 << res) - 1;
42+
}
43+
}
44+
3945
extern void __analogWriteFreq(uint32_t freq) {
4046
if (freq < 100) {
4147
analogFreq = 100;
@@ -57,6 +63,10 @@ extern void __analogWrite(uint8_t pin, int val) {
5763
val = analogScale;
5864
}
5965

66+
// Per the Arduino docs at https://www.arduino.cc/reference/en/language/functions/analog-io/analogwrite/
67+
// val: the duty cycle: between 0 (always off) and 255 (always on).
68+
// So if val = 0 we have digitalWrite(LOW), if we have val==range we have digitalWrite(HIGH)
69+
6070
analogMap &= ~(1 << pin);
6171
uint32_t high = (analogPeriod * val) / analogScale;
6272
uint32_t low = analogPeriod - high;
@@ -75,5 +85,6 @@ extern void __analogWrite(uint8_t pin, int val) {
7585
extern void analogWrite(uint8_t pin, int val) __attribute__((weak, alias("__analogWrite")));
7686
extern void analogWriteFreq(uint32_t freq) __attribute__((weak, alias("__analogWriteFreq")));
7787
extern void analogWriteRange(uint32_t range) __attribute__((weak, alias("__analogWriteRange")));
88+
extern void analogWriteResolution(int res) __attribute__((weak, alias("__analogWriteResolution")));
7889

7990
};

doc/reference.rst

+14-4
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,19 @@ Analog output
102102

103103
``analogWrite(pin, value)`` enables software PWM on the given pin. PWM
104104
may be used on pins 0 to 16. Call ``analogWrite(pin, 0)`` to disable PWM
105-
on the pin. ``value`` may be in range from 0 to ``PWMRANGE``, which is
106-
equal to 1023 by default. PWM range may be changed by calling
107-
``analogWriteRange(new_range)``.
105+
on the pin.
106+
107+
``value`` may be in range from 0 to 255 (which is the Arduino default).
108+
PWM range may be changed by calling ``analogWriteRange(new_range)`` or
109+
``analogWriteResolution(bits)``. ``new_range`` may be from 15...65535
110+
or ``bits`` may be from 4...16.
111+
112+
**NOTE:** The default ``analogWrite`` range was 1023 in releases before
113+
3.0, but this lead to incompatibility with external libraries which
114+
depended on the Arduino core default of 256. Existing applications which
115+
rely on the prior 1023 value may add a call to ``analogWriteRange(1023)``
116+
to their ``setup()`` routine to retrurn to their old behavior. Applications
117+
which already were calling ``analogWriteRange`` need no change.
108118

109119
PWM frequency is 1kHz by default. Call
110120
``analogWriteFreq(new_frequency)`` to change the frequency. Valid values
@@ -113,7 +123,7 @@ are from 100Hz up to 40000Hz.
113123
The ESP doesn't have hardware PWM, so the implementation is by software.
114124
With one PWM output at 40KHz, the CPU is already rather loaded. The more
115125
PWM outputs used, and the higher their frequency, the closer you get to
116-
the CPU limits, and the less CPU cycles are available for sketch execution.
126+
the CPU limits, and the fewer CPU cycles are available for sketch execution.
117127

118128
Timing and delays
119129
-----------------

0 commit comments

Comments
 (0)