From 13f5dfb5c863e973b3504129220dbc70a1e246ad Mon Sep 17 00:00:00 2001
From: "Earle F. Philhower, III" <earlephilhower@yahoo.com>
Date: Tue, 14 Jul 2020 11:46:54 -0700
Subject: [PATCH 1/3] BREAKING - analogWriteRange 8-bit default

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.

Fixes #2895
---
 cores/esp8266/Arduino.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cores/esp8266/Arduino.h b/cores/esp8266/Arduino.h
index 72cf07c896..e720a7d413 100644
--- a/cores/esp8266/Arduino.h
+++ b/cores/esp8266/Arduino.h
@@ -43,7 +43,7 @@ extern "C" {
 #define HIGH 0x1
 #define LOW  0x0
 
-#define PWMRANGE 1023
+#define PWMRANGE 255
 
 //GPIO FUNCTIONS
 #define INPUT             0x00

From f505ec776ac4daeef7314baf672fde50477baf1b Mon Sep 17 00:00:00 2001
From: "Earle F. Philhower, III" <earlephilhower@yahoo.com>
Date: Sun, 26 Jul 2020 12:57:43 -0700
Subject: [PATCH 2/3] Match upstream Arduino interfaces

Add a `analogWriteResolution` which takes a number of bits and sets
the range from 0...(1<<bits)-1

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).
---
 cores/esp8266/Arduino.h                   |  3 +--
 cores/esp8266/core_esp8266_wiring_pwm.cpp | 15 +++++++++++++--
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/cores/esp8266/Arduino.h b/cores/esp8266/Arduino.h
index e720a7d413..0a16645d22 100644
--- a/cores/esp8266/Arduino.h
+++ b/cores/esp8266/Arduino.h
@@ -43,8 +43,6 @@ extern "C" {
 #define HIGH 0x1
 #define LOW  0x0
 
-#define PWMRANGE 255
-
 //GPIO FUNCTIONS
 #define INPUT             0x00
 #define INPUT_PULLUP      0x02
@@ -176,6 +174,7 @@ int analogRead(uint8_t pin);
 void analogReference(uint8_t mode);
 void analogWrite(uint8_t pin, int val);
 void analogWriteFreq(uint32_t freq);
+void analogWriteResolution(int res);
 void analogWriteRange(uint32_t range);
 
 unsigned long millis(void);
diff --git a/cores/esp8266/core_esp8266_wiring_pwm.cpp b/cores/esp8266/core_esp8266_wiring_pwm.cpp
index 1ebdd64c89..b4991310d3 100644
--- a/cores/esp8266/core_esp8266_wiring_pwm.cpp
+++ b/cores/esp8266/core_esp8266_wiring_pwm.cpp
@@ -27,15 +27,21 @@
 extern "C" {
 
 static uint32_t analogMap = 0;
-static int32_t analogScale = PWMRANGE;
+static int32_t analogScale = 255;  // Match upstream default, breaking change from 2.x.x
 static uint16_t analogFreq = 1000;
 
 extern void __analogWriteRange(uint32_t range) {
-  if (range > 0) {
+  if ((range >= 15) && (range <= 65535)) {
     analogScale = range;
   }
 }
 
+extern void __analogWriteResolution(int res) {
+  if ((res >= 4) && (res <= 16)) {
+    analogScale = (1 << res) - 1;
+  }
+}
+
 extern void __analogWriteFreq(uint32_t freq) {
   if (freq < 100) {
     analogFreq = 100;
@@ -57,6 +63,10 @@ extern void __analogWrite(uint8_t pin, int val) {
     val = analogScale;
   }
 
+  // Per the Arduino docs at https://www.arduino.cc/reference/en/language/functions/analog-io/analogwrite/
+  // val: the duty cycle: between 0 (always off) and 255 (always on).
+  // So if val = 0 we have digitalWrite(LOW), if we have val==range we have digitalWrite(HIGH)
+
   analogMap &= ~(1 << pin);
   uint32_t high = (analogPeriod * val) / analogScale;
   uint32_t low = analogPeriod - high;
@@ -75,5 +85,6 @@ extern void __analogWrite(uint8_t pin, int val) {
 extern void analogWrite(uint8_t pin, int val) __attribute__((weak, alias("__analogWrite")));
 extern void analogWriteFreq(uint32_t freq) __attribute__((weak, alias("__analogWriteFreq")));
 extern void analogWriteRange(uint32_t range) __attribute__((weak, alias("__analogWriteRange")));
+extern void analogWriteResolution(int res) __attribute__((weak, alias("__analogWriteResolution")));
 
 };

From 7522ab13dfa0750ca8317700493dd06fc8104c72 Mon Sep 17 00:00:00 2001
From: "Earle F. Philhower, III" <earlephilhower@yahoo.com>
Date: Tue, 28 Jul 2020 12:21:37 -0700
Subject: [PATCH 3/3] Update documentation for new calls and defaults

Also add note about the change and how to fix pre 3.0 applications.
---
 doc/reference.rst | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/doc/reference.rst b/doc/reference.rst
index db789128e6..6cb03d6928 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -102,9 +102,19 @@ Analog output
 
 ``analogWrite(pin, value)`` enables software PWM on the given pin. PWM
 may be used on pins 0 to 16. Call ``analogWrite(pin, 0)`` to disable PWM
-on the pin. ``value`` may be in range from 0 to ``PWMRANGE``, which is
-equal to 1023 by default. PWM range may be changed by calling
-``analogWriteRange(new_range)``.
+on the pin.
+
+``value`` may be in range from 0 to 255 (which is the Arduino default).
+PWM range may be changed by calling ``analogWriteRange(new_range)`` or
+``analogWriteResolution(bits)``.  ``new_range`` may be from 15...65535
+or ``bits`` may be from 4...16.
+
+**NOTE:** The default ``analogWrite`` range was 1023 in releases before
+3.0, but this lead to incompatibility with external libraries which
+depended on the Arduino core default of 256.  Existing applications which
+rely on the prior 1023 value may add a call to ``analogWriteRange(1023)``
+to their ``setup()`` routine to retrurn to their old behavior.  Applications
+which already were calling ``analogWriteRange`` need no change.
 
 PWM frequency is 1kHz by default. Call
 ``analogWriteFreq(new_frequency)`` to change the frequency. Valid values 
@@ -113,7 +123,7 @@ are from 100Hz up to 40000Hz.
 The ESP doesn't have hardware PWM, so the implementation is by software. 
 With one PWM output at 40KHz, the CPU is already rather loaded. The more 
 PWM outputs used, and the higher their frequency, the closer you get to 
-the CPU limits, and the less CPU cycles are available for sketch execution. 
+the CPU limits, and the fewer CPU cycles are available for sketch execution.
 
 Timing and delays
 -----------------