SimRacing.h

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/>.
 */
 
#ifndef SIM_RACING_LIB_H
#define SIM_RACING_LIB_H
 
#include <Arduino.h>
 
namespace SimRacing {
    using PinNum = int16_t;
 
    const PinNum UnusedPin = -1;
 
 
    enum Axis : uint8_t {
        X = 0,  
        Y = 1,  
    };
 
 
    class DeviceConnection {
    public:
        enum ConnectionState {
            Disconnected,  
            PlugIn,        
            Connected,     
            Unplug,        
        };
 
        DeviceConnection(PinNum pin, bool activeLow = false, unsigned long detectTime = 250);
 
        void poll();
 
        ConnectionState getState() const;
 
        bool isConnected() const;
 
        void setStablePeriod(unsigned long t);
 
    private:
        bool readPin() const;
 
        PinNum pin;                  
        bool inverted;               
        unsigned long stablePeriod;  
 
        ConnectionState state;       
        bool pinState;               
        unsigned long lastChange;    
    };
 
 
    class AnalogInput {
    public:
        static const int Min = 0;     
        static const int Max = 1023;  
 
        AnalogInput(PinNum pin);
 
        virtual bool read();
 
        long getPosition(long rMin = Min, long rMax = Max) const;
 
        int getPositionRaw() const;
 
        int getMin() const { return this->cal.min; }
 
        int getMax() const { return this->cal.max; }
 
        bool isInverted() const;
 
        void setPosition(int newPos);
 
        void setInverted(bool invert = true);
 
        struct Calibration {
            int min;  
            int max;  
        };
 
        void setCalibration(Calibration newCal);
 
    private:
        PinNum pin;              
        int position;            
        Calibration cal;         
    };
 
 
    class Peripheral {
    public:
        virtual ~Peripheral() {}
 
        virtual void begin() {};
 
        bool update();
 
        bool isConnected() const;
 
        void setStablePeriod(unsigned long t);
 
    protected:
        virtual bool updateState(bool connected) = 0;
 
        void setDetectPtr(DeviceConnection* d);
 
    private:
        DeviceConnection* detector;  
    };
 
 
    enum Pedal {
        Gas = 0,
        Accelerator = Gas,
        Throttle = Gas,
        Brake = 1,
        Clutch = 2,
    };
 
    class Pedals : public Peripheral {
    public:
        using PedalID = SimRacing::Pedal;
 
        Pedals(
            AnalogInput* dataPtr, uint8_t nPedals
        );
 
        virtual void begin();
 
        long getPosition(PedalID pedal, long rMin = 0, long rMax = 100) const;
 
        int getPositionRaw(PedalID pedal) const;
 
        bool hasPedal(PedalID pedal) const;
 
        int getNumPedals() const { return this->NumPedals; }
 
        bool positionChanged() const { return changed; }
 
        void setCalibration(PedalID pedal, AnalogInput::Calibration cal);
 
        void serialCalibration(Stream& iface = Serial);
        
        static String getPedalName(PedalID pedal);
 
    protected:
        virtual bool updateState(bool connected);
 
    private:
        AnalogInput* pedalData;     
        const int NumPedals;        
        bool changed;               
    };
 
 
    class TwoPedals : public Pedals {
    public:
        TwoPedals(
            PinNum pinGas, PinNum pinBrake
        );
 
        void setCalibration(AnalogInput::Calibration gasCal, AnalogInput::Calibration brakeCal);
 
    private:
        static const uint8_t NumPedals = 2;  
        AnalogInput pedalData[NumPedals];    
    };
 
 
    class ThreePedals : public Pedals {
    public:
        ThreePedals(
            PinNum pinGas, PinNum pinBrake, PinNum pinClutch
        );
 
        void setCalibration(AnalogInput::Calibration gasCal, AnalogInput::Calibration brakeCal, AnalogInput::Calibration clutchCal);
 
    private:
        static const uint8_t NumPedals = 3;  
        AnalogInput pedalData[NumPedals];    
    };
 
 
 
