SimRacing.cpp

Go to the documentation of this file.

/*
 *  Project     Sim Racing Library for Arduino
 *  @author     David Madison
 *  @link       github.com/dmadison/Sim-Racing-Arduino
 *  @license    LGPLv3 - Copyright (c) 2022 David Madison
 *
 *  This file is part of the Sim Racing Library for Arduino.
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
#include "SimRacing.h"
 
namespace SimRacing {
 
#if defined(__AVR_ATmega32U4__) || defined(SIM_RACING_DOXYGEN)
 
template<>
LogitechPedals CreateShieldObject<LogitechPedals, 1>() {
    //  Power (VCC): DE-9 pin 9, bridged to DE-9 pin 6
    // Ground (GND): DE-9 pin 1
 
    const PinNum Pin_Gas    = A2;  // DE-9 pin 2
    const PinNum Pin_Brake  = A1;  // DE-9 pin 3
    const PinNum Pin_Clutch = A0;  // DE-9 pin 4
    const PinNum Pin_Detect = 10;  // DE-9 pin 6, requires 10k Ohm pull-down
 
    return LogitechPedals(Pin_Gas, Pin_Brake, Pin_Clutch, Pin_Detect);
}
 
template<>
LogitechPedals CreateShieldObject<LogitechPedals, 2>() {
    // version 2 of the pedals shield has the same pinout,
    // so we can use the v1 function
    return CreateShieldObject<LogitechPedals, 1>();
}
 
template<>
LogitechShifter CreateShieldObject<LogitechShifter, 1>() {
    //  Power (VCC): DE-9 pin 9, bridged to DE-9 pin 7
    // Ground (GND): DE-9 pin 6
    // DE-9 pin 3 (CS) needs to be pulled-up to VCC
 
    const PinNum Pin_X_Wiper = A1;  // DE-9 pin 4
    const PinNum Pin_Y_Wiper = A0;  // DE-9 pin 8
    const PinNum Pin_DataOut = 14;  // DE-9 pin 2
    const PinNum Pin_Detect  = A2;  // DE-9 pin 7, requires 10k Ohm pull-down
 
    return LogitechShifter(Pin_X_Wiper, Pin_Y_Wiper, Pin_DataOut, Pin_Detect);
}
 
template<>
LogitechShifter CreateShieldObject<LogitechShifter, 2>() {
    // version 2 of the shifter shield has the same data pinout for
    // the Driving Force shifter, so we can use the v1 function
    return CreateShieldObject<LogitechShifter, 1>();
}
 
template<>
LogitechShifterG27 CreateShieldObject<LogitechShifterG27, 2>() {
    //  Power (VCC): DE-9 pin 9, bridged to DE-9 pin 7
    // Ground (GND): DE-9 pin 6
 
    const PinNum Pin_X_Wiper  = A1;  // DE-9 pin 4
    const PinNum Pin_Y_Wiper  = A0;  // DE-9 pin 8
    const PinNum Pin_DataOut  = 14;  // DE-9 pin 2
 
    const PinNum Pin_Latch    = 10;  // DE-9 pin 3, aka chip select, requires 10k Ohm pull-up
    const PinNum Pin_Clock    = 15;  // DE-9 pin 1, should have 470 Ohm resistor to prevent shorts
 
    const PinNum Pin_LED      = 16;  // DE-9 pin 5, has a 100-120 Ohm series resistor
    const PinNum Pin_Detect   = A2;  // DE-9 pin 7, requires 10k Ohm pull-down
 
    return LogitechShifterG27(Pin_X_Wiper, Pin_Y_Wiper, Pin_Latch, Pin_Clock, Pin_DataOut, Pin_LED, Pin_Detect);
}
 
template<>
LogitechShifterG25 CreateShieldObject<LogitechShifterG25, 2>() {
    //  Power (VCC): DE-9 pin 9, bridged to DE-9 pin 1
    // Ground (GND): DE-9 pin 6
 
    const PinNum Pin_X_Wiper  = A1;  // DE-9 pin 4
    const PinNum Pin_Y_Wiper  = A0;  // DE-9 pin 8
    const PinNum Pin_DataOut  = 14;  // DE-9 pin 2
 
    const PinNum Pin_Latch    = 10;  // DE-9 pin 3, aka chip select, requires 10k Ohm pull-up
    const PinNum Pin_Clock    = A2;  // DE-9 pin 7, should have 470 Ohm resistor to prevent shorts
 
    const PinNum Pin_LED      = 16;  // DE-9 pin 5, has a 100-120 Ohm series resistor
    const PinNum Pin_Detect   = 15;  // DE-9 pin 1, requires 10k Ohm pull-down
 
    return LogitechShifterG25(Pin_X_Wiper, Pin_Y_Wiper, Pin_Latch, Pin_Clock, Pin_DataOut, Pin_LED, Pin_Detect);
}
#endif  // ATmega32U4 for shield functions
 
 
static constexpr PinNum sanitizePin(PinNum pin) {
    return pin < 0 ? UnusedPin : pin;
}
 
 
static constexpr long invertAxis(long value, long min, long max) {
    return max - value + min;  // flip to other side of the scale
}
 
 
static long remap(long value, long inMin, long inMax, long outMin, long outMax) {
    // if inverted, swap min/max and adjust position of value
    if (inMin > inMax) {
        const long temp = inMin;
        inMin = inMax;
        inMax = temp;
 
        value = invertAxis(value, inMin, inMax);
    }
 
    if (value <= inMin) return outMin;
    if (value >= inMax) return outMax;
    return map(value, inMin, inMax, outMin, outMax);
}
 
 
static float floatPercent(float pct) {
    if (pct < 0.0) pct = 0.0;
    else if (pct > 1.0) pct = 1.0;
    return pct;
}
 
static void flushClient(Stream& client) {
    while (client.read() != -1) { delay(2); }  // 9600 baud = ~1 ms per byte
}
 
static void waitClient(Stream& client) {
    flushClient(client);
    while (client.peek() == -1) { delay(1); }  // wait for a new byte (using delay to avoid watchdog)
}
 
static void readFloat(float& value, Stream& client) {
    client.print("(to skip this step and go with the default value of '");
    client.print(value);
    client.print("', send 'n')");
    client.println();
 
    waitClient(client);
    if (client.peek() == 'n') return;  // skip this step
 
    float input;
 
    while (true) {
        client.setTimeout(200);
        input = client.parseFloat();
 
        if (input >= 0.0 && input <= 1.0) {
            client.print(F("Set the new value to '"));
            client.print(input);
            client.println("'");
            break;
        }
        client.print(F("Input '"));
        client.print(input);
        client.print(F("' not within acceptable range (0.0 - 1.0). Please try again."));
        client.println();
 
        waitClient(client);
    }
 
    value = input;
}
 
 
//#########################################################
//                  DeviceConnection                      #
//#########################################################
 
DeviceConnection::DeviceConnection(PinNum pin, bool activeLow, unsigned long detectTime)
    :
    pin(sanitizePin(pin)), inverted(activeLow), stablePeriod(detectTime),  // constants(ish)
 
    /* Assume we're connected on first call
    */
    state(ConnectionState::Connected),
 
    /* Init state to "not inverted", which is the connected state. For example
    * if we're looking for 'HIGH' then inverted is false, which means the
    * initial state is 'true' and thus connected.
    *
    * We're assuming we're connected on first call here because it allows
    * the device to be read as connected as soon as the board turns on, without
    * having to wait an arbitrary amount.
    */
    pinState(!inverted),
 
    /* Set the last pin change to right now minus the stable period so it's
    * read as being already stable. Again, this will make the class return
    * 'present' as soon as the board starts up
    */
    lastChange(millis() - detectTime)
 
