Termi3 - The Question-Answering Typewriter Is Back

/*
 *  """
 *  Termi3 - Python Script
 *  Cameron Coward
 *  cameroncoward.com
 *  9/24/2026
 *  """
 *
 *   1. Print "ASK TERMI3: "                (bit-bang TX)
 *   2. Read keystrokes until CR            (bit-bang RX -> line buffer)
 *   3. Bridge.call("ask", question)        (blocks for the answer)
 *   4. Print "TERMI3: " + answer           (bit-bang TX)
 *   5. Loop
 *
 * serial config (Phase 3): A0=TX, A1=RX, 300 baud (BIT_US=3333),
 * 7 data bits, odd parity, 1 stop, TX_INVERT=false / RX idle HIGH.
 * Terminal switches: HIGH SPEED, HALF DUPLEX, ON LINE.
 */

#include <Arduino_RouterBridge.h>
#include <Arduino_LED_Matrix.h>

// ---------------- Status LED matrix (UNO Q, 8x13) ----------------
// Three status icons show where the loop is, set once at each boundary
// (never refreshed in loop()). The firmware refresh IRQ keeps the frame lit.
// NOTE: that refresh IRQ runs during bit-bang serial. If it ever jitters the
// 3.3ms/bit timing (corrupt chars), matrix.end() disables it as a fallback.
Arduino_LED_Matrix matrix;

// 8 rows x 13 cols, row-major, 1 = LED on. setGrayscaleBits(1) -> on/off.

// "?"  waiting for a question
const uint8_t ICON_WAIT[104] = {
  0,0,0,0,1,1,1,1,1,0,0,0,0,
  0,0,0,1,1,0,0,0,1,1,0,0,0,
  0,0,0,0,0,0,0,0,1,1,0,0,0,
  0,0,0,0,0,0,0,1,1,0,0,0,0,
  0,0,0,0,0,0,1,1,0,0,0,0,0,
  0,0,0,0,0,0,1,1,0,0,0,0,0,
  0,0,0,0,0,0,0,0,0,0,0,0,0,
  0,0,0,0,0,0,1,1,0,0,0,0,0
};

// hourglass  processing (waiting on the LLM answer)
const uint8_t ICON_PROC[104] = {
  0,0,0,1,1,1,1,1,1,1,0,0,0,
  0,0,0,0,1,1,1,1,1,0,0,0,0,
  0,0,0,0,0,1,1,1,0,0,0,0,0,
  0,0,0,0,0,0,1,0,0,0,0,0,0,
  0,0,0,0,0,0,1,0,0,0,0,0,0,
  0,0,0,0,0,1,1,1,0,0,0,0,0,
  0,0,0,0,1,1,1,1,1,0,0,0,0,
  0,0,0,1,1,1,1,1,1,1,0,0,0
};

// speaker  responding (printing the answer)
const uint8_t ICON_RESP[104] = {
  0,0,0,0,0,1,0,0,0,0,0,0,0,
  0,0,0,0,1,1,0,0,1,0,0,0,0,
  0,0,1,1,1,1,0,1,0,1,0,0,0,
  0,0,1,1,1,1,0,1,0,1,0,1,0,
  0,0,1,1,1,1,0,1,0,1,0,1,0,
  0,0,1,1,1,1,0,1,0,1,0,0,0,
  0,0,0,0,1,1,0,0,1,0,0,0,0,
  0,0,0,0,0,1,0,0,0,0,0,0,0
};

// A0/A1 (STM32U585 PA4/PA5, aliased D14/D15) are full digital GPIO  the
// bit-bang is pure polled digitalRead/Write, so no pin-specific peripheral is
// needed. NOTE: A0/A1 are NOT 5V tolerant; the MAX3232 runs at 3.3V so R1OUT
// swings 0-3.3V. Keep the 5V connect-detect line (DA-15 pin 11) away from them.
const int PIN_TX = A0;
const int PIN_RX = A1;
const int BIT_US = 3333;
const int HALF_BIT_US = 1666;
const bool TX_INVERT = false;
const bool RX_IDLE_HIGH = true;

const int  MAX_Q = 200;         // max question length

// ---------------- TX (confirmed) ----------------
inline void txBit(bool level) {
  digitalWrite(PIN_TX, TX_INVERT ? !level : level);
}
void sendChar(char c) {
  uint8_t data = (uint8_t)c & 0x7F;
  txBit(false); delayMicroseconds(BIT_US);           // start
  uint8_t ones = 0;
  for (int i = 0; i < 7; i++) {
    bool b = (data >> i) & 0x01; if (b) ones++;
    txBit(b); delayMicroseconds(BIT_US);
  }
  txBit(ones % 2 == 0); delayMicroseconds(BIT_US);   // odd parity
  txBit(true); delayMicroseconds(BIT_US);            // stop
}
void sendString(const char *s) { while (*s) sendChar(*s++); }
void sendString(const String &s) {
  for (unsigned i = 0; i < s.length(); i++) sendChar(s[i]);
}
void newline() { sendChar('\r'); sendChar('\n'); }
// Advance the paper n lines (CR+LF each  bare CR would not feed the paper).
void feedLines(int n) { while (n-- > 0) newline(); }

