The Sense Amplifier

// Sense-amplifier sequencer and sensitivity sweep.
// Board: ESP32 DevKit v1. Drives the discrete latch built in step 2.
//
// The sense amplifier is a TIMING device as much as a circuit. Doing this by hand with
// switches cannot produce the microsecond-scale sequence it needs, and cannot repeat it
// the hundreds of times required to measure an error RATE rather than an anecdote.
//
// SEQUENCE, and the order is the whole thing:
//   1. EQ + PRECHARGE  - force both bit lines to exactly VDD/2, shorted together
//   2. release both    - the nodes now float at the unstable point of the latch
//   3. CELL dump       - share a small charge onto ONE node (this is the signal)
//   4. wait t_dev      - let the difference develop
//   5. FIRE SAP + SAN  - power the latch; it falls toward whichever side is higher
//   6. read the result, compare with what was written, count errors
//
// WIRING
//   GPIO 25  EQ         - shorts BL to BL_BAR (equalise)
//   GPIO 26  PRECHARGE  - connects both to VDD/2
//   GPIO 27  CELL       - dumps the cell capacitor onto BL
//   GPIO 14  CELL_SET   - charges the cell capacitor to the level under test
//   GPIO 12  FIRE       - drives SAP high and SAN low together
//   GPIO 34  READ_BL    - ADC1, reads BL after the latch has settled

#define EQ_PIN        25
#define PRECHARGE_PIN 26
#define CELL_PIN      27
#define CELL_SET_PIN  14
#define FIRE_PIN      12
#define READ_PIN      34

#define VREF     3.30f
#define ADC_MAX  4095.0f
#define TRIALS   40

void precharge() {
  digitalWrite(FIRE_PIN, LOW);          // latch unpowered - nodes may float
  digitalWrite(EQ_PIN, HIGH);           // short the pair together
  digitalWrite(PRECHARGE_PIN, HIGH);    // pull both to VDD/2
  delayMicroseconds(400);               // generous: the bit line caps are large
  digitalWrite(PRECHARGE_PIN, LOW);
  digitalWrite(EQ_PIN, LOW);            // both now FLOAT at the unstable point
  delayMicroseconds(20);
}

// dutyPct sets how hard the cell capacitor is charged, i.e. the signal size.
void chargeCell(int dutyPct) {
  ledcWrite(0, (dutyPct * 255) / 100);
  delayMicroseconds(300);
}

bool senseOnce(int dutyPct, int t_dev_us) {
  precharge();
  chargeCell(dutyPct);
  digitalWrite(CELL_PIN, HIGH);         // share the cell charge onto BL
  delayMicroseconds(30);
  digitalWrite(CELL_PIN, LOW);

  delayMicroseconds(t_dev_us);          // let the difference develop

  digitalWrite(FIRE_PIN, HIGH);         // power the latch - it decides now
  delayMicroseconds(200);

  int raw = analogRead(READ_PIN);
  digitalWrite(FIRE_PIN, LOW);
  return raw > (int)(ADC_MAX * 0.5f);   // did it land high?
}

void setup() {
  Serial.begin(115200);
  for (int p : {EQ_PIN, PRECHARGE_PIN, CELL_PIN, FIRE_PIN}) {
    pinMode(p, OUTPUT); digitalWrite(p, LOW);
  }
  analogSetPinAttenuation(READ_PIN, ADC_11db);
  ledcSetup(0, 20000, 8);
  ledcAttachPin(CELL_SET_PIN, 0);

  // ---- SWEEP 1: signal size, with a generous development time ----
  Serial.println("# sensitivity vs signal size (t_dev = 200 us)");
  Serial.println("duty_pct,trials,correct,error_rate");
  for (int duty = 2; duty <= 40; duty += 2) {
    int correct = 0;
    for (int i = 0; i < TRIALS; i++) if (senseOnce(duty, 200)) correct++;
    Serial.printf("%d,%d,%d,%.3f\n", duty, TRIALS, correct, 1.0f - (float)correct / TRIALS);
  }

  // ---- SWEEP 2: development time, at a signal that worked above ----
  Serial.println("# sensitivity vs development time (duty = 20%)");
  Serial.println("t_dev_us,trials,correct,error_rate");
  for (int t : {0, 1, 2, 5, 10, 20, 50, 100, 200, 500}) {
    int correct = 0;
    for (int i = 0; i < TRIALS; i++) if (senseOnce(20, t)) correct++;
    Serial.printf("%d,%d,%d,%.3f\n", t, TRIALS, correct, 1.0f - (float)correct / TRIALS);
  }

  Serial.println("# DONE - plot both sweeps in the jupyter step.");
  Serial.println("# Expect an S-curve, not a threshold. The width of the transition");
  Serial.println("# region IS your latch's offset and noise, measured rather than assumed.");
  Serial.println("# And note: at EVERY point above, the latch output is a clean full-swing");
  Serial.println("# logic level. It is never uncertain, only wrong.");
}

void loop() { }