{
    if (pin != UnusedPin) {
        pinMode(pin, INPUT);  // set pin as input, *no* pull-up
    }
}
 
void DeviceConnection::poll() {
    const bool newState = readPin();
 
    if (newState == HIGH && state == ConnectionState::Connected) return;  // short circuit, already connected
 
    // check if the pin changed. if it did, record the time
    if (pinState != newState) {
        pinState = newState;
        lastChange = millis();
 
        // rising, we just connected
        if (pinState == HIGH) {
            state = ConnectionState::PlugIn;
        }
        // falling, we just disconnected
        else {
            state = ConnectionState::Unplug;
        }
    }
 
    // if pin hasn't changed, compare stable times
    else {
        // check stable connection (over time)
        if (pinState == HIGH) {
            const unsigned long now = millis();
            if (now - lastChange >= stablePeriod) {
                state = ConnectionState::Connected;
            }
        }
        // if we were previously unplugged and are still low, now we're disconnected
        else if (state == ConnectionState::Unplug) {
            state = ConnectionState::Disconnected;
        }
    }
}
 
DeviceConnection::ConnectionState DeviceConnection::getState() const {
    return state;
}
 
bool DeviceConnection::isConnected() const {
    return this->getState() == ConnectionState::Connected;
}
 
void DeviceConnection::setStablePeriod(unsigned long t) {
    stablePeriod = t;
 
    if (state == ConnectionState::Connected) {
        const unsigned long now = millis();
 
        // if we were previously considered connected, adjust the timestamps
        // accordingly so that we still are
        if (now - lastChange < stablePeriod) {
            lastChange = now - stablePeriod;
        }
    }
}
 
bool DeviceConnection::readPin() const {
    if (pin == UnusedPin) return HIGH;  // if no pin is set, we're always connected
    const bool state = digitalRead(pin);
    return inverted ? !state : state;
}
 
//#########################################################
//                     AnalogInput                        #
//#########################################################
 
 
AnalogInput::AnalogInput(PinNum pin)
    : pin(sanitizePin(pin)), position(AnalogInput::Min), cal({AnalogInput::Min, AnalogInput::Max})
{
    if (pin != UnusedPin) {
        pinMode(pin, INPUT);
    }
}
 
bool AnalogInput::read() {
    bool changed = false;
 
    if (pin != UnusedPin) {
        const int previous = this->position;
        this->position = analogRead(pin);
 
        // check if value is different for 'changed' flag
        if (previous != this->position) {
 
            const int rMin = isInverted() ? getMax() : getMin();
            const int rMax = isInverted() ? getMin() : getMax();
 
            if (
                // if the previous value was under the minimum range
                // and the current value is as well, no change
                !(previous < rMin && this->position < rMin) && 
 
                // if the previous value was over the maximum range
                // and the current value is as well, no change
                !(previous > rMax && this->position > rMax)
            )
            {
                // otherwise, the current value is either within the
                // range limits *or* it has changed from one extreme
                // to the other. Either way, mark it changed!
                changed = true;
            }
        }
    }
    return changed;
}
 
long AnalogInput::getPosition(long rMin, long rMax) const {
    // inversion is handled within the remap function
    return remap(getPositionRaw(), getMin(), getMax(), rMin, rMax);
}
 
int AnalogInput::getPositionRaw() const {
    return this->position;
}
 
bool AnalogInput::isInverted() const {
    return (this->cal.min > this->cal.max);  // inverted if min is greater than max
}
 
void AnalogInput::setPosition(int newPos) {
    this->position = newPos;
}
 
void AnalogInput::setInverted(bool invert) {
    if (isInverted() == invert) return;  // inversion already set
 
    // to change inversion, swap max and min of the current calibration
    AnalogInput::Calibration inverted = { this->cal.max, this->cal.min };
    setCalibration(inverted);
}
 
void AnalogInput::setCalibration(AnalogInput::Calibration newCal) {
    this->cal = newCal;
}
 
//#########################################################
//                     Peripheral                         #
//#########################################################
 
bool Peripheral::update() {
    // if the detector exists, poll for state
    if (this->detector) {
        this->detector->poll();
    }
 
    // get the connected state from the detector
    const bool connected = this->isConnected();
 
    // call the derived class update function
    return this->updateState(connected);
}
 
bool Peripheral::isConnected() const {
    // if detector exists, return state
    if (this->detector) {
        return this->detector->isConnected();
    }
 
    // otherwise, assume always connected
    return true;
}
 
void Peripheral::setDetectPtr(DeviceConnection* d) {
    this->detector = d;
}
 
void Peripheral::setStablePeriod(unsigned long t) {
    // if detector exists, set the stable period
    if (this->detector) {
        this->detector->setStablePeriod(t);
    }
}
 
//#########################################################
//                       Pedals                           #
//#########################################################
 
Pedals::Pedals(AnalogInput* dataPtr, uint8_t nPedals)
    : 
    pedalData(dataPtr),
    NumPedals(nPedals),
    changed(false)
{}
 
void Pedals::begin() {
    update();  // set initial pedal position
}
 
bool Pedals::updateState(bool connected) {
    this->changed = false;
 
    // if we're connected, read all pedal positions
    if (connected) {
        for (int i = 0; i < getNumPedals(); ++i) {
            changed |= pedalData[i].read();
        }
    }
 
    // otherwise, zero all pedals
    else {
        for (int i = 0; i < getNumPedals(); ++i) {
            const int min = pedalData[i].getMin();
            const int prev = pedalData[i].getPositionRaw();
            if (min != prev) {
                pedalData[i].setPosition(min);
                changed = true;
            }
        }
    }
 
    return this->changed;
}
 
long Pedals::getPosition(PedalID pedal, long rMin, long rMax) const {
    if (!hasPedal(pedal)) return rMin;  // not a pedal
    return pedalData[pedal].getPosition(rMin, rMax);
}
 
int Pedals::getPositionRaw(PedalID pedal) const {
    if (!hasPedal(pedal)) return AnalogInput::Min;  // not a pedal
    return pedalData[pedal].getPositionRaw();
}
 