    class Shifter : public Peripheral {
    public:
        using Gear = int8_t;
 
        Shifter(Gear min, Gear max);
    
        Gear getGear() const { return currentGear; }
 
        static char getGearChar(int gear);
 
        char getGearChar() const;
 
        static String getGearString(int gear);
 
        String getGearString() const;
 
        bool gearChanged() const { 
            return this->currentGear != this->previousGear;
        }
 
        Gear getGearMin() { return MinGear; }
 
        Gear getGearMax() { return MaxGear; }
 
    protected:
        void setGear(Gear gear);
 
    private:
        const Gear MinGear;  
        const Gear MaxGear;  
 
        Gear currentGear;    
        Gear previousGear;   
    };
 
 
    class AnalogShifter : public Shifter {
    public:
        AnalogShifter(
            Gear gearMin, Gear gearMax,
            PinNum pinX, PinNum pinY,
            PinNum pinRev = UnusedPin
        );
 
        virtual void begin();
 
        long getPosition(Axis ax, long rMin = AnalogInput::Min, long rMax = AnalogInput::Max) const;
 
        int getPositionRaw(Axis ax) const;
 
        bool getReverseButton() const;
 
        struct GearPosition {
            int x;  
            int y;  
        };
 
        void setCalibration(
            GearPosition neutral,
            GearPosition g1, GearPosition g2, GearPosition g3, GearPosition g4, GearPosition g5, GearPosition g6,
            float engagePoint = CalEngagementPoint, float releasePoint = CalReleasePoint, float edgeOffset = CalEdgeOffset);
 
        void serialCalibration(Stream& iface = Serial);
 
    protected:
        virtual bool updateState(bool connected);
 
    private:
        virtual bool readReverseButton();
 
        static const float CalEngagementPoint; 
 
        static const float CalReleasePoint;
 
        static const float CalEdgeOffset;
 
        /*** Internal calibration struct */
        struct Calibration {
            int    neutralX;  
            int    neutralY;  
            int  oddTrigger;  
            int  oddRelease;  
            int evenTrigger;  
            int evenRelease;  
            int    leftEdge;  
            int   rightEdge;  
        } calibration;
 
        AnalogInput analogAxis[2];  
        PinNum pinReverse;          
        bool reverseState;          
    };
 
 
 
    class Handbrake : public Peripheral {
    public:
        Handbrake(PinNum pinAx);
 
        virtual void begin();
 
        long getPosition(long rMin = 0, long rMax = 100) const;
 
        int getPositionRaw() const;
 
        bool positionChanged() const { return this->changed; }
 
        void setCalibration(AnalogInput::Calibration newCal);
 
        void serialCalibration(Stream& iface = Serial);
 
    protected:
        virtual bool updateState(bool connected);
 
    private:
        AnalogInput analogAxis;      
        bool changed;                
    };
 
 
    class LogitechPedals : public ThreePedals {
    public:
        LogitechPedals(PinNum pinGas, PinNum pinBrake, PinNum pinClutch, PinNum pinDetect = UnusedPin);
 
    private:
        DeviceConnection detectObj;  
    };
 
    class LogitechDrivingForceGT_Pedals : public TwoPedals {
    public:
        LogitechDrivingForceGT_Pedals(PinNum pinGas, PinNum pinBrake, PinNum pinDetect = UnusedPin);
 
    private:
        DeviceConnection detectObj;  
    };
 
    class LogitechShifter : public AnalogShifter {
    public:
        LogitechShifter(PinNum pinX, PinNum pinY, PinNum pinRev = UnusedPin, PinNum pinDetect = UnusedPin);
 
    private:
        DeviceConnection detectObj;  
    };
 
    using LogitechShifterG923 = LogitechShifter;
 
    using LogitechShifterG29 = LogitechShifter;
 
    using LogitechShifterG920 = LogitechShifter;
 
