DC throttle with momentum on an Arduino Uno

// DC throttle with momentum: a knob, a direction switch, a brake and a TB6612.
//
//   A0       the throttle knob (its ends on 5 V and GND)
//   pin 2    direction switch (to GND for reverse, internal pull-up)
//   pin 3    brake button (to GND, internal pull-up)
//   pin 9    PWM into the TB6612's PWMA     pins 7 and 8: AIN1 and AIN2
//
// This is how a DC layout runs a train: the speed is the average voltage on the
// rails, and PWM sets that average by switching the full supply on and off.
// What makes it feel like a train is momentum. A heavy train does not jump to
// the speed the knob asks for; it eases up to it at ACCEL per step and slows at
// DECEL, so a quick twist of the knob still gives a gentle start. The brake
// button slows much harder, and the direction switch is only obeyed at a
// standstill: flip it at speed and the train coasts down, stops, then reverses,
// as an engineer would make it.
//
// DCC works differently. The rails carry constant power as a square wave that
// also carries digital packets, and a decoder inside each locomotive does the
// PWM and the momentum itself (its CV3 and CV4 set acceleration and braking).
// Mokxi does not simulate DCC; this sketch is the DC way, and the momentum logic
// is the same idea a decoder runs.
//
// The supply here is 12 V, like most HO and N scale DC power packs. On a real
// layout fit a fuse or a current limit: a derailed wheel across both rails is a
// dead short.

const int KNOB_PIN = A0;
const int REVERSE_PIN = 2;
const int BRAKE_PIN = 3;
const int PWM_PIN = 9;
const int AIN1 = 7;
const int AIN2 = 8;

const int ACCEL = 2;       // speed steps gained per 20 ms tick, out of 255
const int DECEL = 3;       // lost when the knob is turned down
const int BRAKE = 12;      // lost per tick with the brake held
const int START_AT = 30;   // below this a typical motor only hums, so treat it as stopped

int speed = 0;             // what the motor gets now, 0 to 255
bool reverse = false;      // the direction the motor is turning (or will turn)
unsigned long lastTick = 0;
int lastReported = -1;

void drive() {
  digitalWrite(AIN1, reverse ? LOW : HIGH);
  digitalWrite(AIN2, reverse ? HIGH : LOW);
  analogWrite(PWM_PIN, speed);
}

void setup() {
  Serial.begin(9600);
  pinMode(REVERSE_PIN, INPUT_PULLUP);
  pinMode(BRAKE_PIN, INPUT_PULLUP);
  pinMode(AIN1, OUTPUT);
  pinMode(AIN2, OUTPUT);
  reverse = digitalRead(REVERSE_PIN) == LOW;
  drive();
  Serial.println("DC throttle ready: turn the knob");
}

void loop() {
  unsigned long now = millis();
  if (now - lastTick < 20) return;
  lastTick = now;

  int asked = map(analogRead(KNOB_PIN), 0, 1023, 0, 255);
  if (asked < START_AT) asked = 0;
  bool wantReverse = digitalRead(REVERSE_PIN) == LOW;
  bool braking = digitalRead(BRAKE_PIN) == LOW;

  // A change of direction waits for a standstill: aim for zero until then.
  if (wantReverse != reverse) {
    if (speed == 0) {
      reverse = wantReverse;
      Serial.println(reverse ? "reverse" : "forward");
    } else {
      asked = 0;
    }
  }
  if (braking) asked = 0;

  if (speed < asked) speed = min(speed + ACCEL, asked);
  else if (speed > asked) speed = max(speed - (braking ? BRAKE : DECEL), asked);
  drive();

  int percent = speed * 100 / 255;
  if (percent / 5 != lastReported / 5 || (speed == 0 && lastReported != 0)) {
    lastReported = percent;
    Serial.print(reverse ? "reverse " : "forward ");
    Serial.print(percent);
    Serial.println(braking ? "%  braking" : "%");
  }
}