bool Pedals::hasPedal(PedalID pedal) const {
    return (pedal < getNumPedals());
}
 
void Pedals::setCalibration(PedalID pedal, AnalogInput::Calibration cal) {
    if (!hasPedal(pedal)) return;
    pedalData[pedal].setCalibration(cal);
    pedalData[pedal].setPosition(pedalData[pedal].getMin());  // reset to min position
}
 
String Pedals::getPedalName(PedalID pedal) {
    String name;
 
    switch (pedal) {
    case(PedalID::Gas):
        name = F("gas");
        break;
    case(PedalID::Brake):
        name = F("brake");
        break;
    case(PedalID::Clutch):
        name = F("clutch");
        break;
    default:
        name = F("???");
        break;
    }
    return name;
}
 
void Pedals::serialCalibration(Stream& iface) {
    const char* separator = "------------------------------------";
 
    iface.println();
    iface.println(F("Sim Racing Library Pedal Calibration"));
    iface.println(separator);
    iface.println();
 
    // read minimums
    iface.println(F("Take your feet off of the pedals so they move to their resting position."));
    iface.println(F("Send any character to continue."));
    waitClient(iface);
 
    const int MaxPedals = 3;  // hard-coded at 3 pedals
 
    AnalogInput::Calibration pedalCal[MaxPedals];
 
    // read minimums
    for (int i = 0; (i < getNumPedals()) && (i < MaxPedals); i++) {
        pedalData[i].read();  // read position
        pedalCal[i].min = pedalData[i].getPositionRaw();  // set min to the recorded position
    }
    iface.println(F("\nMinimum values for all pedals successfully recorded!\n"));
    iface.println(separator);
 
    // read maximums
    iface.println(F("\nOne at a time, let's measure the maximum range of each pedal.\n"));
    for (int i = 0; (i < getNumPedals()) && (i < MaxPedals); i++) {
 
        iface.print(F("Push the "));
        String name = getPedalName(static_cast<PedalID>(i));
        name.toLowerCase();
        iface.print(name);
        iface.print(F(" pedal to the floor. "));
 
        iface.println(F("Send any character to continue."));
        waitClient(iface);
 
        pedalData[i].read();  // read position
        pedalCal[i].max = pedalData[i].getPositionRaw();  // set max to the recorded position
    }
 
    // deadzone options
    iface.println(separator);
    iface.println();
 
    float DeadzoneMin = 0.01;  // by default, 1% (trying to keep things responsive)
    float DeadzoneMax = 0.025;  // by default, 2.5%
 
    iface.println(F("These settings are optional. Send 'y' to customize. Send any other character to continue with the default values."));
 
    iface.print(F("  * Pedal Travel Deadzone, Start: \t"));
    iface.print(DeadzoneMin);
    iface.println(F("  (Used to avoid the pedal always being slightly pressed)"));
 
    iface.print(F("  * Pedal Travel Deadzone, End:   \t"));
    iface.print(DeadzoneMax);
    iface.println(F("  (Used to guarantee that the pedal can be fully pressed)"));
 
    iface.println();
 
    waitClient(iface);
 
    if (iface.read() == 'y') {
        iface.println(F("Set the pedal travel starting deadzone as a floating point percentage."));
        readFloat(DeadzoneMin, iface);
        iface.println();
 
        iface.println(F("Set the pedal travel ending deadzone as a floating point percentage."));
        readFloat(DeadzoneMax, iface);
        iface.println();
    }
 
    flushClient(iface);
 
    // calculate deadzone offsets
    for (int i = 0; (i < getNumPedals()) && (i < MaxPedals); i++) {
        auto &cMin = pedalCal[i].min;
        auto &cMax = pedalCal[i].max;
 
        const int range = abs(cMax - cMin);
        const int dzMin = DeadzoneMin * (float)range;
        const int dzMax = DeadzoneMax * (float)range;
 
        // non-inverted
        if (cMax >= cMin) {
            cMax -= dzMax;  // 'cut' into the range so it limits sooner
            cMin += dzMin;
        }
        // inverted
        else {
            cMax += dzMax;
            cMin -= dzMin;
        }
    }
 
    // print finished calibration
    iface.println(F("Here is your calibration:"));
    iface.println(separator);
    iface.println();
 
    iface.print(F("pedals.setCalibration("));
 
    for (int i = 0; (i < getNumPedals()) && (i < MaxPedals); i++) {
        if(i > 0) iface.print(F(", "));
        iface.print('{');
 
        iface.print(pedalCal[i].min);
        iface.print(F(", "));
        iface.print(pedalCal[i].max);
 
        iface.print('}');
 
        this->setCalibration(static_cast<PedalID>(i), pedalCal[i]);  // and set it ourselves, too
    }
    iface.print(");");
    iface.println();
 
    iface.println();
    iface.println(separator);
    iface.println();
 
    iface.print(F("Paste this line into the setup() function. The "));
    iface.print(F("pedals"));
    iface.print(F(" will be calibrated with these values on startup."));
    iface.println(F("\nCalibration complete! :)\n\n"));
 
    flushClient(iface);
}
 
 
TwoPedals::TwoPedals(PinNum gasPin, PinNum brakePin)
    : Pedals(pedalData, NumPedals),
    pedalData{ AnalogInput(gasPin), AnalogInput(brakePin) }
{}
 
void TwoPedals::setCalibration(AnalogInput::Calibration gasCal, AnalogInput::Calibration brakeCal) {
    this->Pedals::setCalibration(PedalID::Gas, gasCal);
    this->Pedals::setCalibration(PedalID::Brake, brakeCal);
}
 
 
ThreePedals::ThreePedals(PinNum gasPin, PinNum brakePin, PinNum clutchPin)
    : Pedals(pedalData, NumPedals),
    pedalData{ AnalogInput(gasPin), AnalogInput(brakePin), AnalogInput(clutchPin) }
{}
 
void ThreePedals::setCalibration(AnalogInput::Calibration gasCal, AnalogInput::Calibration brakeCal, AnalogInput::Calibration clutchCal) {
    this->Pedals::setCalibration(PedalID::Gas, gasCal);
    this->Pedals::setCalibration(PedalID::Brake, brakeCal);
    this->Pedals::setCalibration(PedalID::Clutch, clutchCal);
}
 
 
LogitechPedals::LogitechPedals(PinNum gasPin, PinNum brakePin, PinNum clutchPin, PinNum detectPin)
    : 
    ThreePedals(gasPin, brakePin, clutchPin),
    detectObj(detectPin, false)  // active high
{
    this->setDetectPtr(&this->detectObj);
 
    // taken from calibrating my own pedals. the springs are pretty stiff so while
    // this covers the whole travel range, users may want to back it down for casual
    // use (esp. for the brake travel)
    this->setCalibration({ 904, 48 }, { 944, 286 }, { 881, 59 });
}
 
