brownies.H

Go to the documentation of this file.

/*
 *  This file is part of the Home2L project.
 *
 *  (C) 2015-2024 Gundolf Kiefer
 *
 *  Home2L is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  Home2L 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 General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with Home2L. If not, see <https://www.gnu.org/licenses/>.
 *
 */
 
 
#ifndef _BROWNIES_
#define _BROWNIES_
 
#include "env.H"
#include "resources.H"
 
 
extern "C" {
#include "avr/interface.h"
}
 
 
// *************************** Basics ******************************************
 
 
#define BR_CONF_DEFAULT_NAME "brownies.conf"
 
 
extern const char *envBrDatabaseFile;   
extern const char *envBrLinkDev;        
 
 
const char *BrStatusStr (EBrStatus s);
 
const char *BrMcuStr (int mcuType, const char *unknown = NULL);
int BrMcuFromStr (const char *mcuStr);
 
 
 
 
 
// ***************** Brownie Feature and Config Records ************************
 
 
// ***** Configuration item descriptor *****
 
 
typedef enum {
  ctUint8,
  ctInt8,
  ctUint16,
  ctVersion,      // special: Version number (stored in TBrFeatureRecord.version*)
  ctFeatures,     // special: Feature information relevant for resources
  ctMcu,          // special: MCU model
  ctFw,           // special: Firmware name (stored in TBrFeatureRecord.fwName)
  ctId,           // special: ID (stored in EEPROM at BR_EEPROM_ID_BASE)
  ctShadesDelay,  // special: Shades delay (byte displayed as seconds)
  ctShadesSpeed   // special: Shades speed (byte displayed as seconds of 100% movement)
} EBrCfgType;
 
 
struct TBrCfgDescriptor {
  const char *key;      // written key
  const char *fmt;      // format for output
  EBrCfgType type;
  int features;         // any of these features must be present, otherwise the variable is ignored
  int ofs;              // offset inside the TBrConfigRecord structure
  const char *help;
};
 
 
extern const TBrCfgDescriptor brCfgDescList[];  
extern const int brCfgDescs;                    
 
 
 
// ***** Feature record to/from string *****
 
uint32_t BrVersionGet (TBrFeatureRecord *featureRecord);
static inline const char *BrVersionGetAsStr (CString *ret, TBrFeatureRecord *featureRecord) { return VersionToStr (ret, BrVersionGet (featureRecord)); }
bool BrVersionFromStr (TBrFeatureRecord *featureRecord, const char *str);
 
const char *BrFeaturesToStr (CString *ret, TBrFeatureRecord *featureRecord);
bool BrFeaturesFromStr (TBrFeatureRecord *featureRecord, const char *str);
 
 
 
 
 
// *************************** CBrownie ****************************************
 
 
class CBrownie {
  public:
 
 
    CBrownie () { features = 0; Clear (); }
    ~CBrownie () { Clear (); }
 
    void Clear ();
 
    void SetId (const char *id) { strncpy (idRecord, id, sizeof (idRecord)); idRecord[sizeof (idRecord) - 1] = '\0'; }
    void SetFeatureRecord (TBrFeatureRecord *_featureRecord) { featureRecord = *_featureRecord; }
    void SetConfigRecord (TBrConfigRecord *_configRecord) { configRecord = *_configRecord; }
    void SetDatabaseString (const char *s) { databaseString.Set (s); }
 
    bool SetFromStr (const char *str, CString *ret = NULL);
    const char *ToStr (CString *ret, bool withIdentification = true, bool withVersionInfo = true);
 
 
    int Adr () { return configRecord.adr; }
    const char *Id () { return idRecord; }
    TBrFeatureRecord *FeatureRecord () { return &featureRecord; }
    TBrConfigRecord *ConfigRecord () { return &configRecord; }
 
    const char *DatabaseString () { return databaseString.Get (); }
 
 
    bool IsValid () { return configRecord.adr != 0; }
    bool HasFeatures () { return featureRecord.features || featureRecord.gpiPresence || featureRecord.gpoPresence; }
 
    bool HasDeviceFeatures () { return featureRecord.magic == BR_MAGIC; }
    bool HasDeviceConfig () { return configRecord.magic == BR_MAGIC; }
 
 
    bool IsCompatible (const char *_databaseString);
 
    bool UpdateFromDevice (class CBrownieLink *link);
 
 
  protected:
    const char *GetOptValue (CString *ret, int optIdx);
    bool SetOptValue (int optIdx, const char *str);
    void CheckDeviceForResources (CBrownieLink *link);
 