    class LogitechShifterG27 : public LogitechShifter {
    public:
        enum Button : uint8_t {
            BUTTON_UNUSED1    = 15,  
            BUTTON_REVERSE    = 14,  
            BUTTON_UNUSED2    = 13,  
            BUTTON_SEQUENTIAL = 12,  
            BUTTON_3          = 11,  
            BUTTON_2          = 10,  
            BUTTON_4          = 9,   
            BUTTON_1          = 8,   
            BUTTON_NORTH      = 7,   
            BUTTON_EAST       = 6,   
            BUTTON_WEST       = 5,   
            BUTTON_SOUTH      = 4,   
            DPAD_RIGHT        = 3,   
            DPAD_LEFT         = 2,   
            DPAD_DOWN         = 1,   
            DPAD_UP           = 0,   
        };
 
        LogitechShifterG27(
            PinNum pinX, PinNum pinY,
            PinNum pinLatch, PinNum pinClock, PinNum pinData,
            PinNum pinLed    = UnusedPin,
            PinNum pinDetect = UnusedPin
        );
 
        virtual void begin();
 
        bool getButton(Button button) const;
 
        bool getButtonChanged(Button button) const;
 
        int getDpadAngle() const;
 
        bool buttonsChanged() const;
 
        void setPowerLED(bool state);
 
        bool getPowerLED() const { return this->ledState; }
 
    protected:
        virtual bool updateState(bool connected);
 
    private:
        static bool extractButton(Button button, uint16_t data) {
            // convert button to single bit with offset, and perform
            // a bitwise 'AND' to get the bit value
            return data & (1 << (uint8_t) button);
        }
 
        void cacheButtons(uint16_t newStates);
 
        void setPinModes(bool enabled);
 
        uint16_t readShiftRegisters();
 
        virtual bool readReverseButton();
 
        // Pins for the shift register interface
        PinNum pinLatch;             
        PinNum pinClock;             
        PinNum pinData;              
 
        // Generic I/O pins
        PinNum pinLed;               
 
        // I/O state
        bool pinModesSet;            
        bool ledState;               
 
        // Button states
        uint16_t buttonStates;       
        uint16_t previousButtons;    
    };
 
    class LogitechShifterG25 : public LogitechShifterG27 {
    public:
        LogitechShifterG25(
            PinNum pinX, PinNum pinY,
            PinNum pinLatch, PinNum pinClock, PinNum pinData,
            PinNum pinLed    = UnusedPin,
            PinNum pinDetect = UnusedPin
        );
 
        virtual void begin();
 
        bool inSequentialMode() const;
 
        bool getShiftUp() const;
 
        bool getShiftDown() const;
 
        void setCalibrationSequential(int neutral, int up, int down,
            float engagePoint  = LogitechShifterG25::CalEngagementPoint,
            float releasePoint = LogitechShifterG25::CalReleasePoint
        );
 
        void serialCalibrationSequential(Stream& iface = Serial);
 
    protected:
        virtual bool updateState(bool connected);
 
    private:
        static const float CalEngagementPoint; 
 
        static const float CalReleasePoint;
 
        bool   sequentialProcess;  
        int8_t sequentialState;    
 
        /*** Internal calibration struct */
        struct SequentialCalibration {
            int   upTrigger;  
            int   upRelease;  
            int downTrigger;  
            int downRelease;  
        } seqCalibration;
    };
 
 
#if defined(__AVR_ATmega32U4__) || defined(SIM_RACING_DOXYGEN)
    template<class T, uint8_t Version>
    T CreateShieldObject();
 
    template<>
    LogitechPedals CreateShieldObject<LogitechPedals, 1>();
 
    template<>
    LogitechPedals CreateShieldObject<LogitechPedals, 2>();
 
    template<>
    LogitechShifter CreateShieldObject<LogitechShifter, 1>();
 
    template<>
    LogitechShifter CreateShieldObject<LogitechShifter, 2>();
 
    template<>
    LogitechShifterG27 CreateShieldObject<LogitechShifterG27, 2>();
 
    template<>
    LogitechShifterG25 CreateShieldObject<LogitechShifterG25, 2>();
#endif
 
}  // end SimRacing namespace
 
#endif