LogitechDrivingForceGT_Pedals::LogitechDrivingForceGT_Pedals(PinNum gasPin, PinNum brakePin, PinNum detectPin)
    : 
    TwoPedals(gasPin, brakePin),
    detectObj(detectPin, false)  // active high
{
    this->setDetectPtr(&this->detectObj);
    this->setCalibration({ 646, 0 }, { 473, 1023 });  // taken from calibrating my own pedals
}
 
 
//#########################################################
//                       Shifter                          #
//#########################################################
 
Shifter::Shifter(Gear min, Gear max)
    :
    MinGear(min), MaxGear(max)
{
    this->currentGear = this->previousGear = 0;  // neutral
}
 
void Shifter::setGear(Gear gear) {
    // if gear is out of range, set it to neutral
    if (gear < MinGear || gear > MaxGear) {
        gear = 0;
    }
 
    this->previousGear = this->currentGear;
    this->currentGear = gear;
}
 
char Shifter::getGearChar(int gear) {
    char c = '?';
 
    switch (gear) {
    case(-1):
        c = 'r';
        break;
    case(0):
        c = 'n';
        break;
    default:
        if (gear > 0 && gear <= 9)
            c = '0' + gear;
        break;
    }
    return c;
}
 
char Shifter::getGearChar() const {
    return getGearChar(getGear());
}
 
String Shifter::getGearString(int gear) {
    String name;
 
    switch (gear) {
    case(-1):
        name = F("reverse");
        break;
    case(0):
        name = F("neutral");
        break;
    default: {
        if (gear < 0 || gear > 9) {
            name = F("???");
            break;  // out of range
        }
        name = gear;  // set string to current gear
 
        switch (gear) {
        case(1):
            name += F("st");
            break;
        case(2):
            name += F("nd");
            break;
        case(3):
            name += F("rd");
            break;
        default:
            name += F("th");
            break;
        }
        break;
    }
    }
    return name;
}
 
String Shifter::getGearString() const {
    return getGearString(getGear());
}
 
 
/* Static calibration constants
* These values are arbitrary - just what worked well with my own shifter.
*/
const float AnalogShifter::CalEngagementPoint = 0.70;
const float AnalogShifter::CalReleasePoint = 0.50;
const float AnalogShifter::CalEdgeOffset = 0.60;
 
AnalogShifter::AnalogShifter(
    Gear gearMin, Gear gearMax,
    PinNum pinX, PinNum pinY, PinNum pinRev
) : 
    Shifter(gearMin, gearMax),
 
    /* Two axes, X and Y */
    analogAxis{ AnalogInput(pinX), AnalogInput(pinY) },
 
    pinReverse(sanitizePin(pinRev)),
    reverseState(false)
{}
 
void AnalogShifter::begin() {
    if (this->pinReverse != UnusedPin) {
        pinMode(pinReverse, INPUT);
    }
    update();  // set initial gear position
}
 
bool AnalogShifter::updateState(bool connected) {
    // if not connected, reset our position back to neutral
    // and immediately return
    if (!connected) {
        // set axis values to calibrated neutral
        analogAxis[Axis::X].setPosition(calibration.neutralX);
        analogAxis[Axis::Y].setPosition(calibration.neutralY);
 
        // set reverse state to unpressed
        this->reverseState = false;
 
        // set gear to neutral
        this->setGear(0);
 
        // status changed if gear changed
        return this->gearChanged();
    }
 
    // poll the analog axes for new data
    analogAxis[Axis::X].read();
    analogAxis[Axis::Y].read();
    const int x = analogAxis[Axis::X].getPosition();
    const int y = analogAxis[Axis::Y].getPosition();
 
    // poll the reverse button and cache in the class
    this->reverseState = this->readReverseButton();
 
    // check previous gears for comparison
    const Gear previousGear = this->getGear();
    const bool prevOdd = ((previousGear != -1) && (previousGear & 1));  // were we previously in an odd gear
    const bool prevEven = (!prevOdd && previousGear != 0);  // were we previously in an even gear
 
    Gear newGear = 0;
 
    // If we're below the 'release' thresholds, we must still be in the previous gear
    if ((prevOdd && y > calibration.oddRelease) || (prevEven && y < calibration.evenRelease)) {
        newGear = previousGear;
    }
 
    // If we're *not* below the release thresholds, we may be in a different gear
    else {
        // Check if we're in even or odd gears (Y axis)
        if (y > calibration.oddTrigger) {
            newGear = 1;  // we're in an odd gear
        }
        else if (y < calibration.evenTrigger) {
            newGear = 2;  // we're in an even gear
        }
 
        if (newGear != 0) {
            // Now check *which* gear we're in, if we're in one (X axis)
                 if (x > calibration.rightEdge) newGear += 4;  // 1-2 + 4 = 5-6
            else if (x >= calibration.leftEdge) newGear += 2;  // 1-2 + 2 = 3-4
            // (note the '>=', because it would normally be a '<' check for the lower range)
            // else gear = 1-2 (as set above)
 
            const bool reverse = getReverseButton();
 
            // If the reverse button is pressed and we're in 5th gear
            // something is wrong. Revert that and go back to neutral.
            if (reverse && newGear == 5) {
                newGear = 0;
            }
 
            // If the reverse button is pressed or we were previously
            // in reverse *and* we are currently in 6th gear, then we
            // should be in reverse.
            else if ((reverse || previousGear == -1) && newGear == 6) {
                newGear = -1;
            }
        }
    }
 
    // finally, store the newly calculated gear
    this->setGear(newGear);
 
    return this->gearChanged();
}
 
long AnalogShifter::getPosition(Axis ax, long min, long max) const {
    if (ax != Axis::X && ax != Axis::Y) return min;  // not an axis
    return analogAxis[ax].getPosition(min, max);
}
 
int AnalogShifter::getPositionRaw(Axis ax) const {
    if (ax != Axis::X && ax != Axis::Y) return AnalogInput::Min;  // not an axis
    return analogAxis[ax].getPositionRaw();
}
 
bool AnalogShifter::readReverseButton() {
    // if the reverse pin is not set, avoid reading the
    // floating input and just return 'false'
    if (pinReverse == UnusedPin) {
        return false;
    }
    return digitalRead(pinReverse);
}
 
bool AnalogShifter::getReverseButton() const {
    // return the cached reverse state from updateState(bool)
    // do NOT poll the button!
    return this->reverseState;
}
 
