WIP

04-adc/README.md

@@ -4,7 +4,7 @@
 
 This project lets you control a couple of LEDs with a potentiometer and a capacitive touch sensor, while reading out the values of the Analog to Digital Converter (ADC) from the potentiometer.
 
-The breadboard diagram there is cursed. I diagrammed it exactly as I wired it. It looked a LOT less ugly in reality.
+The wire coming off pin 14 in the breadboard is just a bare wire hanging off the side for capacitive touch sensing.
 
 ## Lessons Learned
 
@@ -44,22 +44,33 @@ One of the simplest ADCs to implement is called a Flash ADC, and that one is sim
 
 ## How the ESP32-S3 ADC works
 
+I really wanted to understand how the ESP32-S3 in particular accomplishes this. So I went through a deep dive of the reference manual, plus some googling, plus some GPT interpretation of the TRM, and figured some things out. 
+
+![hold on to your butts](holdontoyourbutts.gif)
+
 The ESP32-S3 has two ADCs on the package that both perform in the same fashion. Per the technical reference manual
 
 > Two 12-bit Successive Approximation ADCs (SAR ADCs) controlled by five dedicated controllers that can input analog signals from total of 20 channels. The SAR ADCs can operate in a high-performance mode or a low-power mode.
 
 ![ESP32-S3 SAR ADC diagram](esp32sdcadc.png)
 
-The Successive Approximation ADCs are independent circuits that work similar to a binary search algorithm, searching for the digital value that corresponds to the voltage measurement within the maximum range. Basically the ADCs say:
+There are two ADCs on the ESP32-S3, being ADC1 and ADC2. They can both be operated in a low power mode (by driving them with the real-time clock controller) or in a high power mode (using the digital controller). ADC2 is shared among many peripherals such as WiFi, and so it has an "arbiter" hardware component that controls who gets to use it at which times and which controller drives it. ADC1 appears to be dedicated to userland programs running on the CPU, so it does not have a separate hardware arbiter, but you can select which driver to use by controlling a hardware register.
 
-1. Is the voltage over 1.6v?
+### ADC hardware registers
-2. If so, is it over 2.4v?
-3. If not, is it over 2.0?
-4. If so, is it over 2.2?
 
-.... and it keeps doing this, walking down into smaller and smaller slices of the maximum possible value, until it figures out where the right value is. It does this independently of the CPU; it cooperates with the ULP coprocessor (an ultra low power coprocessor that still runs when the CPU is in deep sleep mode). The ULP triggers the SAR ADC measurements and reads the results, and it has a whole separate set of real time clocks, timers, registers etc to manage the peripherals and their associated interrupts. Honestly the ULP is a fascinating little device in itself, capable of acting in either FSM or RISC-V modes depending on how it's programmed. 
+The ADC hardware registers are mapped into memory between `0x6000_8000` and `0x6000_8FFF`. These memory addresses are memory mapped in from the low power mode peripherals in the address controller. Basically, when something requests data from those memory regions, the memory address controller redirects the request out to the appropriate peripheral. The peripheral in question then manages the requested item, which is usually stored in a hardware register inside the peripheral. The ADC registers that are of most interest to this particular explanation are:
 
-[The technical reference manual](https://documentation.espressif.com/esp32-s3_technical_reference_manual_en.pdf) for the ULP is 35 pages, and the ADCs themselves get another 11 pages. Knock yourself out.
+| ADC | Register | Address | Purpose |
+|-----|----------|---------|---------|
+| ADC1|`SENS_SAR_MEAS1_MUX_REG`|`0x6000_8010`| Selecting the RTC or Digital controller for ADC1 operations|
+| ADC1|`SENS_SAR_MEAS1_CTRL2_REG`|`0x6000_800C`| Activating ADC1 and reading the output of the operation|
+| ADC1|`SENS_SAR_READER1_CTRL_REG`|`0x6000_8000`| Controlling ADC1 data and sampling|
+| ADC1|`SENS_SAR_ATTEN1_REG`|`0x6000_8014`| Setting the attenuation for ADC1|
+| ADC2|`SENS_SAR_MEAS2_MUX_REG`|`0x6000_8024`| Selecting the RTC or Digital controller for ADC1 operations|
+| ADC2|`SENS_SAR_MEAS2_CTRL2_REG`|`0x6000_8030`| Activating ADC1 and reading the output of the operation|
+| ADC2|`SENS_SAR_READER2_CTRL_REG`|`0x6000_8034`| Controlling ADC1 data and sampling|
+| ADC2|`SENS_SAR_ATTEN2_REG`|`0x6000_8038`| Setting the attenuation for ADC1|
+| Both|`SENS_SAR_POWER_XPD_SAR_REG`|`0x6000_803C`| SAR ADC Power Control|
 
 ## Measuring Capacitance