WIP pwm

Author: aykevl

config.toml

@@ -30,3 +30,7 @@ weight = 30
 name = "<i class='fab fa-slack'></i> Slack"
 url = "https://gophers.slack.com/messages/CDJD3SUP6/"
 weight = 40
+
+[markup.goldmark.renderer]
+# Allow raw HTML and JavaScript.
+unsafe = true

content/microcontrollers/machine/pwm.md

@@ -0,0 +1,166 @@
+---
+title: PWM
+weight: 1
+---
+
+## What is PWM?
+
+PWM, short for Pulse Width Modulation, is a trick to dim a digital output by switching the output on and off quickly enough so that the average remains at a value somewhere between on and off. Using this trick, a digital output starts to behave like an analog output. One very common application is dimming of LEDs.
+
+In the example below you can control a simulated LED using PWM. You can change the duty cycle and the speed and see how that affects the LED. Notice how, if the frequency is high enough, the output appears continuous.
+
+<label>
+  Duty cycle: <span id="pwm-dutycycle">50%</span>
+  <input id="pwm-dutycycle-input" type="range" value="50" min="0" max="100"/>
+</label>
+
+<label>
+  Speed: <span id="pwm-period">1000ms</span> or <span id="pwm-frequency">1Hz</span>
+  <input id="pwm-period-input" type="range" value="0" min="0" max="30"/>
+</label>
+
+<svg viewBox="0 0 340 30" width="340px" height="30px">
+  <rect x="0.5" y="0.5" width="302" height="28" fill="transparent" stroke="gray"/>
+  <path id="pwm-path" fill="transparent" stroke="black" stroke-linecap="square" d="M 1.5 27.5 H 1.5 V 1.5 H 151.5 V 27.5 H 301.5"/>
+  <circle id="pwm-led" cx="325" cy="14.5" r="10" fill="gray" stroke-width="1" stroke="gray"/>
+</svg>
+
+<style id="pwm-styles">
+/* Note: these properties will be modified from JavaScript using CSSOM. */
+#pwm-led {
+  animation-duration: 1s;
+  animation-name: pwm;
+  animation-iteration-count: infinite;
+}
+@keyframes pwm {
+  from {
+    fill: transparent;
+  }
+  10% {
+    fill: red;
+  }
+  50% {
+    fill: red;
+  }
+  60% {
+    fill: transparent;
+  }
+  to {
+    fill: transparent;
+  }
+}
+</style>
+
+<script>
+var period, frequency, dutyCycle;
+
+// Update the graph and the LED animation.
+function updateView() {
+  if (frequency === undefined)
+    return; // updateSpeed not yet called
+
+  // Update the graph.
+  let graphTop = 1.5;
+  let graphBottom = 27.5;
+  let graphStart = 1.5;
+  let graphEnd = 301.5;
+  let width = graphEnd - graphStart
+  let widthTime = 1; // 1s
+  let path;
+  if (dutyCycle == 0) {
+    // Duty cycle is 0%, draw a straight line at the bottom.
+    path = 'M ' + graphStart + ' ' + graphBottom + ' H ' + graphEnd;
+  } else if (dutyCycle == 1) {
+    // Duty cycle is 100%, draw a straight line at the top.
+    path = 'M ' + graphStart + ' ' + graphTop + ' H ' + graphEnd;
+  } else {
+    // Duty cycle is somewhere in between, draw a line starting at the start of
+    // a pulse.
+    path = 'M ' + graphStart + ' ' + graphBottom;
+    for (let t=0; t<widthTime; t+=period) {
+      let pulseStart = graphStart + t*width;
+      path += ' H ' + pulseStart + ' V ' + graphTop;
+      let pulseEnd = graphStart + (t+period*dutyCycle)*width;
+      if (pulseEnd > graphEnd) {
+        // End of the graph, don't move the line back.
+        continue;
+      }
+      if (dutyCycle >= 1) {
+        continue;
+      }
+      path += ' H ' + pulseEnd + ' V ' + graphBottom;
+    }
+  }
+  path += ' H ' + graphEnd;
+  document.querySelector('#pwm-path').setAttribute('d', path);
+
+  // Update the LED animation CSS.
+  let animation;
+  let style;
+  for (let rule of document.querySelector('#pwm-styles').sheet.cssRules) {
+    if (rule.type == CSSRule.KEYFRAMES_RULE && rule.name == 'pwm') {
+      animation = rule;
+    } else if (rule.type == CSSRule.STYLE_RULE && rule.selectorText == '#pwm-led') {
+      style = rule;
+    }
+  }
+  if (dutyCycle == 1) {
+    style.style.animationName = '';
+    style.style.fill = 'red';
+  } else if (dutyCycle == 0) {
+    style.style.animationName = '';
+    style.style.fill = 'transparent';
+  } else if (period < 0.035) {
+    // Speed is too high for most monitors/browsers to display properly.
+    // This is a bit cheating, but there is no other way to make it show what
+    // it is intended to show.
+    style.style.animationName = '';
+    style.style.fill = 'rgba(255, 0, 0, ' + dutyCycle + ')';
+  } else {
+    let delayPercent = (frequency/50) * 100; // soften transition in 20ms
+    animation.cssRules[1].keyText = delayPercent + '%';
+    animation.cssRules[2].keyText = (dutyCycle*100) + '%';
+    animation.cssRules[3].keyText = (dutyCycle*100 + delayPercent) + '%';
+    style.style.animationName = 'pwm';
+    style.style.animationDuration = period + 's';
+  }
+}
+
+// Called when the duty cycle slider is changed.
+function updateDutyCycle() {
+  let input = document.querySelector('#pwm-dutycycle-input');
+  dutyCycle = input.value / 100;
+  document.querySelector('#pwm-dutycycle').textContent = input.value + '%';
+  updateView();
+}
+
+// Called when the speed slider is changed.
+function updateSpeed() {
+  let input = document.querySelector('#pwm-period-input');
+  period = Math.pow(10, (30-input.value) / 10) / 1000;
+  frequency = 1 / period;
+  let periodString = (period * 1000).toFixed(0)+'ms';
+  if (period < 0.01) {
+    periodString = (period * 1e3).toFixed(1)+'ms';
+  }
+  if (period < 0.001) {
+    periodString = (period * 1e6).toFixed(0)+'µs';
+  }
+  document.querySelector('#pwm-period').textContent = periodString;
+  let frequencyString = frequency.toFixed(0) + 'Hz';
+  document.querySelector('#pwm-frequency').textContent = frequencyString;
+  updateView();
+}
+
+// Listen to slider changes.
+document.querySelector('#pwm-dutycycle-input').addEventListener('input', updateDutyCycle);
+document.querySelector('#pwm-period-input').addEventListener('input', updateSpeed);
+
+// Make sure the graph and LED are initialized properly.
+updateDutyCycle();
+updateSpeed();
+</script>
+
+## How does a PWM peripheral work?
+
+In most cases, a PWM is a combination of a counter that counts up or down and a few channels with a value that this counter is continuously compared against.