void AnalogShifter::setCalibration(
    GearPosition neutral,
    GearPosition g1, GearPosition g2, GearPosition g3, GearPosition g4, GearPosition g5, GearPosition g6,
    float engagePoint, float releasePoint, float edgeOffset) {
 
    // limit percentage thresholds
    engagePoint = floatPercent(engagePoint);
    releasePoint = floatPercent(releasePoint);
    edgeOffset = floatPercent(edgeOffset);
 
    const int xLeft = (g1.x + g2.x) / 2;  // find the minimum X position average
    const int xRight = (g5.x + g6.x) / 2;  // find the maximum X position average
 
    const int yOdd = (g1.y + g3.y + g5.y) / 3;  // find the maximum Y position average
    const int yEven = (g2.y + g4.y + g6.y) / 3;  // find the minimum Y position average
 
    // set X/Y calibration and inversion
    analogAxis[Axis::X].setCalibration({ xLeft, xRight });
    analogAxis[Axis::Y].setCalibration({ yEven, yOdd });
 
    // save neutral values (raw)
    calibration.neutralX = neutral.x;
    calibration.neutralY = neutral.y;
 
    // get normalized and inverted neutral values
    // this lets us take advantage of the AnalogInput normalization function
    // that handles inverted axes and automatic range rescaling, so the rest of
    // the calibration options can be in the normalized range
    const Axis axes[2] = { Axis::X, Axis::Y };
    int* const neutralAxis[2] = { &neutral.x, &neutral.y };
    for (int i = 0; i < 2; i++) {
        const int previous = analogAxis[axes[i]].getPositionRaw();  // save current value
        analogAxis[axes[i]].setPosition(*neutralAxis[i]);           // set new value to neutral calibration
        *neutralAxis[i] = analogAxis[axes[i]].getPosition();        // get normalized neutral value
        analogAxis[axes[i]].setPosition(previous);                  // reset axis position to previous
    }
 
    // calculate the distances between each neutral and the limits of each axis
    const int yOddDiff = AnalogInput::Max - neutral.y;
    const int yEvenDiff = neutral.y - AnalogInput::Min;
 
    const int leftDiff = neutral.x - AnalogInput::Min;
    const int rightDiff = AnalogInput::Max - neutral.x;
 
    // calculate and save the trigger and release points for each level
    calibration.oddTrigger = neutral.y + ((float)yOddDiff * engagePoint);
    calibration.oddRelease = neutral.y + ((float)yOddDiff * releasePoint);
 
    calibration.evenTrigger = neutral.y - ((float)yEvenDiff * engagePoint);
    calibration.evenRelease = neutral.y - ((float)yEvenDiff * releasePoint);
 
    calibration.leftEdge = neutral.x - ((float)leftDiff * edgeOffset);
    calibration.rightEdge = neutral.x + ((float)rightDiff * edgeOffset);
 
#if 0
    Serial.print("Odd Trigger: ");
    Serial.println(calibration.oddTrigger);
    Serial.print("Odd Release: ");
    Serial.println(calibration.oddRelease);
    Serial.print("Even Trigger: ");
    Serial.println(calibration.evenTrigger);
    Serial.print("Even Release: ");
    Serial.println(calibration.evenRelease);
    Serial.print("Left Edge: ");
    Serial.println(calibration.leftEdge);
    Serial.print("Right Edge: ");
    Serial.println(calibration.rightEdge);
    Serial.println();
 
    Serial.print("X Min: ");
    Serial.println(analogAxis[Axis::X].getMin());
    Serial.print("X Max: ");
    Serial.println(analogAxis[Axis::X].getMax());
 
    Serial.print("Y Min: ");
    Serial.println(analogAxis[Axis::Y].getMin());
    Serial.print("Y Max: ");
    Serial.println(analogAxis[Axis::Y].getMax());
#endif
}
 
void AnalogShifter::serialCalibration(Stream& iface) {
    if (isConnected() == false) {
        iface.print(F("Error! Cannot perform calibration, "));
        iface.print(F("shifter"));
        iface.println(F(" is not connected."));
        return;
    }
 
    const char* separator = "------------------------------------";
 
    iface.println();
    iface.println(F("Sim Racing Library Shifter Calibration"));
    iface.println(separator);
    iface.println();
 
    AnalogShifter::GearPosition gears[7];  // neutral, then 1-6
    float engagementPoint = CalEngagementPoint;
    float releasePoint = CalReleasePoint;
    float edgeOffset = CalEdgeOffset;
 
    for (int i = 0; i <= 6; i++) {
        const String gearName = this->getGearString(i);
 
        iface.print(F("Please move the gear shifter into "));
        iface.print(gearName);
        iface.println(F(". Send any character to continue."));
 
        waitClient(iface);
 
        this->update();
        gears[i] = { 
            this->analogAxis[Axis::X].getPositionRaw(), 
            this->analogAxis[Axis::Y].getPositionRaw()
        };
 
        iface.print("Gear '");
        iface.print(gearName);
        iface.print("' position recorded as { ");
        iface.print(gears[i].x);
        iface.print(", ");
        iface.print(gears[i].y);
        iface.println(" }");
        iface.println();
    }
 
    iface.println(separator);
    iface.println();
 
    iface.println(F("These settings are optional. Send 'y' to customize. Send any other character to continue with the default values."));
 
    iface.print(F("  * Gear Engagement Point: \t"));
    iface.println(engagementPoint);
 
    iface.print(F("  * Gear Release Point:   \t"));
    iface.println(releasePoint);
 
    iface.print(F("  * Horizontal Gate Offset:\t"));
    iface.println(edgeOffset);
 
    iface.println();
 
    waitClient(iface);
 
    if (iface.read() == 'y') {
        iface.println(F("Set the engagement point as a floating point percentage. This is the percentage away from the neutral axis on Y to start engaging gears."));
        readFloat(engagementPoint, iface);
        iface.println();
 
        iface.println(F("Set the release point as a floating point percentage. This is the percentage away from the neutral axis on Y to go back into neutral. It must be less than the engagement point."));
        readFloat(releasePoint, iface);
        iface.println();
 
        iface.println(F("Set the gate offset as a floating point percentage. This is the percentage away from the neutral axis on X to select the side gears."));
        readFloat(edgeOffset, iface);
        iface.println();
    }
 
    flushClient(iface);
 
    this->setCalibration(gears[0], gears[1], gears[2], gears[3], gears[4], gears[5], gears[6], engagementPoint, releasePoint, edgeOffset);
 
    iface.println(F("Here is your calibration:"));
    iface.println(separator);
    iface.println();
 
    iface.print(F("shifter.setCalibration( "));
 
    for (int i = 0; i < 7; i++) {
        iface.print('{');
 
        iface.print(gears[i].x);
        iface.print(", ");
        iface.print(gears[i].y);
 
        iface.print('}');
        iface.print(", ");
    }
    iface.print(engagementPoint);
    iface.print(", ");
    iface.print(releasePoint);
    iface.print(", ");
    iface.print(edgeOffset);
    iface.print(");");
    iface.println();
 
    iface.println();
    iface.println(separator);
    iface.println();
 
    iface.println(F("Paste this line into the setup() function to calibrate on startup."));
    iface.println(F("\n\nCalibration complete! :)\n"));
}
 