    // Database and hardware info ...
    TBrIdRecord idRecord;
    TBrFeatureRecord featureRecord;
    TBrConfigRecord configRecord;
    CString databaseString;
 
    // Resources (with interface calls for @ref CBrownieSet) ...
    friend class CBrownieSet;
    friend class CBrRcDriver;
 
    class CBrFeature *featureList[8]; // array of device feature objects (use 'sizeof(featureList)' to avoid buffer overflows)
    int features;                     // number of device features
    bool deviceChecked;               // device has been checked, either with or without success:
                                      // if true, but HasDeviceFeatures() or HasDeviceConfig() returns false, it should not be checked again but treated as unusable
    bool unknownChanges;              // There was a failure reading the "changed" register, we may have missed changes
 
    void RegisterAllResources (class CRcDriver *rcDriver, class CBrownieLink *link = NULL);
      // Register all resources and create device feature objects;
      // This is done based on the database, However, later, on the first
      // invocation of 'Iterate()', the features of the real hardware should be validated against
      // this for the case the database is out of date.
      // If 'link != NULL' and the 'features' configuration option is not set in the database,
      // the device is checked immediately.
      // If 'link == NULL', the 'features' configuration option must be set in the database,
      // otherwise, no resources will be registered for the device.
    unsigned Iterate (class CBrownieLink *link, bool fast);
      // Check the "changed" register BR_REG_CHANGED and do all necessary actions.
      //
      // 'link' may be 'NULL', in which case time-outs should be checked and resources
      // be invalidated accordingly.
      //
      // If 'fast' is 'true', a notification was received for this
      // subnet. Hence, we must only read registers of time-critical features
      // (= those with a set "changed" bit) to save time in favour of some other
      // node that caused the notification.
      //
      // Returns the contents of register BR_REG_CHANGED (presently only
      // relevant for hubs and their BR_CHANGED_CHILD bit, other may return 0).
      //
    void CheckExpiration ();
      // Invalidate all expireable resources on expiration
    void DriveValue (class CBrownieLink *link, class CResource *rc, class CRcValueState *vs);
      // Unlike CBrownieSet::DriveValue(), this method is always called from the
      // Brownie thread, so no care of concurrency is necessary.
};
 
 
 
 
 
// *************************** CBrownieSet *************************************
 
 
class CBrownieSet {
  public:
 
 
    CBrownieSet ();
    ~CBrownieSet () { ResourcesDone (); Clear (); }
 
    void Clear ();
 
    CBrownie *Get (const char *id) { int *pAdr = adrMap.Get (id); return pAdr ? Get (*pAdr) : NULL; }
    CBrownie *Get (int adr) { return (adr < 0 || adr > 127) ? NULL : brList[adr]; }
 
    void Set (CBrownie *brownie);   
    CBrownie *Unlink (int adr);     
 
    void Del (int adr);             
 
 
    bool ReadDatabase (const char *fileName = NULL);
    bool WriteDatabase (const char *fileName = NULL);
 
 
    void ResourcesInit (CRcEventDriver *_rcDriver, class CBrownieLink *_rcLink);
    void ResourcesIterate (bool noLink = false, bool noSleep = false);
    void ResourcesDone ();
 
 
  protected:
    CBrownie *brList[128];
    CDictCompact<int> adrMap;
 
    // Resources ...
    class CRcEventDriver *rcDriver;
    class CBrownieLink *rcLink;
    int rcLastCheckedAdr;         // next address to be polled normally (not fast)
    TTicks tLastIterate; // monotonic time of last entry of 'ResourcesIterate ()'
};
 
 
 
 
 
// *************************** CBrownieLink ***********************************
 
 
typedef enum {
  ifNone = 0,     
  ifSocket,       
  ifI2cDev,       
  ifElvI2c,       
  ifEND
} ETwiIfType;
 
 
const char *TwiIfTypeStr (ETwiIfType type);
 
 
enum ESocketOp {
  soSend = 0,     // request: head + data (<bytes>),  reply: head
  soFetch,        // request: head,                   reply: head + data <bytes>
  soStatReset,    // request: head,   no reply
  soStatFetch     // request: head,                   reply: head + string without \0 <bytes>
};
 
 
struct TSocketHeader {
  ESocketOp op      : 3;    // Socket operation
  EBrStatus status  : 5;    // Status (for 'soSend', 'soFetch')
  int adr           : 8;    // TWI address (for 'soSend', 'soFetch')
  int bytes         : 16;   // amount of the remaining data (exception: 'soFetch' request, where this is the desired reply bytes)
};
 
 
class CBrownieLink {
  public:
 
 
    CBrownieLink ();
    ~CBrownieLink () { Close (); }
 
