training/explanation-what-is-pwm.md

+# Tutorial: Controlling the Robot (Pulse Width Modulation)
+
+Written by Alexander Yelovich.
+
+Status: In progress
+
+[[_TOC_]]
+
+# Introduction
+
+In this tutorial we will go into what Pulse-Width Modulation (PWM) is, why
+we need to use PWM to move the robot, and how we can code it up.
+
+# What is Pulse-Width Modulation?
+
+At a high level, Pulse-Width Modulation (PWM) is a method of transmitting
+data through raw voltage signals. Graphically, we can picture a line segment split
+into equal portions. For each portion, there is some part that is "off", or low
+voltage, followed by some amount that is "on", or high voltage, with the
+rest of that portion filled in with low voltage. What follows is a quick
+explanation of some vocabulary/parameters that you might encounter when working
+with PWM.
+
+## Frequency
+
+This dictates how "long" each portion is. A very common setting for this
+(including what we have set on Qubo) is 200 Hz. This means that for each
+second, we will have 200 equally sized portions.
+
+## Duty Cycle
+
+This is a percentage that indictes how long the high voltage is set per portion.
+This setting is crucial for PWM because it is the core of the data. Depending
+on the device, some percentages might mean different things. 50% could
+indicate a particular amount of thrust to output for a thruster, or it could be
+a position for a servo to move to, or it could be a color for an LED. When
+writing an API for PWM, it is crucial to provide a function that writes a
+particular percentage, so that the time comes to write code for each individual
+device, it is relatively straightforward to decide how to translate a
+particular state to a duty cycle.
+
+## Offset/Phase Shift
+
+Going purely off frequency and phase shift, we are limited in that we can only
+define a high voltage that starts at the start of the portion. In order to
+have full freedom/control, we have a phase shift that simply specifies what
+percentage of the portion to have low from the start, followed by the high
+portion, with the final low portion filling in the rest.
+
+## Average Voltage
+
+Consider the scenario when there is a 100% duty cycle. That is simply a constant
+voltage (it is just an electrical signal transferring over a wire). So the
+average voltage to be the duty cycle multiplied by the aforementioned constant
+voltage. For example, if a 100% duty cycle is 5 V, then a 30% duty cycle would
+be 1.5 V (30% of 5).
+
+# PWM Graphical Example
+
+Consider this image from [Wikipedia](https://en.wikipedia.org/wiki/Pulse-width_modulation)
+as an example:
+
+![Example PWM Image](../uploads/training/pwm.png)
+
+# Electronic Speed Control (ESC)
+
+Motors in general (including the thrusters in use on both Qubo and the
+catamaran) do not have the functionality to interpret a raw PWM signal and
+translate it to something useful. To remedy this, we use Electronic Speed
+Controllers (ESCs). The ones that we use comprise of a simple microcontroller
+that for our purposes is a black box (we send data in, and get data out, and
+do not care about what happens in between). For example, our ESCs use
+1500 microseconds to indicate zero thrust, with slightly beyond 1500 to
+indicate positive thrust, and slightly below to indicate negative thrust.