LogitechShifter::LogitechShifter(PinNum pinX, PinNum pinY, PinNum pinRev, PinNum detectPin)
    : 
    AnalogShifter(
        -1, 6,  // includes reverse and gears 1-6
        pinX, pinY, pinRev
    ),
 
    detectObj(detectPin, false)  // active high
{
    this->setDetectPtr(&this->detectObj);
    this->setCalibration({ 490, 440 }, { 253, 799 }, { 262, 86 }, { 460, 826 }, { 470, 76 }, { 664, 841 }, { 677, 77 });
}
 
 
LogitechShifterG27::LogitechShifterG27(
    PinNum pinX, PinNum pinY,
    PinNum pinLatch, PinNum pinClock, PinNum pinData,
    PinNum pinLed,
    PinNum pinDetect
) :
    LogitechShifter(pinX, pinY, UnusedPin, pinDetect),
 
    pinLatch(sanitizePin(pinLatch)), pinClock(sanitizePin(pinClock)), pinData(sanitizePin(pinData)),
    pinLed(sanitizePin(pinLed))
{
    this->pinModesSet = false;
    this->setPowerLED(1);  // power LED on by default
    this->buttonStates = this->previousButtons = 0x0000;  // zero all button data
 
    // using the calibration values from my own G27 shifter
    this->setCalibration({ 453, 470 }, { 247, 828 }, { 258, 6 }, { 449, 878 }, { 472, 5 }, { 645, 880 }, { 651, 21 });
}
 
void LogitechShifterG27::cacheButtons(uint16_t newStates) {
    this->previousButtons = this->buttonStates;  // save current to previous
    this->buttonStates = newStates;  // replace current with new value
}
 
void LogitechShifterG27::setPinModes(bool enabled) {
    // check if pins are valid. if one or more pins is unused,
    // this isn't going to work and we shouldn't bother setting
    // any of the pin states
    if (
        this->pinData  == UnusedPin ||
        this->pinLatch == UnusedPin ||
        this->pinClock == UnusedPin)
    {
        return;
    }
 
    // set up data pin to read from regardless
    pinMode(this->pinData, INPUT);
 
    // enabled = drive the output pins
    if (enabled) {
        // note: writing the output before setting the
        // pin mode so that we don't accidentally drive
        // the wrong direction momentarily
 
        // set latch pin as output, HIGH on idle
        digitalWrite(this->pinLatch, HIGH);
        pinMode(this->pinLatch, OUTPUT);
 
        // set clock pin as output, LOW on idle
        digitalWrite(this->pinClock, LOW);
        pinMode(this->pinClock, OUTPUT);
 
        // if we have an LED pin, set it to output and write the
        // commanded state (inverted, as the LED is active-low)
        if (this->pinLed != UnusedPin) {
            digitalWrite(this->pinLed, !(this->ledState));
            pinMode(this->pinLed, OUTPUT);
        }
    }
 
    // disabled = leave output pins as high-z
    else {
        // note: setting the mode before writing the
        // output for the same reason; changing in
        // high-z mode is safer
 
        // set latch pin as high impedance, with pull-up
        pinMode(this->pinLatch, INPUT);
        digitalWrite(this->pinLatch, HIGH);
 
        // set clock pin as high impedance, no pull-up
        pinMode(this->pinClock, INPUT);
        digitalWrite(this->pinClock, LOW);
 
        // if we have an LED pin, set it to input, LOW on idle
        if (this->pinLed != UnusedPin) {
            pinMode(this->pinLed, INPUT);
            digitalWrite(this->pinLed, LOW);
        }
    }
 
    this->pinModesSet = enabled;
}
 
void LogitechShifterG27::setPowerLED(bool state) {
    this->ledState = state;
}
 
uint16_t LogitechShifterG27::readShiftRegisters() {
    // if the pin outputs are not set, quit (none pressed)
    if (!this->pinModesSet) return 0x0000;
 
    uint16_t data = 0x0000;
 
    // pulse shift register latch from high to low to high, 12 us
    // (this timing is *completely* arbitrary, but it's nice to have
    //  *some* delay so that much faster MCUs don't blow through it)
    digitalWrite(this->pinLatch, LOW);
    delayMicroseconds(12);
    digitalWrite(this->pinLatch, HIGH);
    delayMicroseconds(12);
 
    // clock is pulsed from LOW to HIGH on every bit,
    // and then left to idle low
    for (int i = 0; i < 16; ++i) {
        digitalWrite(this->pinClock, LOW);
        const bool state = digitalRead(this->pinData);
        if (state) data |= 1 << (15 - i);  // store data in word, MSB-first
        digitalWrite(this->pinClock, HIGH);
        delayMicroseconds(6);
    }
    digitalWrite(this->pinClock, LOW);
 
    // edge case: two of the bits (0x8000 and 0x2000) are connected only to
    // pull-down resistors, and should theoretically never be high. If they,
    // and all other bits, *are* high, then we are not reading from a shifter
    // that has shift registers. The "Driving Force" (G29/G920/G923) shifter
    // has its data output connected to the 'reverse' button through a buffer,
    // and will report 'high' if the reverse button is pressed no matter how
    // many times the clock is pulsed.
    //
    // QED: we are connected to a "Driving Force" shifter, and not a G27.
    // That's okay! If we set the state of the 'reverse' button and clear
    // all others, we can still behave like a G27.
    if (data == 0xFFFF) {
        data = (1 << (uint8_t) Button::BUTTON_REVERSE);
    }
 
    return data;
}
 
void LogitechShifterG27::begin() {
    // disable pin outputs. this sets the initial
    // 'safe' state. the outputs will be enabled
    // by the 'updateState(bool)' function when needed.
    this->setPinModes(0);
 
    // call the begin() class of the base, which will also
    // poll 'update()' on our behalf
    this->AnalogShifter::begin();
}
 
bool LogitechShifterG27::updateState(bool connected) {
    bool changed = false;
 
    // if we're connected, set the pin modes, read the
    // shift registers, and cache the data
    if (connected) {
        if (!this->pinModesSet) {
            this->setPinModes(1);
        }
 
        if (this->pinLed != UnusedPin) {
            digitalWrite(this->pinLed, !(this->ledState));  // active low
        }
 
        const uint16_t data = this->readShiftRegisters();
        this->cacheButtons(data);
        changed |= this->buttonsChanged();
    }
 
    // if we're *not* connected, reset the pin modes and
    // set no buttons pressed
    else {
        if (this->pinModesSet) {
            this->setPinModes(0);
        }
 
        this->cacheButtons(0x0000);
        changed |= this->buttonsChanged();
    }
 
    // we also need to update the data for the analog shifter
    changed |= AnalogShifter::updateState(connected);
 
    return changed;
}
 
bool LogitechShifterG27::buttonsChanged() const {
    return this->buttonStates != this->previousButtons;
}
 
bool LogitechShifterG27::getButton(Button button) const {
    return this->extractButton(button, this->buttonStates);
}
 