    EBrStatus Open (const char *devName = NULL);
    EBrStatus Reopen () { TwiOpen (false); return status; }
    void Close () { ServerStop (); TwiClose (); }
 
    const char *IfName () { return twiIfName.Get (); }
    ETwiIfType IfType () { return twiIfType; }
 
 
    TBrRequest *Request () { return &request; }   
    TBrReply *Reply () { return &reply; }         
    EBrStatus Status () { return status; }        
 
 
    void ClearBus ();
    void Flush (int adr);
 
    EBrStatus SendRequest (int adr, bool noResend = false);
 
    EBrStatus FetchReply (int adr, bool noResend = false);
 
    EBrStatus Communicate (int adr, bool noResend = false);
 
 
    EBrStatus CheckDevice (int adr, CBrownie *brownie = NULL);
 
    EBrStatus RegRead (int adr, uint8_t reg, uint8_t *retVal, bool noResend = false);
    EBrStatus RegRead (CBrownie *brownie, uint8_t reg, uint8_t *retVal, bool noResend = false) { return RegRead (brownie->Adr (), reg, retVal, noResend); }
    uint8_t RegReadNext (EBrStatus *status, int adr, uint8_t reg, bool noResend = false);
    uint8_t RegReadNext (EBrStatus *status, CBrownie *brownie, uint8_t reg, bool noResend = false) { return RegReadNext (status, brownie->Adr (), reg, noResend); }
    EBrStatus RegWrite (int adr, uint8_t reg, uint8_t val, bool noResend = false);
    EBrStatus RegWrite (CBrownie *brownie, uint8_t reg, uint8_t val, bool noResend = false) { return RegWrite (brownie->Adr (), reg, val, noResend); }
    void RegWriteNext (EBrStatus *status, int adr, uint8_t reg, uint8_t val, bool noResend = false);
    void RegWriteNext (EBrStatus *status, CBrownie *brownie, uint8_t reg, uint8_t val, bool noResend = false) { return RegWriteNext (status, brownie->Adr (), reg, val, noResend); }
 
    EBrStatus MemRead (int adr, unsigned memAdr, int bytes, uint8_t *retData, bool printProgress = false);
    EBrStatus MemWrite (int adr, unsigned memAdr, int bytes, uint8_t *data, bool printProgress = false);
 
 
    void StatisticsReset (bool local = false);
    const char *StatisticsStr (CString *ret, bool local = false);
    void StatisticsAddIterateTimes (TTicks tCycle, TTicks tFastPoll, TTicks tSlowPoll);
 
 
    bool ServerStart ();
    void ServerStop ();
    bool ServerIterate (TTicks maxSleepTime = -1);
 
 
  protected:
    void TwiOpen (bool warn);
    void TwiClose ();
    EBrStatus TwiSetAdr (int _twiAdr);    // Helper for TwiSend() and TwiFetch()
    EBrStatus TwiSend (int adr, const void *buf, int bytes);
    EBrStatus TwiFetch (int adr, void *buf, int bytes);
 
    CString twiIfName;
    ETwiIfType twiIfType;
    int twiFd, twiAdr;
 
    TBrRequest request;
    TBrReply reply;
    EBrStatus status;
 
    // Statistics ...
    TTicks tLastStatisticsReset;
    int requests, requestRetries[brEND], requestFailures[brEND];
    int replies, replyRetries[brEND], replyFailures[brEND];
 
    int rcIterations;
    TTicks rcTSumCycle, rcTSumFastPoll, rcTSumSlowPoll;
    TTicks rcTCycleMin, rcTCycleMax, rcTFastPollMin, rcTFastPollMax, rcTSlowPollMin, rcTSlowPollMax;
 
    // Socket server ...
    int sockListenFd;       // listening socket (or <0, if none activated)
    int sockClientFd;       // currently connected socket client (or <0, if none is connected)
    TSocketHeader sockHead; // buffer for received header
    uint8_t *sockData;      // buffer for received data
    size_t sockRxBytes;     // number of received bytes (header + data)
};
 
 
 
 
 
#endif // _BROWNIES_