// ---------------- RX (confirmed) ----------------
inline bool rxLevel() {
  bool high = (digitalRead(PIN_RX) == HIGH);
  return RX_IDLE_HIGH ? high : !high;
}
// Blocking read of one char. Returns -1 on framing glitch.
int receiveChar() {
  while (rxLevel() == true) { /* idle */ }
  delayMicroseconds(HALF_BIT_US);
  if (rxLevel() != false) return -1;                 // false start
  delayMicroseconds(BIT_US);
  uint8_t data = 0;
  for (int i = 0; i < 7; i++) {
    if (rxLevel()) data |= (1 << i);
    delayMicroseconds(BIT_US);
  }
  delayMicroseconds(BIT_US);   // past parity
  return data & 0x7F;
}

// Read a full line until CR (0x0D) or LF, into buf. Returns length.
// Uppercases letters (terminal is uppercase anyway; keeps things clean).
int readLine(char *buf, int maxlen) {
  int n = 0;
  for (;;) {
    int c = receiveChar();
    if (c < 0) continue;                 // ignore framing glitches
    if (c == '\r' || c == '\n') break;   // end of question
    if (c == 8 || c == 127) {            // backspace/delete
      if (n > 0) n--;
      continue;
    }
    if (n < maxlen - 1 && c >= 32) {     // printable
      buf[n++] = (char)c;
    }
  }
  buf[n] = '\0';
  return n;
}

// ---------------- App flow ----------------
char question[MAX_Q];

void printPrompt() {
  newline();
  sendString("ASK TERMI3: ");
}

void setup() {
  pinMode(PIN_TX, OUTPUT);
  txBit(true);                 // idle mark
  pinMode(PIN_RX, INPUT);

  matrix.begin();              // starts firmware refresh IRQ
  matrix.setGrayscaleBits(1);  // 1 bit -> on/off
  matrix.draw(ICON_PROC);      // "processing" while warming up

  Bridge.begin();              // ~2s, blocking
  Monitor.begin(115200);       // debug to App Lab console

  // Wait until the Python side AND the local LLM are ready. is_ready() only
  // returns true once llama-server answers /health, so on a cold boot this
  // loop waits out the model-load time. Wait indefinitely (conference: the
  // board is powered on and must self-heal, never give up).
  bool ready = false;
  unsigned long lastDot = 0;
  while (!ready) {
    Bridge.call("is_ready").result(ready);
    if (!ready) {
      // Print a slow row of dots so the paper shows it's warming up, not dead.
      unsigned long now = millis();
      if (now - lastDot > 3000) { sendChar('.'); lastDot = now; }
      delay(200);
    }
  }

  delay(300);
  newline();
  // Startup banner (branded prompt, per on-paper interaction design).
  sendString("TERMI3 - A TYPEWRITER THAT THINKS");
  newline();

  matrix.draw(ICON_WAIT);      // ready, waiting for a question
}

void loop() {
  matrix.draw(ICON_WAIT);                // waiting for a question
  printPrompt();

  int len = readLine(question, MAX_Q);
  if (len == 0) return;                  // empty line -> re-prompt

  matrix.draw(ICON_PROC);                // CR received -> processing

  // Roll the paper up so the user can read back what they just typed.
  feedLines(4);

  // Static "thinking" marker. Printed BEFORE the blocking Bridge call, so it
  // appears the moment the question is accepted. This is an ACKNOWLEDGEMENT,
  // not a progress bar: at the conference many users couldn't tell whether
  // their question had been received. A timed/animated indicator isn't
  // possible here anyway  Bridge.call().result() blocks, so loop() gets no
  // chance to print while waiting (see project memory: no concurrency, to
  // protect bit-bang timing).
  sendString("...");

  // Ask Python (which queries the local LLM). Blocks for the answer.
  // NOTE: using the plain .result() form (confirmed by docs). Timeout is
  // handled Python-side (urllib 30s). If the default Bridge timeout proves
  // too short for a cold first answer, we'll add MCU-side timeout config.
  String answer;
  bool ok = Bridge.call("ask", String(question)).result(answer);

  feedLines(2);                          // separate the marker from the answer

  matrix.draw(ICON_RESP);                // answer in hand -> responding
  sendString("TERMI3: ");
  if (ok && answer.length() > 0) {
    sendString(answer);
  } else {
    sendString("SORRY, NO ANSWER.");
  }

  feedLines(4);                          // leave the answer visible above the platen
}