converter.h

/* Copyright © 2018-2025 Pascal JEAN, All rights reserved.
   This file is part of the Piduino Library.
 
   The Piduino Library 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.
 
   The Piduino Library 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 the Piduino Library; if not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
 
#include <string>
#include <vector>
#include <map>
#include <functional>
#include <piduino/iodevice.h>
#include <climits>
 
namespace Piduino {
  class Converter : public IoDevice {
    public:
      enum Type {
        AnalogToDigital,  
        DigitalToAnalog,  
        Sensor,          
        GpioExpander,  
        UnknownType = -1         
      };
 
      enum ModeFlag {
        NoMode =        0x00000000, 
        NormalMode =    0x00000000, 
        DigitalInput =  0x00000001, 
        DigitalOutput = 0x00000002, 
        AnalogInput =   0x00000004, 
        AnalogOutput =  0x00000008, 
        PullUp =        0x00000010, 
        PullDown =      0x00000020, 
        ActiveLow =     0x00000040, 
 
        // Trigger Modes for GPIO
        EdgeRising =    0x00000080, 
        EdgeFalling =   0x00000100, 
        EdgeBoth =      EdgeRising | EdgeFalling, 
        Interrupt =     0x00000200, 
 
        // Conversion Modes for ADCs
        Continuous =    0x00000400, 
        SingleShot =    0x00000800, 
 
        FastMode =      0x00001000, 
        SaveToEEPROM =  0x00002000, 
 
        // Power Down Modes
        PwrDwn0 =       0x00004000, 
        PwrDwn1 =       0x00008000, 
        PwrDwnEn =      0x00010000, 
        PwrDwn  =       PwrDwnEn, 
        PwrDwnR1 =      PwrDwnEn, 
        PwrDwnR2 =      PwrDwnEn | PwrDwn0, 
        PwrDwnR3 =      PwrDwnEn | PwrDwn1, 
        PwrDwnR4 =      PwrDwnEn | PwrDwn1 | PwrDwn0, 
        PwrDwnMask =    PwrDwnEn | PwrDwn1 | PwrDwn0, 
 
        // Amplifier Gain Selection
        GainBit0 =      0x00020000, 
        GainBit1 =      0x00040000, 
        GainBit2 =      0x00080000, 
        GainEn =        0x00100000, 
        GainMask =      GainBit0 | GainBit1 | GainBit2 | GainEn, 
        Gain1 = GainEn,                                   
        Gain2 = GainEn |                       GainBit0,  
        Gain3 = GainEn |            GainBit1,             
        Gain4 = GainEn |            GainBit1 | GainBit0,  
        Gain5 = GainEn | GainBit2,                        
        Gain6 = GainEn | GainBit2 |            GainBit0,  
        Gain7 = GainEn | GainBit2 | GainBit1,             
        Gain8 = GainEn | GainBit2 | GainBit1 | GainBit0,  
      };
 
      static const std::map<ModeFlag, std::string> &modeFlagToStringMap();
 
      static const std::map<std::string, Converter::ModeFlag> &stringToModeFlagMap();
 
 
      typedef Flags<ModeFlag, long> Mode; 
 
      enum {
        hasFrequency      = 0x00000001, 
        hasReference      = 0x00000002, 
        hasResolution     = 0x00000004, 
        hasBipolar        = 0x00000008, 
        hasRange          = 0x00000010, 
        hasSetFrequency   = 0x00000020, 
        hasSetRange       = 0x00000040, 
        hasSetReference   = 0x00000080, 
        hasSetResolution  = 0x00000100, 
        hasSetBipolar     = 0x00000200, 
        requiresWaitLoop  = 0x00000400, 
        hasClockSelection = 0x00000800, 
        hasModeSetting    = 0x00001000, 
        hasToggle         = 0x00002000, 
        hasReferencePerChannel = 0x00004000, 
      };
 
      enum {
        DefaultReference = 0, 
        InternalReference,    
        VddReference,         
        ExternalReference,    
        // The following references are for converters that have multiple internal reference configurations
        Internal1Reference,   
        Internal2Reference,   
        Internal3Reference,   
        Internal4Reference,   
        UnknownReference = -1 
      };
 
      enum {
        DefaultClock = 0, 
        InternalClock,    
        ExternalClock,    
        UnknownClock = -1 
      };
 
      static constexpr long InvalidValue = LONG_MIN; 
 
      explicit Converter (const std::string &parameters = "");
 
      static Converter *factory (const std::string &deviceName, const std::string &parameters = "");
 
      static void registerConverter (const std::string &deviceName,
                                     std::function<Converter* (const std::string &) > creator,
                                     const std::string &type = "dac",
                                     const std::string &parameters = "");
      struct Info {
        std::string name; 
        std::string type; 
        std::string parameters; 
        Info() = default;
        Info (const std::string &name, const std::string &type, const std::string &parameters)
          : name (name), type (type), parameters (parameters) {}
      };
 
      static std::vector<Info> availableConverters();
 
      virtual ~Converter();
 
      virtual const std::string &deviceName() const;
 
      Type type() const;
 
      virtual unsigned int flags() const;
 
      virtual bool open (IoDevice::OpenMode mode = IoDevice::ReadWrite);
 
      virtual void close();
 
      virtual long read();
 
      virtual bool write (long value);
 
      virtual bool toggle (int channel = -1);
 
      virtual long readChannel (int channel = 0, bool differential = false);
 
      virtual double readValue (int channel = 0, bool differential = false);
 
      virtual double readAverage (int channel = 0, bool differential = false, int count = 8);
 
      virtual double readAverageValue (int channel = 0, bool differential = false, int count = 8);
 
      virtual bool writeChannel (long value, int channel = -1, bool differential = false);
 
      virtual bool writeValue (double value, int channel = -1, bool differential = false);
 
      virtual int numberOfChannels() const;
 
      virtual double digitalToValue (long digitalValue, bool differential = false) const;
 
      virtual double digitalToValue (int channel, long digitalValue, bool differential = false) const;
 
      virtual long valueToDigital (double value, bool differential = false) const;
 
      virtual long valueToDigital (int channel, double value, bool differential = false) const;
 
      virtual void setEnable (bool enable);
 
      virtual bool isEnabled () const;
 
      inline void run();
 
      inline void stop();
 
      virtual long max (bool differential = false) const;
 
      virtual long min (bool differential = false) const;
 
      virtual int resolution() const;
 
      virtual int setResolution (int resolution);
 
      virtual bool isBipolar() const;
 
      virtual bool setBipolar (bool bipolar);
 
      virtual bool setReference (int referenceId, double fsr = 0.0);
 
      virtual bool setReference (int referenceId, int channel, double fsr = 0.0);
 
      virtual int reference() const;
 
      virtual int reference (int channel) const;
 
      virtual double fullScaleRange() const;
 
      virtual double fullScaleRange (int channel) const;
 
      virtual bool setFullScaleRange (double fsr);
 
      virtual bool setFullScaleRange (int channel, double fsr);
 
      virtual long frequency() const;
 
      virtual long setFrequency (long freq);
 
      virtual long range() const;
 
      virtual long setRange (long range);
 
      virtual int clock() const;
 
      virtual bool setClock (int clock);
 
      virtual Mode mode (int channel = 0) const;
 
      virtual bool setMode (Mode m, int channel = -1);
 
      virtual bool setModeFlags (long flags, long mask = -1, int channel = -1);
 
      virtual bool clearModeFlags (long flags, long mask = -1, int channel = -1);
 
    protected:
      class Private;
 
      Converter (Private &dd);
 
    private:
      PIMP_DECLARE_PRIVATE (Converter)
  };
 
  #ifndef DOXYGEN
  inline void Converter::run() {
    setEnable (true);
  }
  inline void Converter::stop() {
    setEnable (false);
  }
  #endif // DOXYGEN
} // namespace Piduino
/* ========================================================================== */