bool LogitechShifterG27::getButtonChanged(Button button) const {
    return this->getButton(button) != this->extractButton(button, this->previousButtons);
}
 
int LogitechShifterG27::getDpadAngle() const {
    const Button pads[4] = {
        DPAD_UP,
        DPAD_RIGHT,
        DPAD_DOWN,
        DPAD_LEFT,
    };
 
    // combine pads to a bitfield (nybble)
    uint8_t dpad = 0x00;
    for (uint8_t i = 0; i < 4; ++i) {
        dpad |= (this->getButton(pads[i]) << i);
    }
 
    // The hatswitch value is from 0-7 proceeding clockwise
    // from top (0 is 'up', 1 is 'up + right', etc.). I don't
    // know of a great way to do this, so have this naive
    // lookup table with a built-in SOCD cleaner
 
    // For this, simultaneous opposing cardinal directions
    // are neutral (because this is presumably used for
    // navigation only, and not fighting games. Probably).
 
    // bitfield to hatswitch lookup table
    const uint8_t hat_table[16] = {
        8, // 0b0000, Unpressed
        0, // 0b0001, Up
        2, // 0b0010, Right
        1, // 0b0011, Right + Up
        4, // 0b0100, Down
        8, // 0b0101, Down + Up (SOCD None)
        3, // 0b0110, Down + Right
        2, // 0b0111, Down + Right + Up (SOCD Right)
        6, // 0b1000, Left
        7, // 0b1001, Left + Up
        8, // 0b1010, Left + Right (SOCD None)
        0, // 0b1011, Left + Right + Up (SOCD Up)
        5, // 0b1100, Left + Down
        6, // 0b1101, Left + Down + Up (SOCD Left)
        4, // 0b1110, Left + Down + Right (SOCD Down)
        8, // 0b1111, Left + Down + Right + Up (SOCD None)
    };
 
    // multiply the 0-8 value by 45 to get it in degrees
    int16_t angle = hat_table[dpad & 0x0F] * 45;
 
    // edge case: if no buttons are pressed, the angle is '-1'
    if (angle == 360) angle = -1;
 
    return angle;
}
 
bool LogitechShifterG27::readReverseButton() {
    // this virtual function is provided for the sake of the AnalogShifter base
    // class, which can use this to get the button state from the shift register
    // without needing to interface with the shift registers themselves
    return this->getButton(BUTTON_REVERSE);
}
 
 
/*
* Static calibration constants
* These values are arbitrary - just what worked well with my own shifter.
*/
const float LogitechShifterG25::CalEngagementPoint = 0.70;
const float LogitechShifterG25::CalReleasePoint = 0.50;
 
LogitechShifterG25::LogitechShifterG25(
    PinNum pinX, PinNum pinY,
    PinNum pinLatch, PinNum pinClock, PinNum pinData,
    PinNum pinLed,
    PinNum pinDetect
) :
    LogitechShifterG27(
        pinX, pinY,
        pinLatch, pinClock, pinData,
        pinLed,
        pinDetect
    ),
 
    sequentialProcess(false),  // not in sequential mode
    sequentialState(0)         // no sequential buttons pressed
{
    // using the calibration values from my own G25 shifter
    this->setCalibration({ 508, 435 }, { 310, 843 }, { 303, 8 }, { 516, 827 }, { 540, 14 }, { 713, 846 }, { 704, 17 });
    this->setCalibrationSequential(425, 619, 257);
}
 
void LogitechShifterG25::begin() {
    this->sequentialProcess = false;  // clear process flag
    this->sequentialState = 0;        // clear any pressed buttons
 
    this->LogitechShifterG27::begin();  // call base class begin()
}
 
bool LogitechShifterG25::updateState(bool connected) {
    // call the base class to update the state of the
    // buttons and the H-pattern shifter
    bool changed = this->LogitechShifterG27::updateState(connected);
 
    // if we're connected and in sequential mode...
    if (connected && this->inSequentialMode()) {
 
        // clear 'changed', because this will falsely report a change
        // if we've "shifted" into 2nd/4th in the process of sequential
        // shifting
        changed = false;
 
        // force neutral gear, ignoring the H-pattern selection
        this->setGear(0);
 
        // edge case: if we've not just switched into sequential mode,
        // we need to ignore the H-pattern gear change (to 2/4, and then
        // set by us to neutral). We can do that, hackily, by setting to
        // neutral again to clear the cached gear for comparison.
        if (this->sequentialProcess) {
            this->setGear(0);
        }
 
        // read the raw y axis value, ignoring the H-pattern calibration
        const int y = this->getPositionRaw(Axis::Y);
 
        // save the previous state for reference
        const int8_t prevState = this->sequentialState;
 
        // if we're neutral, check for up/down shift
        if (this->sequentialState == 0) {
                 if (y >= this->seqCalibration.upTrigger)   this->sequentialState =  1;
            else if (y <= this->seqCalibration.downTrigger) this->sequentialState = -1;
        }
 
        // if we're in up-shift mode, check for release
        else if ((this->sequentialState == 1) && (y < this->seqCalibration.upRelease)) {
            this->sequentialState = 0;
        }
 
        // if we're in down-shift mode, check for release
        else if ((this->sequentialState == -1) && (y > this->seqCalibration.downRelease)) {
            this->sequentialState = 0;
        }
 
        // set the 'changed' flag if the sequential state changed
        if (prevState != this->sequentialState) {
            changed = true;
        }
        // otherwise, set 'changed' based on the buttons *only*
        else {
            changed = this->buttonsChanged();
        }
 
        // set 'process' flag to handle edge case on subsequent updates
        this->sequentialProcess = true;
    }
 
    // if we're not connected or if the sequential mode has been disabled,
    // clear the sequential flags if they have been set
    else {
        if (this->sequentialProcess) {
            this->sequentialProcess = false;  // not in sequential mode
            this->sequentialState = 0;        // no sequential buttons pressed
            changed = true;
        }
    }
 
    return changed;
}
 
bool LogitechShifterG25::inSequentialMode() const {
    return this->getButton(BUTTON_SEQUENTIAL);
}
 
bool LogitechShifterG25::getShiftUp() const {
    return this->sequentialState == 1;
}
 
bool LogitechShifterG25::getShiftDown() const {
    return this->sequentialState == -1;
}
 
void LogitechShifterG25::setCalibrationSequential(int neutral, int up, int down, float engagePoint, float releasePoint) {
    // limit percentage thresholds
    engagePoint  = floatPercent(engagePoint);
    releasePoint = floatPercent(releasePoint);
 
    // prevent release point from being higher than engage
    // (which will prevent the shifter from working at all)
    if (releasePoint > engagePoint) {
        releasePoint = engagePoint;
    }
 
    // calculate ranges
    const int upRange   = up - neutral;
    const int downRange = neutral - down;
 
    // calculate calibration points
    this->seqCalibration.upTrigger   = neutral + (upRange * engagePoint);
    this->seqCalibration.upRelease   = neutral + (upRange * releasePoint);
 
    this->seqCalibration.downTrigger = neutral - (downRange * engagePoint);
    this->seqCalibration.downRelease = neutral - (downRange * releasePoint);
}
 
void LogitechShifterG25::serialCalibrationSequential(Stream& iface) {
    // err if not connected
    if (this->isConnected() == false) {
        iface.print(F("Error! Cannot perform calibration, "));
        iface.print(F("shifter"));
        iface.println(F(" is not connected."));
        return;
    }
 
    const char* separator = "------------------------------------";
 
    iface.println();
    iface.println(F("Sim Racing Library G25 Sequential Shifter Calibration"));
    iface.println(separator);
    iface.println();
 
    while (this->inSequentialMode() == false) {
        iface.print(F("Please press down on the shifter and move the dial counter-clockwise to put the shifter into sequential mode"));
        iface.print(F(". Send any character to continue."));
        iface.println(F(" Send 'q' to quit."));
        iface.println();
 
        waitClient(iface);
        this->update();
 
        // quit if user sends 'q'
        if (iface.read() == 'q') {
            iface.println(F("Quitting sequential calibration! Goodbye <3"));
            iface.println();
            return;
        }
 
        // send an error if we're still not there
        if (this->inSequentialMode() == false) {
            iface.println(F("Error: The shifter is not in sequential mode"));
            iface.println();
        }
    }
 
    float engagementPoint = LogitechShifterG25::CalEngagementPoint;
    float releasePoint = LogitechShifterG25::CalReleasePoint;
 
    const uint8_t NumPoints = 3;
    const char* directions[2] = {
        "up",
        "down",
    };
    int data[NumPoints];
 
    int& neutral = data[0];
    int& yMax    = data[1];
    int& yMin    = data[2];
 
    for (uint8_t i = 0; i < NumPoints; ++i) {
        if (i == 0) {
            iface.print(F("Leave the gear shifter in neutral"));
        }
        else {
            iface.print(F("Please move the gear shifter to sequentially shift "));
            iface.print(directions[i - 1]);
            iface.print(F(" and hold it there"));
        }
        iface.println(F(". Send any character to continue."));
        waitClient(iface);
 
        this->update();
        data[i] = this->getPositionRaw(Axis::Y);
        iface.println();  // spacing
    }
 
    iface.println(F("These settings are optional. Send 'y' to customize. Send any other character to continue with the default values."));
 
    iface.print(F("  * Shift Engagement Point: \t"));
    iface.println(engagementPoint);
 
    iface.print(F("  * Shift Release Point:   \t"));
    iface.println(releasePoint);
 
    iface.println();
 
    waitClient(iface);
 
    if (iface.read() == 'y') {
        iface.println(F("Set the engagement point as a floating point percentage. This is the percentage away from the neutral axis on Y to start shifting."));
        readFloat(engagementPoint, iface);
        iface.println();
 
        iface.println(F("Set the release point as a floating point percentage. This is the percentage away from the neutral axis on Y to stop shifting. It must be less than the engagement point."));
        readFloat(releasePoint, iface);
        iface.println();
    }
 
    flushClient(iface);
 
    // apply and print
    this->setCalibrationSequential(neutral, yMax, yMin, engagementPoint, releasePoint);
 
    iface.println(F("Here is your calibration:"));
    iface.println(separator);
    iface.println();
 
    iface.print(F("shifter.setCalibrationSequential( "));
 
    iface.print(neutral);
    iface.print(", ");
    iface.print(yMax);
    iface.print(", ");
    iface.print(yMin);
    iface.print(", ");
 
    iface.print(engagementPoint);
    iface.print(", ");
    iface.print(releasePoint);
    iface.print(");");
    iface.println();
 
    iface.println();
    iface.println(separator);
    iface.println();
 
    iface.println(F("Paste this line into the setup() function to calibrate on startup."));
    iface.println(F("\n\nCalibration complete! :)\n"));
}
 
//#########################################################
//                      Handbrake                         #
//#########################################################
 
Handbrake::Handbrake(PinNum pinAx)
    : 
    analogAxis(pinAx),
    changed(false)
{}
 
void Handbrake::begin() {
    update();  // set initial handbrake position
}
 
bool Handbrake::updateState(bool connected) {
    this->changed = false;
 
    // if connected, read state of the axis
    if (connected) {
        this->changed = this->analogAxis.read();
    }
 
    // otherwise, set axis to its minimum (idle) position
    else {
        const int min  = this->analogAxis.getMin();
        const int prev = this->analogAxis.getPositionRaw();
 
        if (min != prev) {
            this->analogAxis.setPosition(min);
            this->changed = true;
        }
    }
 
    return this->changed;
}
 
long Handbrake::getPosition(long rMin, long rMax) const {
    return analogAxis.getPosition(rMin, rMax);
}
 
int Handbrake::getPositionRaw() const {
    return analogAxis.getPositionRaw();
}
 
void Handbrake::setCalibration(AnalogInput::Calibration newCal) {
    analogAxis.setCalibration(newCal);
    analogAxis.setPosition(analogAxis.getMin());  // reset to min
}
 
void Handbrake::serialCalibration(Stream& iface) {
    if (isConnected() == false) {
        iface.print(F("Error! Cannot perform calibration, "));
        iface.print(F("handbrake"));
        iface.println(F(" is not connected."));
        return;
    }
 
    const char* separator = "------------------------------------";
 
    iface.println();
    iface.println(F("Sim Racing Library Handbrake Calibration"));
    iface.println(separator);
    iface.println();
 
    AnalogInput::Calibration newCal;
 
    // read minimum
    iface.println(F("Keep your hand off of the handbrake to record its resting position"));
    iface.println(F("Send any character to continue."));
    waitClient(iface);
 
    analogAxis.read();
    newCal.min = analogAxis.getPositionRaw();
    iface.println();
 
    // read maximum
    iface.println(F("Now pull on the handbrake and hold it at the end of its range"));
    iface.println(F("Send any character to continue."));
    waitClient(iface);
 
    analogAxis.read();
    newCal.max = analogAxis.getPositionRaw();
    iface.println();
 
    // set new calibration
    this->setCalibration(newCal);
 
    // print finished calibration
    iface.println(F("Here is your calibration:"));
    iface.println(separator);
    iface.println();
 
    iface.print(F("handbrake.setCalibration("));
    iface.print('{');
    iface.print(newCal.min);
    iface.print(F(", "));
    iface.print(newCal.max);
    iface.print("});");
    iface.println();
 
    iface.println();
    iface.println(separator);
    iface.println();
 
    iface.print(F("Paste this line into the setup() function. The "));
    iface.print(F("handbrake"));
    iface.print(F(" will be calibrated with these values on startup."));
    iface.println(F("\nCalibration complete! :)\n\n"));
 
    flushClient(iface);
}
    
};  // end SimRacing namespace