version entry for 5.4.14

Fix validated

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: DCC-EX
+patreon: dccex

.github/workflows/label-sponsors.yml

@@ -0,0 +1,14 @@
+name: Label sponsors
+on:
+  pull_request:
+    types: [opened]
+  issues:
+    types: [opened]
+jobs:
+  build:
+    name: is-sponsor-label
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JasonEtco/is-sponsor-label-action@v1.2.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/sha.yml

@@ -24,10 +24,11 @@ jobs:
           sha=$(git rev-parse --short "$GITHUB_SHA")
           echo "#define GITHUB_SHA \"$sha\"" > GITHUB_SHA.h
 
-      - uses: EndBug/add-and-commit@v4 # You can change this to use a specific version
+      - uses: EndBug/add-and-commit@v8 # You can change this to use a specific version
         with:
           add: 'GITHUB_SHA.h'
           message: 'Committing a SHA'
+          commit: --amend
 
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Leave this line unchanged

.gitignore

@@ -7,11 +7,11 @@ Release/*
 .pio/
 .vscode/
 config.h
-.vscode/extensions.json
-mySetup.h
 mySetup.cpp
-myAutomation.h
+myHal.cpp
 myFilter.cpp
-myAutomation.h
-myFilter.cpp
-myLayout.h
+my*.h
+!my*.example.h
+compile_commands.json
+newcode.txt.old
+UserAddin.txt

.vscode/extensions.json

@@ -1,7 +0,0 @@
-{
-    // See http://go.microsoft.com/fwlink/?LinkId=827846
-    // for the documentation about the extensions.json format
-    "recommendations": [
-        "platformio.platformio-ide"
-    ]
-}

.vscode/settings.json

@@ -1,12 +0,0 @@
-{
-    "files.associations": {
-        "array": "cpp",
-        "deque": "cpp",
-        "string": "cpp",
-        "unordered_map": "cpp",
-        "vector": "cpp",
-        "string_view": "cpp",
-        "initializer_list": "cpp",
-        "cstdint": "cpp"
-    }
-}

CamParser.cpp

@@ -0,0 +1,95 @@
+
+//sensorCAM parser.cpp version 3.03  Sep 2024
+#include "CamParser.h"
+#include "FSH.h"
+#include "IO_EXSensorCAM.h"
+
+#ifndef SENSORCAM_VPIN       //define CAM vpin (700?) in config.h
+#define SENSORCAM_VPIN 0     
+#endif
+#define CAM_VPIN SENSORCAM_VPIN
+#ifndef SENSORCAM2_VPIN 
+#define SENSORCAM2_VPIN CAM_VPIN
+#endif
+#ifndef SENSORCAM3_VPIN 
+#define SENSORCAM3_VPIN 0
+#endif
+const int CAMVPINS[] = {CAM_VPIN,SENSORCAM_VPIN,SENSORCAM2_VPIN,SENSORCAM3_VPIN};
+const int16_t ver=30177;
+const int16_t ve =2899;
+
+VPIN EXSensorCAM::CAMBaseVpin = CAM_VPIN;
+
+bool CamParser::parseN(Print * stream, byte paramCount, int16_t p[]) {
+  (void)stream;  // probably unused parameter 
+  VPIN vpin=EXSensorCAM::CAMBaseVpin;   //use current CAM selection
+
+  if (paramCount==0) { 
+    DIAG(F("vpin:%d EXSensorCAMs defined at Vpins #1@ %d #2@ %d #3@ %d"),vpin,CAMVPINS[1],CAMVPINS[2],CAMVPINS[3]);
+    return true; 
+  }
+  uint8_t camop=p[0]; // cam oprerator 
+  int param1=0;
+  int16_t param3=9999;   // =0 could invoke parameter changes. & -1 gives later errors
+
+  if(camop=='C'){ 
+    if(p[1]>=100) EXSensorCAM::CAMBaseVpin=p[1];
+    if(p[1]<4) EXSensorCAM::CAMBaseVpin=CAMVPINS[p[1]];
+    DIAG(F("CAM base Vpin: %c %d "),p[0],EXSensorCAM::CAMBaseVpin);
+    return true;
+  }
+  if (camop<100) {               //switch CAM# if p[1] dictates
+    if(p[1]>=100 && p[1]<400) {  //limits to CAM# 1 to 3 for now
+      vpin=CAMVPINS[p[1]/100];
+      EXSensorCAM::CAMBaseVpin=vpin;     
+      DIAG(F("switching to CAM %d baseVpin:%d"),p[1]/100,vpin); 
+      p[1]=p[1]%100;             //strip off CAM #
+    } 
+  }
+  if (EXSensorCAM::CAMBaseVpin==0) return false; // no cam defined 
+
+  
+      // send UPPER case to sensorCAM to flag binary data from a DCCEX-CS parser  
+  switch(paramCount) {    
+    case 1:                          //<N ver> produces '^'
+      if((p[0] == ve) || (p[0] == ver) || (p[0] == 'V')) camop='^'; 
+      if (STRCHR_P((const char *)F("EFGMQRVW^"),camop) == nullptr) return false;
+      if (camop=='Q') param3=10;     //<NQ> for activation state of all 10 banks of sensors
+      if (camop=='F') camop=']';     //<NF> for Reset/Finish webCAM.
+      break;    // F Coded as ']' else conflicts with <Nf %%>
+    
+    case 2:                          //<N camop p1>  
+      if (STRCHR_P((const char *)F("ABFILMNOPQRSTUV"),camop)==nullptr) return false;
+      param1=p[1];
+      break;
+    
+    case 3:              //<N vpin rowY colx > or <N cmd p1 p2>
+      camop=p[0];
+      if (p[0]>=100) {   //vpin - i.e. NOT 'A' through 'Z'
+        if (p[1]>236 || p[1]<0) return false;     //row
+        if (p[2]>316 || p[2]<0) return false;     //column
+        camop=0x80;      // special 'a' case for IO_SensorCAM
+        vpin = p[0];
+      }else if (STRCHR_P((const char *)F("IJMNT"),camop) == nullptr) return false; 
+      param1 = p[1];  
+      param3 = p[2];
+      break;
+    
+    case 4:          //<N a id row col> 
+      if (camop!='A') return false;          //must start with 'a' 
+      if (p[3]>316 || p[3]<0) return false;
+      if (p[2]>236 || p[2]<0) return false;
+      if (p[1]>97 || p[1]<0) return false;   //treat as bsNo.
+      vpin = vpin + (p[1]/10)*8 + p[1]%10;   //translate p[1]
+      camop=0x80;    // special 'a' case for IO_SensorCAM
+      param1=p[2];   // row
+      param3=p[3];   // col
+      break;
+
+    default:
+      return false;
+  }
+  DIAG(F("CamParser: %d %c %d %d"),vpin,camop,param1,param3);
+  IODevice::writeAnalogue(vpin,param1,camop,param3);
+  return true;
+}

CamParser.h

@@ -0,0 +1,12 @@
+#ifndef CamParser_H
+#define CamParser_H
+#include <Arduino.h>
+#include "IODevice.h"
+
+class CamParser {
+   public:
+   static bool parseN(Print * stream, byte paramCount, int16_t p[]);
+};
+
+
+#endif

CommandDistributor.cpp

@@ -1,6 +1,10 @@
 /*
- *  © 2020,Gregor Baues,  Chris Harlow. All rights reserved.
- *  
+ *  © 2022 Harald Barth
+ *  © 2020-2021 Chris Harlow
+ *  © 2020 Gregor Baues
+ *  © 2022 Colin Murdoch
+ *  All rights reserved.
+ *
  *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
@@ -16,16 +20,360 @@
  *  You should have received a copy of the GNU General Public License
  *  along with CommandStation.  If not, see <https://www.gnu.org/licenses/>.
  */
+
 #include <Arduino.h>
 #include "CommandDistributor.h"
+#include "SerialManager.h"
 #include "WiThrottle.h"
+#include "DIAG.h"
+#include "defines.h"
+#include "DCCWaveform.h"
+#include "DCC.h"
+#include "TrackManager.h"
+#include "StringFormatter.h"
 
-DCCEXParser * CommandDistributor::parser=0; 
+// variables to hold clock time
+int16_t lastclocktime;
+int8_t lastclockrate;
 
-void  CommandDistributor::parse(byte clientId,byte * buffer, RingStream * streamer) {
- if (buffer[0] == '<')  {
-    if (!parser) parser = new DCCEXParser();
-    parser->parse(streamer, buffer, streamer); 
-  }
-  else WiThrottle::getThrottle(clientId)->parse(streamer, buffer);
+
+#if WIFI_ON || ETHERNET_ON || defined(SERIAL1_COMMANDS) || defined(SERIAL2_COMMANDS) || defined(SERIAL3_COMMANDS) || defined(SERIAL4_COMMANDS) || defined(SERIAL5_COMMANDS) || defined(SERIAL6_COMMANDS)
+// use a buffer to allow broadcast
+StringBuffer * CommandDistributor::broadcastBufferWriter=new StringBuffer();
+template<typename... Targs> void CommandDistributor::broadcastReply(clientType type, Targs... msg){
+  broadcastBufferWriter->flush();
+  StringFormatter::send(broadcastBufferWriter, msg...);
+  broadcastToClients(type);
 }
+#else
+// on a single USB connection config, write direct to Serial and ignore flush/shove
+template<typename... Targs> void CommandDistributor::broadcastReply(clientType type, Targs... msg){
+  (void)type; //shut up compiler warning
+  StringFormatter::send(&USB_SERIAL, msg...);
+}
+#endif 
+
+#ifdef CD_HANDLE_RING
+  // wifi or ethernet ring streams with multiple client types
+  RingStream *  CommandDistributor::ring=0;
+  CommandDistributor::clientType  CommandDistributor::clients[8]={
+    NONE_TYPE,NONE_TYPE,NONE_TYPE,NONE_TYPE,NONE_TYPE,NONE_TYPE,NONE_TYPE,NONE_TYPE};
+
+// Parse is called by Withrottle or Ethernet interface to determine which
+// protocol the client is using and call the appropriate part of dcc++Ex
+void  CommandDistributor::parse(byte clientId,byte * buffer, RingStream * stream) {
+  if (Diag::WIFI && Diag::CMD)
+    DIAG(F("Parse C=%d T=%d B=%s"),clientId, clients[clientId], buffer);
+  ring=stream;
+
+  // First check if the client is not known
+  // yet and in that case determinine type
+  // NOTE: First character of transmission determines if this
+  // client is using the DCC++ protocol where all commands start
+  // with '<'
+  if (clients[clientId] == NONE_TYPE) {
+    if (buffer[0] == '<')
+      clients[clientId]=COMMAND_TYPE;
+    else
+      clients[clientId]=WITHROTTLE_TYPE;
+  }
+
+  // mark buffer that is sent to parser
+  ring->mark(clientId);
+
+  // When type is known, send the string
+  // to the right parser
+  if (clients[clientId] == COMMAND_TYPE) {
+    DCCEXParser::parse(stream, buffer, ring);
+  } else if (clients[clientId] == WITHROTTLE_TYPE) {
+    WiThrottle::getThrottle(clientId)->parse(ring, buffer);
+  }
+
+  if (ring->peekTargetMark()!=RingStream::NO_CLIENT) {
+    // The commit call will either write the length bytes
+    // OR rollback to the mark because the reply is empty
+    // or the command generated more output than fits in
+    // the buffer
+    if (!ring->commit()) {
+      DIAG(F("OUTBOUND FULL processing cmd:%s"),buffer);
+    }
+  } else {
+    DIAG(F("CD parse: was alredy committed")); //XXX Could have been committed by broadcastClient?!
+  }
+}
+
+void CommandDistributor::forget(byte clientId) {
+  if (clients[clientId]==WITHROTTLE_TYPE) WiThrottle::forget(clientId);
+  clients[clientId]=NONE_TYPE;
+  if (virtualLCDClient==clientId) virtualLCDClient=RingStream::NO_CLIENT;
+}
+#endif 
+
+// This will not be called on a uno 
+void CommandDistributor::broadcastToClients(clientType type) {
+
+  byte rememberClient;
+  (void)rememberClient; // shut up compiler warning
+
+  // Broadcast to Serials
+  if (type==COMMAND_TYPE) SerialManager::broadcast(broadcastBufferWriter->getString());
+
+#ifdef CD_HANDLE_RING
+  // If we are broadcasting from a wifi/eth process we need to complete its output
+  // before merging broadcasts in the ring, then reinstate it in case
+  // the process continues to output to its client.
+  if (ring) {
+    if ((rememberClient = ring->peekTargetMark()) != RingStream::NO_CLIENT) {
+      //DIAG(F("CD precommit client %d"), rememberClient);
+      ring->commit();
+    }
+    // loop through ring clients
+    for (byte clientId=0; clientId<sizeof(clients); clientId++) {
+      if (clients[clientId]==type)  {
+	//DIAG(F("CD mark client %d"), clientId);
+	ring->mark(clientId);
+	ring->print(broadcastBufferWriter->getString());
+	//DIAG(F("CD commit client %d"), clientId);
+	ring->commit();
+      }
+    }
+    // at this point ring is committed (NO_CLIENT) either from
+    // 4 or 13 lines above.
+    if (rememberClient != RingStream::NO_CLIENT) {
+      //DIAG(F("CD postmark client %d"), rememberClient);
+      ring->mark(rememberClient);
+    }
+  }
+#endif
+}
+
+// Public broadcast functions below 
+void  CommandDistributor::broadcastSensor(int16_t id, bool on ) {
+  broadcastReply(COMMAND_TYPE, F("<%c %d>\n"), on?'Q':'q', id);
+}
+
+void  CommandDistributor::broadcastTurnout(int16_t id, bool isClosed ) {
+  // For DCC++ classic compatibility, state reported to JMRI is 1 for thrown and 0 for closed;
+  // The string below contains serial and Withrottle protocols which should
+  // be safe for both types.
+  broadcastReply(COMMAND_TYPE, F("<H %d %d>\n"),id, !isClosed);
+#ifdef CD_HANDLE_RING
+  broadcastReply(WITHROTTLE_TYPE, F("PTA%c%d\n"), isClosed?'2':'4', id);
+#endif
+}
+
+void CommandDistributor::broadcastTurntable(int16_t id, uint8_t position, bool moving) {
+  broadcastReply(COMMAND_TYPE, F("<I %d %d %d>\n"), id, position, moving);
+}
+
+void  CommandDistributor::broadcastClockTime(int16_t time, int8_t rate) {
+  // The JMRI clock command is of the form : PFT65871<;>4
+  // The CS broadcast is of the form "<jC mmmm nn" where mmmm is time minutes and dd speed
+  // The string below contains serial and Withrottle protocols which should
+  // be safe for both types.
+  broadcastReply(COMMAND_TYPE, F("<jC %d %d>\n"),time, rate);
+#ifdef CD_HANDLE_RING
+  broadcastReply(WITHROTTLE_TYPE, F("PFT%l<;>%d\n"), (int32_t)time*60, rate);
+#endif
+}
+
+void CommandDistributor::setClockTime(int16_t clocktime, int8_t clockrate, byte opt) {
+  // opt - case 1 save the latest time if changed
+  //       case 2 broadcast the time when requested
+  //       case 3 display latest time
+  switch (opt)
+  {
+    case 1:
+      if (clocktime != lastclocktime){
+        // CAH. DIAG removed because LCD does it anyway. 
+        LCD(6,F("Clk Time:%d Sp %d"), clocktime, clockrate);
+        // look for an event for this time
+        RMFT2::clockEvent(clocktime,1);
+        // Now tell everyone else what the time is.
+        CommandDistributor::broadcastClockTime(clocktime, clockrate);
+        lastclocktime = clocktime;
+        lastclockrate = clockrate;
+      }
+      return;
+
+    case 2:
+      CommandDistributor::broadcastClockTime(lastclocktime, lastclockrate);
+      return;
+  }
+ 
+}
+
+int16_t CommandDistributor::retClockTime() {
+  return lastclocktime;
+}
+
+void  CommandDistributor::broadcastLoco(byte slot) {
+  DCC::LOCO * sp=&DCC::speedTable[slot];
+  broadcastReply(COMMAND_TYPE, F("<l %d %d %d %l>\n"), sp->loco,slot,sp->speedCode,sp->functions);
+#ifdef SABERTOOTH
+  if (Serial2 && sp->loco == SABERTOOTH) {
+    static uint8_t rampingmode = 0;
+    bool direction = (sp->speedCode & 0x80) !=0; // true for forward
+    int32_t speed = sp->speedCode & 0x7f;
+    if (speed == 1) { // emergency stop
+      if (rampingmode != 1) {
+	rampingmode = 1;
+	Serial2.print("R1: 0\r\n");
+	Serial2.print("R2: 0\r\n");
+      }
+      Serial2.print("MD: 0\r\n");
+    } else {
+      if (speed != 0) {
+        // speed is here 2 to 127
+	speed = (speed - 1) * 1625 / 100;
+	speed = speed * (direction ? 1 : -1);
+	// speed is here -2047 to 2047
+      }
+      if (rampingmode != 2) {
+	rampingmode = 2;
+	Serial2.print("R1: 2047\r\n");
+	Serial2.print("R2: 2047\r\n");
+      }
+      Serial2.print("M1: ");
+      Serial2.print(speed);
+      Serial2.print("\r\n");
+      Serial2.print("M2: ");
+      Serial2.print(speed);
+      Serial2.print("\r\n");
+    }
+  }
+#endif
+#ifdef CD_HANDLE_RING
+  WiThrottle::markForBroadcast(sp->loco);
+#endif
+}
+
+void  CommandDistributor::broadcastForgetLoco(int16_t loco) {
+  broadcastReply(COMMAND_TYPE, F("<l %d 0 1 0>\n<- %d>\n"), loco,loco);
+}
+
+void  CommandDistributor::broadcastPower() {
+  char pstr[] = "? x";
+  for(byte t=0; t<TrackManager::MAX_TRACKS; t++)
+    if (TrackManager::getPower(t, pstr))
+      broadcastReply(COMMAND_TYPE, F("<p%s>\n"),pstr);
+
+  byte trackcount=0;
+  byte oncount=0;
+  byte offcount=0;
+  for(byte t=0; t<TrackManager::MAX_TRACKS; t++) {
+    if (TrackManager::isActive(t)) {
+      trackcount++;
+      // do not call getPower(t) unless isActive(t)!
+      if (TrackManager::getPower(t) == POWERMODE::ON)
+	oncount++;
+      else
+	offcount++;
+    }
+  }
+  //DIAG(F("t=%d on=%d off=%d"), trackcount, oncount, offcount);
+
+  char state='2';
+  if (oncount==0 || offcount == trackcount)
+    state = '0';
+  else if (oncount == trackcount) {
+    state = '1';
+  }
+
+  if (state != '2')
+    broadcastReply(COMMAND_TYPE, F("<p%c>\n"),state);
+
+  // additional info about MAIN, PROG and JOIN
+  bool main=TrackManager::getMainPower()==POWERMODE::ON;
+  bool prog=TrackManager::getProgPower()==POWERMODE::ON;
+  bool join=TrackManager::isJoined();
+  //DIAG(F("m=%d p=%d j=%d"), main, prog, join);
+  const FSH * reason=F("");
+  if (join) {
+    reason = F(" JOIN"); // with space at start so we can append without space
+    broadcastReply(COMMAND_TYPE, F("<p1%S>\n"),reason);
+  } else {
+    if (main) {
+      //reason = F("MAIN");
+      broadcastReply(COMMAND_TYPE, F("<p1 MAIN>\n"));
+    }
+    if (prog) {
+      //reason = F("PROG");
+      broadcastReply(COMMAND_TYPE, F("<p1 PROG>\n"));
+    }
+  }
+#ifdef CD_HANDLE_RING
+  // send '1' if all main are on, otherwise global state (which in that case is '0' or '2')
+  broadcastReply(WITHROTTLE_TYPE, F("PPA%c\n"), main?'1': state);
+#endif
+
+  LCD(2,F("Power %S%S"),state=='1'?F("On"): ( state=='0'? F("Off") : F("SC") ),reason);
+}
+
+void CommandDistributor::broadcastRaw(clientType type, char * msg) {
+  broadcastReply(type, F("%s"),msg);
+}
+
+void CommandDistributor::broadcastMessage(char * message) {
+  broadcastReply(COMMAND_TYPE, F("<m \"%s\">\n"),message);
+  broadcastReply(WITHROTTLE_TYPE, F("Hm%s\n"),message);
+}
+
+void CommandDistributor::broadcastTrackState(const FSH* format, byte trackLetter, const FSH *modename, int16_t dcAddr) {
+  broadcastReply(COMMAND_TYPE, format, trackLetter, modename, dcAddr);
+}
+
+void  CommandDistributor::broadcastRouteState(int16_t routeId, byte state ) {
+  broadcastReply(COMMAND_TYPE, F("<jB %d %d>\n"),routeId,state);
+}
+
+void  CommandDistributor::broadcastRouteCaption(int16_t routeId, const FSH* caption ) {
+  broadcastReply(COMMAND_TYPE, F("<jB %d \"%S\">\n"),routeId,caption);
+}
+
+Print * CommandDistributor::getVirtualLCDSerial(byte screen, byte row) {
+  Print * stream=virtualLCDSerial;
+  #ifdef  CD_HANDLE_RING
+  rememberVLCDClient=RingStream::NO_CLIENT;
+  if (!stream && virtualLCDClient!=RingStream::NO_CLIENT) {
+    // If we are broadcasting from a wifi/eth process we need to complete its output
+    // before merging broadcasts in the ring, then reinstate it in case
+    // the process continues to output to its client.
+    if ((rememberVLCDClient = ring->peekTargetMark()) != RingStream::NO_CLIENT) {
+      ring->commit();
+    }
+    ring->mark(virtualLCDClient);   
+    stream=ring; 
+  }
+  #endif
+  if (stream) StringFormatter::send(stream,F("<@ %d %d \""), screen,row);
+  return stream;  
+}
+
+void CommandDistributor::commitVirtualLCDSerial() {
+  #ifdef  CD_HANDLE_RING
+  if (virtualLCDClient!=RingStream::NO_CLIENT) {
+    StringFormatter::send(ring,F("\">\n"));
+    ring->commit();
+    if (rememberVLCDClient!=RingStream::NO_CLIENT) ring->mark(rememberVLCDClient);
+    return;  
+   }
+  #endif
+  StringFormatter::send(virtualLCDSerial,F("\">\n"));  
+}
+
+void CommandDistributor::setVirtualLCDSerial(Print * stream) {
+  #ifdef  CD_HANDLE_RING
+  virtualLCDClient=RingStream::NO_CLIENT;
+  if (stream && stream->availableForWrite()==RingStream::THIS_IS_A_RINGSTREAM) {
+     virtualLCDClient=((RingStream *) stream)->peekTargetMark();
+     virtualLCDSerial=nullptr;
+     return;
+  }      
+    #endif
+  virtualLCDSerial=stream;
+}
+
+Print* CommandDistributor::virtualLCDSerial=&USB_SERIAL;
+byte CommandDistributor::virtualLCDClient=0xFF;
+byte CommandDistributor::rememberVLCDClient=0;

CommandDistributor.h

@@ -1,6 +1,11 @@
 /*
- *  © 2020,Gregor Baues,  Chris Harlow. All rights reserved.
- *  
+ *  © 2022 Harald Barth
+ *  © 2020-2021 Chris Harlow
+ *  © 2020 Gregor Baues
+ *  © 2022 Colin Murdoch
+ * 
+ *  All rights reserved.
+ *
  *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
@@ -20,13 +25,52 @@
 #define CommandDistributor_h
 #include "DCCEXParser.h"
 #include "RingStream.h"
+#include "StringBuffer.h"
+#include "defines.h"
+#include "EXRAIL2.h"
+
+#if WIFI_ON | ETHERNET_ON 
+  // Command Distributor must handle a RingStream of clients
+  #define CD_HANDLE_RING
+#endif 
 
 class CommandDistributor {
-
-public :
-  static void parse(byte clientId,byte* buffer, RingStream * streamer);
+public:
+  enum clientType: byte {NONE_TYPE,COMMAND_TYPE,WITHROTTLE_TYPE};
 private:
-   static DCCEXParser * parser;
+  static void broadcastToClients(clientType type);
+  static StringBuffer * broadcastBufferWriter;
+  #ifdef CD_HANDLE_RING
+    static RingStream * ring;
+    static clientType clients[8];
+  #endif
+public :
+  static void parse(byte clientId,byte* buffer, RingStream * ring);
+  static void broadcastLoco(byte slot);
+  static void broadcastForgetLoco(int16_t loco);
+  static void broadcastSensor(int16_t id, bool value);
+  static void broadcastTurnout(int16_t id, bool isClosed);
+  static void broadcastTurntable(int16_t id, uint8_t position, bool moving);
+  static void broadcastClockTime(int16_t time, int8_t rate);
+  static void setClockTime(int16_t time, int8_t rate, byte opt);
+  static int16_t retClockTime();
+  static void broadcastPower();
+  static void broadcastRaw(clientType type,char * msg);
+  static void broadcastTrackState(const FSH* format,byte trackLetter, const FSH* modename, int16_t dcAddr);
+  template<typename... Targs> static void broadcastReply(clientType type, Targs... msg);
+  static void forget(byte clientId);
+  static void broadcastRouteState(int16_t routeId,byte state);
+  static void broadcastRouteCaption(int16_t routeId,const FSH * caption);
+  static void broadcastMessage(char * message);
+  
+  // Handling code for virtual LCD receiver.
+  static Print * getVirtualLCDSerial(byte screen, byte row);
+  static void commitVirtualLCDSerial();
+  static void setVirtualLCDSerial(Print * stream); 
+  private:
+    static Print * virtualLCDSerial;
+    static byte virtualLCDClient;
+    static byte rememberVLCDClient;
 };
 
 #endif

CommandStation-EX.ino

@@ -1,33 +1,38 @@
 ////////////////////////////////////////////////////////////////////////////////////
-//  DCC-EX CommandStation-EX   Please see https://DCC-EX.com 
+//  DCC-EX CommandStation-EX   Please see https://DCC-EX.com
 //
 // This file is the main sketch for the Command Station.
-// 
-// CONFIGURATION: 
+//
+// CONFIGURATION:
 // Configuration is normally performed by editing a file called config.h.
 // This file is NOT shipped with the code so that if you pull a later version
 // of the code, your configuration will not be overwritten.
 //
 // If you used the automatic installer program, config.h will have been created automatically.
-// 
-// To obtain a starting copy of config.h please copy the file config.example.h which is 
-// shipped with the code and may be updated as new features are added. 
-// 
+//
+// To obtain a starting copy of config.h please copy the file config.example.h which is
+// shipped with the code and may be updated as new features are added.
+//
 // If config.h is not found, config.example.h will be used with all defaults.
 ////////////////////////////////////////////////////////////////////////////////////
 
 #if __has_include ( "config.h")
   #include "config.h"
+  #ifndef MOTOR_SHIELD_TYPE
+  #error Your config.h must include a MOTOR_SHIELD_TYPE definition. If you see this warning in spite not having a config.h, you have a buggy preprocessor and must copy config.example.h to config.h
+  #endif
 #else
-  #warning config.h not found. Using defaults from config.example.h 
+  #warning config.h not found. Using defaults from config.example.h
   #include "config.example.h"
 #endif
 
-
 /*
- *  © 2020,2021 Chris Harlow, Harald Barth, David Cutting, 
- *  Fred Decker, Gregor Baues, Anthony W - Dayton  All rights reserved.
- *  
+ *  © 2021 Neil McKechnie
+ *  © 2020-2021 Chris Harlow, Harald Barth, David Cutting,
+ *  Fred Decker, Gregor Baues, Anthony W - Dayton
+ *  © 2023 Nathan Kellenicki
+ *  All rights reserved.
+ *
  *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
@@ -45,11 +50,30 @@
  */
 
 #include "DCCEX.h"
+#include "Display_Implementation.h"
+#ifdef ARDUINO_ARCH_ESP32
+#include "Sniffer.h"
+#include "DCCDecoder.h"
+Sniffer *dccSniffer = NULL;
+bool DCCDecoder::active = false;
+#endif // ARDUINO_ARCH_ESP32
 
-// Create a serial command parser for the USB connection, 
-// This supports JMRI or manual diagnostics and commands
-// to be issued from the USB serial console.
-DCCEXParser serialParser;
+#ifdef CPU_TYPE_ERROR
+#error CANNOT COMPILE - DCC++ EX ONLY WORKS WITH THE ARCHITECTURES LISTED IN defines.h
+#endif
+
+#ifdef WIFI_WARNING
+#warning You have defined that you want WiFi but your hardware has not enough memory to do that, so WiFi DISABLED
+#endif
+#ifdef ETHERNET_WARNING
+#warning You have defined that you want Ethernet but your hardware has not enough memory to do that, so Ethernet DISABLED
+#endif
+#ifdef EXRAIL_WARNING
+#warning You have myAutomation.h but your hardware has not enough memory to do that, so EX-RAIL DISABLED
+#endif
+// compile time check, passwords 1 to 7 chars do not work, so do not try to compile with them at all
+// remember trailing '\0', sizeof("") == 1.
+#define PASSWDCHECK(S) static_assert(sizeof(S) == 1 || sizeof(S) > 8, "Password shorter than 8 chars")
 
 void setup()
 {
@@ -57,97 +81,142 @@ void setup()
 
   // Responsibility 1: Start the usb connection for diagnostics
   // This is normally Serial but uses SerialUSB on a SAMD processor
-  Serial.begin(115200);
+  SerialManager::init();
 
   DIAG(F("License GPLv3 fsf.org (c) dcc-ex.com"));
 
-  CONDITIONAL_LCD_START {
-    // This block is still executed for DIAGS if LCD not in use 
-    LCD(0,F("DCC++ EX v%S"),F(VERSION));
-    LCD(1,F("Lic GPLv3")); 
-    }   
+// If user has defined a startup delay, delay here before starting IO
+#if defined(STARTUP_DELAY)
+  DIAG(F("Delaying startup for %dms"), STARTUP_DELAY);
+  delay(STARTUP_DELAY);
+#endif
+
+// Initialise HAL layer before reading EEprom or setting up MotorDrivers 
+  IODevice::begin();
+
+  // As the setup of a motor shield may require a read of the current sense input from the ADC,
+  // let's make sure to initialise the ADCee class!
+  ADCee::begin();
+  // Set up MotorDrivers early to initialize all pins
+  TrackManager::Setup(MOTOR_SHIELD_TYPE);
+
+  DISPLAY_START (
+    // This block is still executed for DIAGS if display not in use
+    LCD(0,F("DCC-EX v" VERSION));
+    LCD(1,F("Lic GPLv3"));
+  );
 
   // Responsibility 2: Start all the communications before the DCC engine
   // Start the WiFi interface on a MEGA, Uno cannot currently handle WiFi
   // Start Ethernet if it exists
+#ifndef ARDUINO_ARCH_ESP32
 #if WIFI_ON
-  WifiInterface::setup(WIFI_SERIAL_LINK_SPEED, F(WIFI_SSID), F(WIFI_PASSWORD), F(WIFI_HOSTNAME), IP_PORT, WIFI_CHANNEL);
+  PASSWDCHECK(WIFI_PASSWORD); // compile time check
+  WifiInterface::setup(WIFI_SERIAL_LINK_SPEED, F(WIFI_SSID), F(WIFI_PASSWORD), F(WIFI_HOSTNAME), IP_PORT, WIFI_CHANNEL, WIFI_FORCE_AP);
 #endif // WIFI_ON
+#else
+  // ESP32 needs wifi on always
+  PASSWDCHECK(WIFI_PASSWORD); // compile time check
+  WifiESP::setup(WIFI_SSID, WIFI_PASSWORD, WIFI_HOSTNAME, IP_PORT, WIFI_CHANNEL, WIFI_FORCE_AP);
+#endif // ARDUINO_ARCH_ESP32
 
 #if ETHERNET_ON
   EthernetInterface::setup();
 #endif // ETHERNET_ON
-
-  // Responsibility 3: Start the DCC engine.
-  // Note: this provides DCC with two motor drivers, main and prog, which handle the motor shield(s)
-  // Standard supported devices have pre-configured macros but custome hardware installations require
-  //  detailed pin mappings and may also require modified subclasses of the MotorDriver to implement specialist logic.
-  // STANDARD_MOTOR_SHIELD, POLOLU_MOTOR_SHIELD, FIREBOX_MK1, FIREBOX_MK1S are pre defined in MotorShields.h
-  DCC::begin(MOTOR_SHIELD_TYPE);
-         
-  // Start RMFT (ignored if no automnation)
-  RMFT::begin();
   
-  // Link to and call mySetup() function (if defined in the build in mySetup.cpp).
-  //  The contents will depend on the user's system hardware configuration.
-  //  The mySetup.cpp file is a standard C++ module so has access to all of the DCC++EX APIs.
-  extern __attribute__((weak)) void mySetup();
-  if (mySetup) {
-    mySetup();
-  }
+  // Responsibility 3: Start the DCC engine.
+  DCC::begin();
 
-  // Invoke any DCC++EX commands in the form "SETUP("xxxx");"" found in optional file mySetup.h.  
-  //  This can be used to create turnouts, outputs, sensors etc. throught the normal text commands.
+  // Start RMFT aka EX-RAIL (ignored if no automnation)
+  RMFT::begin();
+
+#ifdef ARDUINO_ARCH_ESP32
+#ifdef BOOSTER_INPUT
+  dccSniffer = new Sniffer(BOOSTER_INPUT);
+#endif // BOOSTER_INPUT
+#endif // ARDUINO_ARCH_ESP32
+
+  // Invoke any DCC++EX commands in the form "SETUP("xxxx");"" found in optional file mySetup.h.
+  //  This can be used to create turnouts, outputs, sensors etc. through the normal text commands.
   #if __has_include ( "mySetup.h")
-        #define SETUP(cmd) serialParser.parse(F(cmd))  
-        #include "mySetup.h"
-        #undef SETUP
-       #endif
-
-  #if defined(LCN_SERIAL)
-      LCN_SERIAL.begin(115200); 
-      LCN::init(LCN_SERIAL);
+    #define SETUP(cmd) DCCEXParser::parse(F(cmd))
+    #include "mySetup.h"
+    #undef SETUP
   #endif
 
-  LCD(3,F("Ready")); 
+  #if defined(LCN_SERIAL)
+  LCN_SERIAL.begin(115200);
+  LCN::init(LCN_SERIAL);
+  #endif
+  LCD(3, F("Ready"));
+  CommandDistributor::broadcastPower();
 }
 
 void loop()
 {
+#ifdef ARDUINO_ARCH_ESP32
+#ifdef BOOSTER_INPUT
+  static bool oldactive = false;
+  if (dccSniffer) {
+    bool newactive = dccSniffer->inputActive();
+    if (oldactive != newactive) {
+      RMFT2::railsyncEvent(newactive);
+      oldactive = newactive;
+    }
+    DCCPacket p = dccSniffer->fetchPacket();
+    if (p.len() != 0) {
+      if (DCCDecoder::parse(p)) {
+	if (Diag::SNIFFER)
+	  p.print();
+      }
+    }
+  }
+#endif // BOOSTER_INPUT
+#endif // ARDUINO_ARCH_ESP32
+
   // The main sketch has responsibilities during loop()
 
   // Responsibility 1: Handle DCC background processes
   //                   (loco reminders and power checks)
   DCC::loop();
-
+ 
   // Responsibility 2: handle any incoming commands on USB connection
-  serialParser.loop(Serial);
-
-// Responsibility 3: Optionally handle any incoming WiFi traffic
+  SerialManager::loop();
+ 
+  // Responsibility 3: Optionally handle any incoming WiFi traffic
+#ifndef ARDUINO_ARCH_ESP32
 #if WIFI_ON
   WifiInterface::loop();
+ 
+#endif //WIFI_ON
+#else  //ARDUINO_ARCH_ESP32
+#ifndef WIFI_TASK_ON_CORE0
+  WifiESP::loop();
 #endif
+#endif //ARDUINO_ARCH_ESP32
 #if ETHERNET_ON
   EthernetInterface::loop();
 #endif
 
   RMFT::loop();  // ignored if no automation
 
-  #if defined(LCN_SERIAL) 
-      LCN::loop();
+  #if defined(LCN_SERIAL)
+  LCN::loop();
   #endif
 
-  LCDDisplay::loop();  // ignored if LCD not in use 
+  // Display refresh
+  DisplayInterface::loop();
 
   // Handle/update IO devices.
   IODevice::loop();
-  
-  // Report any decrease in memory (will automatically trigger on first call)
-  static int ramLowWatermark = __INT_MAX__; // replaced on first loop 
 
-  int freeNow = minimumFreeMemory();
-  if (freeNow < ramLowWatermark)
-  {
+  Sensor::checkAll(); // Update and print changes
+
+  // Report any decrease in memory (will automatically trigger on first call)
+  static int ramLowWatermark = __INT_MAX__; // replaced on first loop
+
+  int freeNow = DCCTimer::getMinimumFreeMemory();
+  if (freeNow < ramLowWatermark) {
     ramLowWatermark = freeNow;
     LCD(3,F("Free RAM=%5db"), ramLowWatermark);
   }

DCC.h

@@ -1,5 +1,10 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
+ *  © 2021 Mike S
+ *  © 2021 Fred Decker
+ *  © 2021 Herb Morton
+ *  © 2020-2021 Harald Barth
+ *  © 2020-2021 Chris Harlow
+ *  All rights reserved.
  *  
  *  This file is part of Asbelos DCC API
  *
@@ -23,80 +28,54 @@
 #include "MotorDrivers.h"
 #include "FSH.h"
 
-typedef void (*ACK_CALLBACK)(int16_t result);
-
-enum ackOp : byte
-{           // Program opcodes for the ack Manager
-  BASELINE, // ensure enough resets sent before starting and obtain baseline current
-  W0,
-  W1,               // issue write bit (0..1) packet
-  WB,               // issue write byte packet
-  VB,               // Issue validate Byte packet
-  V0,               // Issue validate bit=0 packet
-  V1,               // issue validate bit=1 packlet
-  WACK,             // wait for ack (or absence of ack)
-  ITC1,             // If True Callback(1)  (if prevous WACK got an ACK)
-  ITC0,             // If True callback(0);
-  ITCB,             // If True callback(byte)
-  ITCBV,            // If True callback(byte) - end of Verify Byte
-  ITCB7,            // If True callback(byte &0x7F)
-  NAKFAIL,          // if false callback(-1)
-  FAIL,             // callback(-1)
-  BIV,              // Set ackManagerByte to initial value for Verify retry
-  STARTMERGE,       // Clear bit and byte settings ready for merge pass
-  MERGE,            // Merge previous wack response with byte value and decrement bit number (use for readimng CV bytes)
-  SETBIT,           // sets bit number to next prog byte
-  SETCV,            // sets cv number to next prog byte
-  SETBYTE,          // sets current byte to next prog byte
-  SETBYTEH,         // sets current byte to word high byte
-  SETBYTEL,         // sets current byte to word low byte
-  STASHLOCOID,      // keeps current byte value for later
-  COMBINELOCOID,    // combines current value with stashed value and returns it
-  ITSKIP,           // skip to SKIPTARGET if ack true
-  SKIPTARGET = 0xFF // jump to target
-};
-
-enum   CALLBACK_STATE : byte {
-  AFTER_WRITE,  // Start callback sequence after something was written to the decoder  
-  WAITING_100,        // Waiting for 100mS of stable power 
-  WAITING_30,         // waiting to 30ms of power off gap. 
-  READY,              // Ready to complete callback  
-  }; 
+#include "defines.h"
+#ifndef HIGHEST_SHORT_ADDR
+#define HIGHEST_SHORT_ADDR 127
+#else
+#if HIGHEST_SHORT_ADDR > 127
+#error short addr greater than 127 does not make sense
+#endif
+#endif
+#include "DCCACK.h"
+const uint16_t LONG_ADDR_MARKER = 0x4000;
 
 
 // Allocations with memory implications..!
 // Base system takes approx 900 bytes + 8 per loco. Turnouts, Sensors etc are dynamically created
-#if defined(ARDUINO_AVR_UNO)
-const byte MAX_LOCOS = 20;
-#elif defined(ARDUINO_AVR_NANO)
-const byte MAX_LOCOS = 30;
-#else
+#if defined(HAS_ENOUGH_MEMORY)
 const byte MAX_LOCOS = 50;
+#else
+const byte MAX_LOCOS = 30;
 #endif
 
 class DCC
 {
 public:
-  static void begin(const FSH * motorShieldName, MotorDriver *mainDriver, MotorDriver *progDriver);
-  static void setJoinRelayPin(byte joinRelayPin);
+  static inline void setShieldName(const FSH * motorShieldName) {
+    shieldName=(FSH *)motorShieldName;
+  };
+  static void begin();
   static void loop();
 
   // Public DCC API functions
   static void setThrottle(uint16_t cab, uint8_t tSpeed, bool tDirection);
-  static uint8_t getThrottleSpeed(int cab);
+  static int8_t getThrottleSpeed(int cab);
+  static uint8_t getThrottleSpeedByte(int cab);
+  static uint8_t getThrottleFrequency(int cab);
   static bool getThrottleDirection(int cab);
   static void writeCVByteMain(int cab, int cv, byte bValue);
   static void writeCVBitMain(int cab, int cv, byte bNum, bool bValue);
   static void setFunction(int cab, byte fByte, byte eByte);
-  static void setFn(int cab, int16_t functionNumber, bool on);
-  static int changeFn(int cab, int16_t functionNumber, bool pressed);
-  static int  getFn(int cab, int16_t functionNumber);
+  static bool setFn(int cab, int16_t functionNumber, bool on);
+  static void changeFn(int cab, int16_t functionNumber);
+  static int8_t getFn(int cab, int16_t functionNumber);
+  static uint32_t getFunctionMap(int cab);
+  static void setDCFreq(int cab,byte freq);
   static void updateGroupflags(byte &flags, int16_t functionNumber);
-  static void setAccessory(int aAdd, byte aNum, bool activate);
+  static void setAccessory(int address, byte port, bool gate, byte onoff = 2);
+  static bool setExtendedAccessory(int16_t address, int16_t value, byte repeats=3);
   static bool writeTextPacket(byte *b, int nBytes);
-  static void setProgTrackSyncMain(bool on); // when true, prog track becomes driveable
-  static void setProgTrackBoost(bool on);    // when true, special prog track current limit does not apply
-
+  
   // ACKable progtrack calls  bitresults callback 0,0 or -1, cv returns value or -1
   static void readCV(int16_t cv, ACK_CALLBACK callback);
   static void readCVBit(int16_t cv, byte bitNum, ACK_CALLBACK callback); // -1 for error
@@ -107,70 +86,42 @@ public:
 
   static void getLocoId(ACK_CALLBACK callback);
   static void setLocoId(int id,ACK_CALLBACK callback);
-
+  static void setConsistId(int id,bool reverse,ACK_CALLBACK callback);
   // Enhanced API functions
   static void forgetLoco(int cab); // removes any speed reminders for this loco
   static void forgetAllLocos();    // removes all speed reminders
   static void displayCabList(Print *stream);
-
   static FSH *getMotorShieldName();
   static inline void setGlobalSpeedsteps(byte s) {
     globalSpeedsteps = s;
   };
-  static inline int16_t setAckRetry(byte retry) {
-    ackRetry = retry;
-    ackRetryPSum = ackRetrySum;
-    ackRetrySum = 0;  // reset running total
-    return ackRetryPSum;
-  };
-
-private:
+  
   struct LOCO
   {
     int loco;
     byte speedCode;
     byte groupFlags;
-    unsigned long functions;
+    uint32_t functions;
   };
-  static byte joinRelay;
+ static LOCO speedTable[MAX_LOCOS];
+ static int lookupSpeedTable(int locoId, bool autoCreate=true);
+ static byte cv1(byte opcode, int cv);
+ static byte cv2(int cv);
+ 
+private:
   static byte loopStatus;
   static void setThrottle2(uint16_t cab, uint8_t speedCode);
   static void updateLocoReminder(int loco, byte speedCode);
-  static void setFunctionInternal(int cab, byte fByte, byte eByte);
+  static void setFunctionInternal(int cab, byte fByte, byte eByte, byte count);
   static bool issueReminder(int reg);
-  static int nextLoco;
+  static int lastLocoReminder;
+  static int highestUsedReg;
   static FSH *shieldName;
   static byte globalSpeedsteps;
 
-  static LOCO speedTable[MAX_LOCOS];
-  static byte cv1(byte opcode, int cv);
-  static byte cv2(int cv);
-  static int lookupSpeedTable(int locoId);
   static void issueReminders();
   static void callback(int value);
 
-  // ACK MANAGER
-  static ackOp const *ackManagerProg;
-  static ackOp const *ackManagerProgStart;
-  static byte ackManagerByte;
-  static byte ackManagerByteVerify;
-  static byte ackManagerBitNum;
-  static int ackManagerCv;
-  static byte ackManagerRetry;
-  static byte ackRetry;
-  static int16_t ackRetrySum;
-  static int16_t ackRetryPSum;
-  static int ackManagerWord;
-  static byte ackManagerStash;
-  static bool ackReceived;
-  static bool ackManagerRejoin;
-  static ACK_CALLBACK ackManagerCallback;
-  static CALLBACK_STATE callbackState;
-  static void ackManagerSetup(int cv, byte bitNumOrbyteValue, ackOp const program[], ACK_CALLBACK callback);
-  static void ackManagerSetup(int wordval, ackOp const program[], ACK_CALLBACK callback);
-  static void ackManagerLoop();
-  static bool checkResets( uint8_t numResets);
-  static const int PROG_REPEATS = 8; // repeats of programming commands (some decoders need at least 8 to be reliable)
   
   // NMRA codes #
   static const byte SET_SPEED = 0x3f;
@@ -185,31 +136,4 @@ private:
   static const byte BIT_OFF = 0x00;
 };
 
-#ifdef ARDUINO_AVR_MEGA // is using Mega 1280, define as Mega 2560 (pinouts and functionality are identical)
-#define ARDUINO_AVR_MEGA2560
-#endif
-
-#if defined(ARDUINO_AVR_UNO)
-#define ARDUINO_TYPE "UNO"
-#elif defined(ARDUINO_AVR_NANO)
-#define ARDUINO_TYPE "NANO"
-#elif defined(ARDUINO_AVR_MEGA2560)
-#define ARDUINO_TYPE "MEGA"
-#elif defined(ARDUINO_ARCH_MEGAAVR)
-#define ARDUINO_TYPE "MEGAAVR"
-#elif defined(ARDUINO_TEENSY32)
-#define ARDUINO_TYPE "TEENSY32"
-#elif defined(ARDUINO_TEENSY35)
-#define ARDUINO_TYPE "TEENSY35"
-#elif defined(ARDUINO_TEENSY36)
-#define ARDUINO_TYPE "TEENSY36"
-#elif defined(ARDUINO_TEENSY40)
-#define ARDUINO_TYPE "TEENSY40"
-#elif defined(ARDUINO_TEENSY41)
-#define ARDUINO_TYPE "TEENSY41"
-#else
-#error CANNOT COMPILE - DCC++ EX ONLY WORKS WITH AN ARDUINO UNO, NANO 328, OR ARDUINO MEGA 1280/2560
-#endif
-
-
 #endif

DCCACK.cpp

@@ -0,0 +1,507 @@
+/*
+ *  © 2021 M Steve Todd
+ *  © 2021 Mike S
+ *  © 2021 Fred Decker
+ *  © 2020-2021 Harald Barth
+ *  © 2020-2022 Chris Harlow
+ *  All rights reserved.
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#include "DCCACK.h"
+#include "DIAG.h"
+#include "DCC.h"
+#include "DCCWaveform.h"
+#include "TrackManager.h"
+
+unsigned long DCCACK::minAckPulseDuration = 2000; // micros
+unsigned long DCCACK::maxAckPulseDuration = 20000; // micros
+  
+MotorDriver *  DCCACK::progDriver=NULL;
+ackOp  const *  DCCACK::ackManagerProg;
+ackOp  const *  DCCACK::ackManagerProgStart;
+byte   DCCACK::ackManagerByte;
+byte   DCCACK::ackManagerByteVerify;
+byte   DCCACK::ackManagerStash;
+int    DCCACK::ackManagerWord;
+byte   DCCACK::ackManagerRetry;
+byte   DCCACK::ackRetry = 2;
+int16_t  DCCACK::ackRetrySum;
+int16_t  DCCACK::ackRetryPSum;
+int    DCCACK::ackManagerCv;
+byte   DCCACK::ackManagerBitNum;
+bool   DCCACK::ackReceived;
+bool   DCCACK::ackManagerRejoin;
+volatile uint8_t DCCACK::numAckGaps=0;
+volatile uint8_t DCCACK::numAckSamples=0;
+uint8_t DCCACK::trailingEdgeCounter=0;
+
+
+unsigned long DCCACK::ackPulseDuration;  // micros
+unsigned long DCCACK::ackPulseStart; // micros
+ volatile bool DCCACK::ackDetected;
+ unsigned long DCCACK::ackCheckStart; // millis
+ volatile bool DCCACK::ackPending;
+  bool   DCCACK::autoPowerOff;
+   int  DCCACK::ackThreshold; 
+   int  DCCACK::ackLimitmA = 50;
+     int DCCACK::ackMaxCurrent;
+      unsigned int DCCACK::ackCheckDuration; // millis       
+    
+    
+CALLBACK_STATE DCCACK::callbackState=READY;
+
+ACK_CALLBACK DCCACK::ackManagerCallback;
+
+void  DCCACK::Setup(int cv, byte byteValueOrBitnum, ackOp const program[], ACK_CALLBACK callback) {
+  // On ESP32 the joined track is hidden from sight (it has type MAIN)
+  // and because of that we need first check if track was joined and
+  // then unjoin if necessary. This requires that the joined flag is
+  // cleared when the prog track is removed.
+  ackManagerRejoin=TrackManager::isJoined();
+  //DIAG(F("Joined is %d"), ackManagerRejoin);
+  if (ackManagerRejoin) {
+    // Change from JOIN must zero resets packet.
+    TrackManager::setJoin(false);
+    DCCWaveform::progTrack.clearResets();
+  }
+  progDriver=TrackManager::getProgDriver();
+  //DIAG(F("Progdriver is %d"), progDriver);
+  if (progDriver==NULL) {
+    if (ackManagerRejoin) {
+      DIAG(F("Joined but no Prog track"));
+      TrackManager::setJoin(false);
+    }
+    callback(-3); // we dont have a prog track!
+    return;
+  }
+  if (!progDriver->canMeasureCurrent()) {
+    TrackManager::setJoin(ackManagerRejoin);
+    callback(-2); // our prog track cant measure current
+    return;
+  }
+
+   autoPowerOff=false;
+   if (progDriver->getPower() == POWERMODE::OFF) {
+        autoPowerOff=true;  // power off afterwards
+        if (Diag::ACK) DIAG(F("Auto Prog power on"));
+        progDriver->setPower(POWERMODE::ON);
+	
+    /* TODO !!! in MotorDriver surely!
+    if (MotorDriver::commonFaultPin)
+	  DCCWaveform::mainTrack.setPowerMode(POWERMODE::ON);
+        DCCWaveform::progTrack.clearResets();
+   **/
+      }
+
+
+  ackManagerCv = cv;
+  ackManagerProg = program;
+  ackManagerProgStart = program;
+  ackManagerRetry = ackRetry;
+  ackManagerByte = byteValueOrBitnum;
+  ackManagerByteVerify = byteValueOrBitnum;
+  ackManagerBitNum=byteValueOrBitnum;
+  ackManagerCallback = callback;
+}
+
+void  DCCACK::Setup(int wordval, ackOp const program[], ACK_CALLBACK callback) {
+  ackManagerWord=wordval;
+  Setup(0, 0, program, callback);
+  }
+
+const byte RESET_MIN=8;  // tuning of reset counter before sending message
+
+// checkRessets return true if the caller should yield back to loop and try later.
+bool DCCACK::checkResets(uint8_t numResets) {
+  return DCCWaveform::progTrack.getResets() < numResets;
+}
+// Operations applicable to PROG track ONLY.
+// (yes I know I could have subclassed the main track but...) 
+
+void DCCACK::setAckBaseline() {
+      int baseline=progDriver->getCurrentRaw();
+      ackThreshold= baseline + progDriver->mA2raw(ackLimitmA);
+      if (Diag::ACK) DIAG(F("ACK baseline=%d/%dmA Threshold=%d/%dmA Duration between %lus and %lus"),
+			  baseline,progDriver->raw2mA(baseline),
+			  ackThreshold,progDriver->raw2mA(ackThreshold),
+                          minAckPulseDuration, maxAckPulseDuration);
+}
+
+void DCCACK::setAckPending() {
+      ackMaxCurrent=0;
+      ackPulseStart=0;
+      ackPulseDuration=0;
+      ackDetected=false;
+      ackCheckStart=millis();
+      numAckSamples=0;
+      numAckGaps=0;
+      ackPending=true;  // interrupt routines will now take note
+}
+
+byte DCCACK::getAck() {
+      if (ackPending) return (2);  // still waiting
+      if (Diag::ACK) DIAG(F("%S after %dmS max=%d/%dmA pulse=%luS samples=%d gaps=%d"),ackDetected?F("ACK"):F("NO-ACK"), ackCheckDuration,
+			  ackMaxCurrent,progDriver->raw2mA(ackMaxCurrent), ackPulseDuration, numAckSamples, numAckGaps);
+      if (ackDetected) return (1); // Yes we had an ack
+      return(0);  // pending set off but not detected means no ACK.   
+}
+
+#ifndef DISABLE_PROG
+void DCCACK::loop() {
+  while (ackManagerProg) {
+    byte opcode=GETFLASH(ackManagerProg);
+
+    // breaks from this switch will step to next prog entry
+    // returns from this switch will stay on same entry
+    // (typically waiting for a reset counter or ACK waiting, or when all finished.)
+    switch (opcode) {
+      case BASELINE:
+          if (progDriver->getPower()==POWERMODE::OVERLOAD) return;
+      	  if (checkResets(autoPowerOff || ackManagerRejoin  ? 20 : 3)) return;
+          setAckBaseline();
+          callbackState=AFTER_READ;
+          break;
+      case W0:    // write 0 bit
+      case W1:    // write 1 bit
+            {
+	      if (checkResets(RESET_MIN)) return;
+              if (Diag::ACK) DIAG(F("W%d cv=%d bit=%d"),opcode==W1, ackManagerCv,ackManagerBitNum);
+              byte instruction = WRITE_BIT | (opcode==W1 ? BIT_ON : BIT_OFF) | ackManagerBitNum;
+              byte message[] = {DCC::cv1(BIT_MANIPULATE, ackManagerCv), DCC::cv2(ackManagerCv), instruction };
+              DCCWaveform::progTrack.schedulePacket(message, sizeof(message), PROG_REPEATS);
+              setAckPending();
+             callbackState=AFTER_WRITE;
+         }
+            break;
+
+      case WB:   // write byte
+            {
+	      if (checkResets( RESET_MIN)) return;
+              if (Diag::ACK) DIAG(F("WB cv=%d value=%d"),ackManagerCv,ackManagerByte);
+              byte message[] = {DCC::cv1(WRITE_BYTE, ackManagerCv), DCC::cv2(ackManagerCv), ackManagerByte};
+              DCCWaveform::progTrack.schedulePacket(message, sizeof(message), PROG_REPEATS);
+              setAckPending();
+              callbackState=AFTER_WRITE;
+            }
+            break;
+
+      case   VB:     // Issue validate Byte packet
+        {
+	  if (checkResets( RESET_MIN)) return;
+          if (Diag::ACK) DIAG(F("VB cv=%d value=%d"),ackManagerCv,ackManagerByte);
+          byte message[] = { DCC::cv1(VERIFY_BYTE, ackManagerCv), DCC::cv2(ackManagerCv), ackManagerByte};
+          DCCWaveform::progTrack.schedulePacket(message, sizeof(message), PROG_REPEATS);
+          setAckPending();
+        }
+        break;
+
+      case V0:
+      case V1:      // Issue validate bit=0 or bit=1  packet
+        {
+	  if (checkResets(RESET_MIN)) return;
+          if (Diag::ACK) DIAG(F("V%d cv=%d bit=%d"),opcode==V1, ackManagerCv,ackManagerBitNum);
+          byte instruction = VERIFY_BIT | (opcode==V0?BIT_OFF:BIT_ON) | ackManagerBitNum;
+          byte message[] = {DCC::cv1(BIT_MANIPULATE, ackManagerCv), DCC::cv2(ackManagerCv), instruction };
+          DCCWaveform::progTrack.schedulePacket(message, sizeof(message), PROG_REPEATS);
+          setAckPending();
+        }
+        break;
+
+      case WACK:   // wait for ack (or absence of ack)
+         {
+          byte ackState=2; // keep polling
+
+          ackState=getAck();
+          if (ackState==2) return; // keep polling
+          ackReceived=ackState==1;
+          break;  // we have a genuine ACK result
+         }
+     case ITC0:
+     case ITC1:   // If True Callback(0 or 1)  (if prevous WACK got an ACK)
+        if (ackReceived) {
+            callback(opcode==ITC0?0:1);
+            return;
+          }
+        break;
+
+      case ITCB:   // If True callback(byte)
+          if (ackReceived) {
+            callback(ackManagerByte);
+            return;
+          }
+        break;
+		
+      case ITCBV:   // If True callback(byte) - Verify
+          if (ackReceived) {
+            if (ackManagerByte == ackManagerByteVerify) {
+               ackRetrySum ++;
+               LCD(1, F("v %d %d Sum=%d"), ackManagerCv, ackManagerByte, ackRetrySum);
+            }
+            callback(ackManagerByte);
+            return;
+          }
+        break;
+		
+      case ITCB7:   // If True callback(byte & 0x7F)
+          if (ackReceived) {
+            callback(ackManagerByte & 0x7F);
+            return;
+          }
+        break;
+
+      case NAKFAIL:   // If nack callback(-1)
+          if (!ackReceived) {
+            callback(-1);
+            return;
+          }
+        break;
+
+      case CALLFAIL:  // callback(-1)
+           callback(-1);
+           return;
+
+      case BIV:     // ackManagerByte initial value
+           ackManagerByte = ackManagerByteVerify;
+           break;
+
+      case STARTMERGE:
+           ackManagerBitNum=7;
+           ackManagerByte=0;
+          break;
+
+      case MERGE:  // Merge previous Validate zero wack response with byte value and update bit number (use for reading CV bytes)
+          ackManagerByte <<= 1;
+          // ackReceived means bit is zero.
+          if (!ackReceived) ackManagerByte |= 1;
+          ackManagerBitNum--;
+          break;
+
+      case SETBIT:
+          ackManagerProg++;
+          ackManagerBitNum=GETFLASH(ackManagerProg);
+          break;
+
+     case SETCV:
+          ackManagerProg++;
+          ackManagerCv=GETFLASH(ackManagerProg);
+          break;
+
+     case SETBYTE:
+          ackManagerProg++;
+          ackManagerByte=GETFLASH(ackManagerProg);
+          break;
+
+    case SETBYTEH:
+          ackManagerByte=highByte(ackManagerWord);
+          break;
+
+    case SETBYTEL:
+          ackManagerByte=lowByte(ackManagerWord);
+          break;
+
+     case STASHLOCOID:
+          ackManagerStash=ackManagerByte;  // stash value from CV17
+          break;
+
+     case COMBINELOCOID:
+          // ackManagerStash is  cv17, ackManagerByte is CV 18
+          callback( LONG_ADDR_MARKER | ( ackManagerByte + ((ackManagerStash - 192) << 8)));
+          return;
+
+     case COMBINE1920:
+          // ackManagerStash is  cv20, ackManagerByte is CV 19
+          // This will not be called if cv20==0
+          ackManagerByte &= 0x7F;  // ignore direction marker
+          ackManagerByte %=100;    // take last 2 decimal digits 
+          callback( ackManagerStash*100+ackManagerByte);
+          return;
+
+     case ITSKIP:
+          if (!ackReceived) break;
+          // SKIP opcodes until SKIPTARGET found
+          while (opcode!=SKIPTARGET) {
+            ackManagerProg++;
+            opcode=GETFLASH(ackManagerProg);
+          }
+          break;
+
+     case NAKSKIP:
+          if (ackReceived) break;
+          // SKIP opcodes until SKIPTARGET found
+          while (opcode!=SKIPTARGET) {
+            ackManagerProg++;
+            opcode=GETFLASH(ackManagerProg);
+          }
+          break;
+     case BAD20SKIP:
+          if (ackManagerByte > 120) {
+            // skip to SKIPTARGET if cv20 is >120 (some decoders respond with 255)
+            if (Diag::ACK) DIAG(F("XX cv20=%d "),ackManagerByte);
+            while (opcode!=SKIPTARGET) {
+              ackManagerProg++;
+              opcode=GETFLASH(ackManagerProg);
+            }
+          }
+          break; 
+     case FAIL_IF_NONZERO_NAK: // fail if writing long address to decoder that cant support it
+          if (ackManagerByte==0) break;
+          callback(-4);  
+          return;           
+     case SKIPTARGET:
+          break;
+     default:
+          DIAG(F("!! ackOp %d FAULT!!"),opcode);
+          callback( -1);
+          return;
+
+      }  // end of switch
+    ackManagerProg++;
+  }
+}
+
+void DCCACK::callback(int value) {
+    // check for automatic retry
+    if (value == -1 && ackManagerRetry > 0) {
+      ackRetrySum ++;
+      LCD(0, F("Retry %d %d Sum=%d"), ackManagerCv, ackManagerRetry, ackRetrySum);
+      ackManagerRetry --;
+      ackManagerProg = ackManagerProgStart;
+      return;
+    }
+
+    static unsigned long callbackStart;
+    // We are about to leave programming mode
+    // Rule 1: If we have written to a decoder we must maintain power for 100mS
+    // Rule 2: If we are re-joining the main track we must power off for 30mS
+
+    switch (callbackState) {
+      case AFTER_READ:
+         if (ackManagerRejoin && !autoPowerOff) {
+                progDriver->setPower(POWERMODE::OFF);
+                callbackStart=millis();
+                callbackState=WAITING_30;
+                if (Diag::ACK) DIAG(F("OFF 30mS"));
+        } else {
+               callbackState=READY;
+        }
+        break;
+
+      case AFTER_WRITE:  // first attempt to callback after a write operation
+	    if (!ackManagerRejoin && !autoPowerOff) {
+               callbackState=READY;
+               break;
+            }                              // lines 906-910 added. avoid wait after write. use 1 PROG
+            callbackStart=millis();
+            callbackState=WAITING_100;
+            if (Diag::ACK) DIAG(F("Stable 100mS"));
+            break;
+
+       case WAITING_100:  // waiting for 100mS
+            if (millis()-callbackStart < 100) break;
+            // stable after power maintained for 100mS
+
+            // If we are going to power off anyway, it doesnt matter
+            // but if we will keep the power on, we must off it for 30mS
+            if (autoPowerOff) callbackState=READY;
+            else { // Need to cycle power off and on
+                progDriver->setPower(POWERMODE::OFF);
+                callbackStart=millis();
+                callbackState=WAITING_30;
+                if (Diag::ACK) DIAG(F("OFF 30mS"));
+            }
+            break;
+
+        case WAITING_30:  // waiting for 30mS with power off
+            if (millis()-callbackStart < 30) break;
+            //power has been off for 30mS
+            progDriver->setPower(POWERMODE::ON);
+            callbackState=READY;
+            break;
+
+       case READY:  // ready after read, or write after power delay and off period.
+            // power off if we powered it on
+           if (autoPowerOff) {
+              if (Diag::ACK) DIAG(F("Auto Prog power off"));
+              progDriver->setPower(POWERMODE::OFF);
+              /* TODO 
+	      if (MotorDriver::commonFaultPin)
+		DCCWaveform::mainTrack.setPowerMode(POWERMODE::OFF);
+        **/
+           }
+          // Restore <1 JOIN> to state before BASELINE
+          if (ackManagerRejoin) {
+              TrackManager::setJoin(true);
+              if (Diag::ACK) DIAG(F("Auto JOIN"));
+          }
+
+          ackManagerProg=NULL;  // no more steps to execute
+          if (Diag::ACK) DIAG(F("Callback(%d)"),value);
+          (ackManagerCallback)( value);
+    }
+}
+#endif
+
+void DCCACK::checkAck(byte sentResetsSincePacket) {
+    if (!ackPending) return; 
+    // This function operates in interrupt() time so must be fast and can't DIAG 
+    if (sentResetsSincePacket > 6) {  //ACK timeout
+        ackCheckDuration=millis()-ackCheckStart;
+        ackPending = false;
+        return; 
+    }
+      
+    int current=progDriver->getCurrentRaw(true); // true means "from interrupt"
+    numAckSamples++;
+    if (current > ackMaxCurrent) ackMaxCurrent=current;
+    // An ACK is a pulse lasting between minAckPulseDuration and maxAckPulseDuration uSecs (refer @haba)
+        
+    if (current>ackThreshold) {
+       if (trailingEdgeCounter > 0) {
+	 numAckGaps++;
+	 trailingEdgeCounter = 0;
+       }
+       if (ackPulseStart==0) ackPulseStart=micros();    // leading edge of pulse detected
+       return;
+    }
+    
+    // not in pulse
+    if (ackPulseStart==0) return; // keep waiting for leading edge 
+    
+    // if we reach to this point, we have
+    // detected trailing edge of pulse
+    if (trailingEdgeCounter == 0) {
+      ackPulseDuration=micros()-ackPulseStart;
+    }
+
+    // but we do not trust it yet and return (which will force another
+    // measurement) and first the third time around with low current
+    // the ack detection will be finalized. 
+    if (trailingEdgeCounter < 2) {
+      trailingEdgeCounter++;
+      return;
+    }
+    trailingEdgeCounter = 0;
+
+    if (ackPulseDuration>=minAckPulseDuration && ackPulseDuration<=maxAckPulseDuration) {
+        ackCheckDuration=millis()-ackCheckStart;
+        ackDetected=true;
+        ackPending=false;
+        DCCWaveform::progTrack.clearRepeats();  // shortcut remaining repeat packets 
+        return;  // we have a genuine ACK result
+    }      
+    ackPulseStart=0;  // We have detected a too-short or too-long pulse so ignore and wait for next leading edge 
+}

DCCACK.h

@@ -0,0 +1,160 @@
+/*
+ *  © 2021 M Steve Todd
+ *  © 2021 Mike S
+ *  © 2021 Fred Decker
+ *  © 2020-2021 Harald Barth
+ *  © 2020-2022 Chris Harlow
+ *  All rights reserved.
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#ifndef DCCACK_h
+#define DCCACK_h
+
+#include "MotorDriver.h"
+
+typedef void (*ACK_CALLBACK)(int16_t result);
+
+enum ackOp : byte
+{           // Program opcodes for the ack Manager
+  BASELINE, // ensure enough resets sent before starting and obtain baseline current
+  W0,
+  W1,               // issue write bit (0..1) packet
+  WB,               // issue write byte packet
+  VB,               // Issue validate Byte packet
+  V0,               // Issue validate bit=0 packet
+  V1,               // issue validate bit=1 packlet
+  WACK,             // wait for ack (or absence of ack)
+  ITC1,             // If True Callback(1)  (if prevous WACK got an ACK)
+  ITC0,             // If True callback(0);
+  ITCB,             // If True callback(byte)
+  ITCBV,            // If True callback(byte) - end of Verify Byte
+  ITCB7,            // If True callback(byte &0x7F)
+  NAKFAIL,          // if false callback(-1)
+  CALLFAIL,         // callback(-1)
+  BIV,              // Set ackManagerByte to initial value for Verify retry
+  STARTMERGE,       // Clear bit and byte settings ready for merge pass
+  MERGE,            // Merge previous wack response with byte value and decrement bit number (use for readimng CV bytes)
+  SETBIT,           // sets bit number to next prog byte
+  SETCV,            // sets cv number to next prog byte
+  SETBYTE,          // sets current byte to next prog byte
+  SETBYTEH,         // sets current byte to word high byte
+  SETBYTEL,         // sets current byte to word low byte
+  STASHLOCOID,      // keeps current byte value for later
+  COMBINELOCOID,    // combines current value with stashed value and returns it
+  ITSKIP,           // skip to SKIPTARGET if ack true
+  NAKSKIP,          // skip to SKIPTARGET if ack false
+  COMBINE1920,      // combine cvs 19 and 20 and callback
+  BAD20SKIP,        // skip to SKIPTARGET if cv20 is >120 (some decoders respond with 255) 
+  FAIL_IF_NONZERO_NAK, // fail if writing long address to decoder that cant support it
+  SKIPTARGET = 0xFF // jump to target
+};
+
+enum   CALLBACK_STATE : byte {
+
+  AFTER_READ,   // Start callback sequence after something was read from the decoder  
+  AFTER_WRITE,  // Start callback sequence after something was written to the decoder  
+  WAITING_100,        // Waiting for 100mS of stable power 
+  WAITING_30,         // waiting to 30ms of power off gap. 
+  READY,              // Ready to complete callback  
+  }; 
+
+
+
+class DCCACK {
+  public:
+    static byte getAck();               //prog track only 0=NACK, 1=ACK 2=keep waiting
+    static void checkAck(byte sentResetsSincePacket); // Interrupt time ack checker
+    static inline void setAckLimit(int mA) {
+	ackLimitmA = mA;
+    }
+    static inline void setMinAckPulseDuration(unsigned long i) {
+	minAckPulseDuration = i;
+    }
+    static inline void setMaxAckPulseDuration(unsigned long i) {
+	maxAckPulseDuration = i;
+    }
+
+    static void  Setup(int cv, byte byteValueOrBitnum, ackOp const program[], ACK_CALLBACK callback);
+    static void  Setup(int wordval, ackOp const program[], ACK_CALLBACK callback);
+    static void loop();
+    static bool isActive() { return ackManagerProg!=NULL;}
+  static inline int16_t setAckRetry(byte retry) {
+    ackRetry = retry;
+    ackRetryPSum = ackRetrySum;
+    ackRetrySum = 0;  // reset running total
+    return ackRetryPSum;
+  };
+
+
+  private:
+    static const byte SET_SPEED = 0x3f;
+    static const byte WRITE_BYTE = 0x7C;
+    static const byte VERIFY_BYTE = 0x74;
+    static const byte BIT_MANIPULATE = 0x78;
+    static const byte WRITE_BIT = 0xF0;
+    static const byte VERIFY_BIT = 0xE0;
+    static const byte BIT_ON = 0x08;
+    static const byte BIT_OFF = 0x00;
+ 
+    static void setAckBaseline();
+    static void setAckPending();  
+    static void callback(int value);
+    
+    static const int PROG_REPEATS = 8; // repeats of programming commands (some decoders need at least 8 to be reliable)
+    
+    // ACK management (Prog track only)  
+    static void checkAck();
+    static bool checkResets(uint8_t numResets);
+
+    static volatile bool ackPending;
+    static volatile bool ackDetected;
+    static int  ackThreshold; 
+    static int  ackLimitmA;
+    static int ackMaxCurrent;
+    static unsigned long ackCheckStart; // millis
+    static unsigned int ackCheckDuration; // millis       
+    
+    static unsigned long ackPulseDuration;  // micros
+    static unsigned long ackPulseStart; // micros
+
+    static unsigned long minAckPulseDuration ; // micros
+    static unsigned long maxAckPulseDuration ; // micros
+    static MotorDriver* progDriver;
+    static volatile uint8_t numAckGaps;
+    static volatile uint8_t numAckSamples;
+    static uint8_t trailingEdgeCounter;
+    static ackOp  const *  ackManagerProg;
+static ackOp  const *  ackManagerProgStart;
+static byte   ackManagerByte;
+static byte   ackManagerByteVerify;
+static byte   ackManagerStash;
+static int    ackManagerWord;
+static byte   ackManagerRetry;
+static byte   ackRetry;
+static int16_t ackRetrySum;
+static int16_t  ackRetryPSum;
+static int    ackManagerCv;
+static byte   ackManagerBitNum;
+static bool   ackReceived;
+static bool   ackManagerRejoin;
+static bool   autoPowerOff;
+static CALLBACK_STATE callbackState;
+static ACK_CALLBACK ackManagerCallback;
+
+
+};
+#endif

DCCDecoder.cpp

@@ -0,0 +1,178 @@
+/*
+ *  © 2025 Harald Barth
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#ifdef ARDUINO_ARCH_ESP32
+#include "DCCDecoder.h"
+#include "LocoTable.h"
+#include "DCCEXParser.h"
+#include "DIAG.h"
+#include "DCC.h"
+
+bool DCCDecoder::parse(DCCPacket &p) {
+  if (!active)
+    return false;
+  const byte DECODER_MOBILE = 1;
+  const byte DECODER_ACCESSORY = 2;
+  byte decoderType = 0; // use 0 as none
+  byte *d = p.data();
+  byte *instr = 0;      // will be set to point to the instruction part of the DCC packet (instr[0] to instr[n])
+  uint16_t addr;        // will be set to decoder addr (long/shor mobile or accessory) 
+  bool locoInfoChanged = false;
+
+  if (d[0] ==  0B11111111) {  // Idle packet
+    return false;
+  }
+  // CRC verification here
+  byte checksum = 0;
+  for (byte n = 0; n < p.len(); n++)
+    checksum ^= d[n];
+  if (checksum) {  // Result should be zero, if not it's an error!
+    if (Diag::SNIFFER) {
+      DIAG(F("Checksum error"));
+      p.print();
+    }
+    return false;
+  }
+
+/*
+  Serial.print("< ");
+  for(int n=0; n<8; n++) {
+    Serial.print(d[0]&(1<<n)?"1":"0");
+  }
+  Serial.println(" >");
+*/
+  if (bitRead(d[0],7) == 0) { // bit7 == 0 => loco short addr
+    decoderType = DECODER_MOBILE;
+    instr = d+1;
+    addr = d[0];
+  } else {
+    if (bitRead(d[0],6) == 1) { // bit7 == 1 and bit6 == 1 => loco long addr
+      decoderType = DECODER_MOBILE;
+      instr = d+2;
+      addr = 256 * (d[0] & 0B00111111) + d[1];
+    } else { // bit7 == 1 and bit 6 == 0
+      decoderType = DECODER_ACCESSORY;
+      instr = d+1;
+      addr = d[0] &  0B00111111;
+    }
+  }
+  if (decoderType == DECODER_MOBILE) {
+    switch (instr[0] & 0xE0) {
+    case 0x20: // 001x-xxxx Extended commands
+      if (instr[0] == 0B00111111) { // 128 speed steps
+	if ((locoInfoChanged = LocoTable::updateLoco(addr, instr[1])) == true) {
+	  byte speed = instr[1] & 0B01111111;
+	  byte direction = instr[1] & 0B10000000;
+	  DCC::setThrottle(addr, speed, direction);
+	  //DIAG(F("UPDATE"));
+	  // send speed change to DCCEX here
+	}
+      }
+      break;
+    case 0x40: // 010x-xxxx 28 (or 14 step) speed we assume 28
+    case 0x60: // 011x-xxxx
+      if ((locoInfoChanged = LocoTable::updateLoco(addr, instr[0] & 0B00111111)) == true) {
+	byte speed = instr[0] & 0B00001111; // first only look at 4 bits
+	if (speed > 1) {               // neither stop nor emergency stop, recalculate speed
+	  speed = ((instr[0] & 0B00001111) << 1) + bitRead(instr[0], 4); // reshuffle bits
+	  speed = (speed - 3) * 9/2;
+	}
+	byte direction = instr[0] & 0B00100000;
+	DCC::setThrottle(addr, speed, direction);
+      }
+      break;
+    case 0x80: // 100x-xxxx Function group 1
+      if ((locoInfoChanged = LocoTable::updateFunc(addr, instr[0], 1)) == true) {
+	byte normalized = (instr[0] << 1 & 0x1e) | (instr[0] >> 4 & 0x01);
+	DCCEXParser::funcmap(addr, normalized, 0, 4);
+      }
+      break;
+    case 0xA0: // 101x-xxxx Function group 3 and 2
+    {
+      byte low, high;
+      if (bitRead(instr[0], 4)) {
+	low = 5;
+	high = 8;
+      } else {
+	low = 9;
+	high = 12;
+      }
+      if ((locoInfoChanged = LocoTable::updateFunc(addr, instr[0], low)) == true) {
+	DCCEXParser::funcmap(addr, instr[0], low, high);
+      }
+    }
+    break;
+    case 0xC0: // 110x-xxxx Extended (here are functions F13 and up
+      switch (instr[0] & 0B00011111) {
+      case 0B00011110:  // F13-F20 Function Control
+	if ((locoInfoChanged = LocoTable::updateFunc(addr, instr[0], 13)) == true) {
+	  DCCEXParser::funcmap(addr, instr[1], 13, 20);
+	}
+	if ((locoInfoChanged = LocoTable::updateFunc(addr, instr[0], 17)) == true) {
+	  DCCEXParser::funcmap(addr, instr[1], 13, 20);
+	}
+      break;
+      case 0B00011111:  // F21-F28 Function Control
+	if ((locoInfoChanged = LocoTable::updateFunc(addr, instr[1], 21)) == true) {
+	  DCCEXParser::funcmap(addr, instr[1], 21, 28);
+	}  // updateFunc handles only the 4 low bits as that is the most common case
+	if ((locoInfoChanged = LocoTable::updateFunc(addr, instr[1]>>4, 25)) == true) {
+	  DCCEXParser::funcmap(addr, instr[1], 21, 28);
+	}
+	break;
+	/* do that later
+      case 0B00011000:  // F29-F36 Function Control
+	break;
+      case 0B00011001:  // F37-F44 Function Control
+	break;
+      case 0B00011010:  // F45-F52 Function Control
+	break;
+      case 0B00011011:  // F53-F60 Function Control
+	break;
+      case 0B00011100:  // F61-F68 Function Control
+	break;
+	*/
+      }
+      break;
+    case 0xE0: // 111x-xxxx Config vars
+      break;
+    }
+    return locoInfoChanged;
+  }
+  if (decoderType == DECODER_ACCESSORY) {
+      if (instr[0] & 0B10000000) {  // Basic Accessory
+	addr = (((~instr[0]) & 0B01110000) << 2) + addr;
+	byte port = (instr[0] & 0B00000110) >> 1;
+	byte activate = (instr[0] & 0B00001000) >> 3;
+	byte coil = (instr[0] & 0B00000001);
+	locoInfoChanged = true;
+	//(void)addr; (void)port; (void)coil; (void)activate;
+	//DIAG(F("HL=%d LL=%d C=%d A=%d"), addr, port, coil, activate);
+	DCC::setAccessory(addr, port, coil, activate);
+      } else { // Accessory Extended NMRA spec, do we need to decode this?
+	/*
+	addr = (addr << 5) +
+	  ((instr[0] & 0B01110000) >> 2) +
+	  ((instr[0] & 0B00000110) >> 1);
+	*/
+      }
+    return locoInfoChanged;
+  }
+  return false;
+}
+#endif // ARDUINO_ARCH_ESP32

DCCDecoder.h

@@ -1,8 +1,7 @@
 /*
- *  © 2020, Harald Barth
- *  © 2021, Neil McKechnie
+ *  © 2025 Harald Barth
  *  
- *  This file is part of DCC-EX
+ *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
@@ -17,9 +16,15 @@
  *  You should have received a copy of the GNU General Public License
  *  along with CommandStation.  If not, see <https://www.gnu.org/licenses/>.
  */
+#ifdef ARDUINO_ARCH_ESP32
+#include <Arduino.h>
+#include "DCCPacket.h"
 
-#ifndef freeMemory_h
-#define freeMemory_h
-void updateMinimumFreeMemory(unsigned char extraBytes=0);
-int minimumFreeMemory();
-#endif
+class DCCDecoder {
+public:
+  static bool parse(DCCPacket &p);
+  static inline void onoff(bool on) {active = on;};
+private:
+  static bool active;
+};
+#endif // ARDUINO_ARCH_ESP32

DCCEX.h

@@ -1,7 +1,8 @@
 /*
- *  (c) 2020 Chris Harlow. All rights reserved.
- *  (c) 2021 Fred Decker.  All rights reserved.
- *  (c) 2020 Harald Barth. All rights reserved.
+ *  © 2021 Fred Decker
+ *  © 2020-2021 Harald Barth
+ *  © 2020-2021 Chris Harlow
+ *  All rights reserved.
  *  
  *  This file is part of CommandStation-EX
  *
@@ -29,19 +30,26 @@
 #include "DCC.h"
 #include "DIAG.h"
 #include "DCCEXParser.h"
+#include "SerialManager.h"
 #include "version.h"
+#ifndef ARDUINO_ARCH_ESP32
 #include "WifiInterface.h"
+#else
+#include "WifiESP32.h"
+#endif
 #if ETHERNET_ON == true
 #include "EthernetInterface.h"
 #endif
-#include "LCD_Implementation.h"
+#include "Display_Implementation.h"
 #include "LCN.h"
-#include "freeMemory.h"
 #include "IODevice.h"
 #include "Turnouts.h"
 #include "Sensors.h"
 #include "Outputs.h"
-#include "RMFT.h"
-
+#include "CommandDistributor.h"
+#include "TrackManager.h"
+#include "DCCTimer.h"    
+#include "KeywordHasher.h"
+#include "EXRAIL.h"
     
 #endif

DCCEXParser.h

@@ -1,5 +1,8 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
+ *  © 2021 Mike S
+ *  © 2021 Fred Decker
+ *  © 2020-2021 Chris Harlow
+ *  All rights reserved.
  *  
  *  This file is part of Asbelos DCC API
  *
@@ -21,39 +24,40 @@
 #include <Arduino.h>
 #include "FSH.h"
 #include "RingStream.h"
+#include "defines.h"
 
 typedef void (*FILTER_CALLBACK)(Print * stream, byte & opcode, byte & paramCount, int16_t p[]);
-typedef void (*AT_COMMAND_CALLBACK)(const byte * command);
+typedef void (*AT_COMMAND_CALLBACK)(HardwareSerial * stream,const byte * command);
 
 struct DCCEXParser
 {
-   DCCEXParser();
-   void loop(Stream & stream);
-   void parse(Print * stream,  byte * command,  RingStream * ringStream);
-   void parse(const FSH * cmd);
-   void flush();
+   
+   static void parse(Print * stream,  byte * command,  RingStream * ringStream);
+   static void parse(const FSH * cmd);
+   static void parseOne(Print * stream,  byte * command,  RingStream * ringStream);
    static void setFilter(FILTER_CALLBACK filter);
    static void setRMFTFilter(FILTER_CALLBACK filter);
    static void setAtCommandCallback(AT_COMMAND_CALLBACK filter);
    static const int MAX_COMMAND_PARAMS=10;  // Must not exceed this
+   static bool funcmap(int16_t cab, byte value, byte fstart, byte fstop);
  
    private:
   
     static const int16_t MAX_BUFFER=50;  // longest command sent in
-     byte  bufferLength=0;
-     bool  inCommandPayload=false;
-     byte  buffer[MAX_BUFFER+2]; 
-    int16_t splitValues( int16_t result[MAX_COMMAND_PARAMS], const byte * command);
-    int16_t splitHexValues( int16_t result[MAX_COMMAND_PARAMS], const byte * command);
+    static int16_t splitValues( int16_t result[MAX_COMMAND_PARAMS], byte * command, bool usehex);
      
-     bool parseT(Print * stream, int16_t params, int16_t p[]);
-     bool parseZ(Print * stream, int16_t params, int16_t p[]);
-     bool parseS(Print * stream,  int16_t params, int16_t p[]);
-     bool parsef(Print * stream,  int16_t params, int16_t p[]);
-     bool parseD(Print * stream,  int16_t params, int16_t p[]);
+    static bool parseT(Print * stream, int16_t params, int16_t p[]);
+    static bool parseZ(Print * stream, int16_t params, int16_t p[]);
+    static bool parseS(Print * stream, int16_t params, int16_t p[]);
+    static bool parsef(Print * stream, int16_t params, int16_t p[]);
+    static bool parseC(Print * stream, int16_t params, int16_t p[]);
+    static bool parseD(Print * stream, int16_t params, int16_t p[]);
+#ifndef IO_NO_HAL
+    static bool parseI(Print * stream, int16_t params, int16_t p[]);
+#endif
 
-     static Print * getAsyncReplyStream();
-     static void commitAsyncReplyStream();
+    static Print * getAsyncReplyStream();
+    static void commitAsyncReplyStream();
 
     static bool stashBusy;
     static byte stashTarget;
@@ -61,18 +65,20 @@ struct DCCEXParser
     static RingStream * stashRingStream;
     
     static int16_t stashP[MAX_COMMAND_PARAMS];
-    bool stashCallback(Print * stream, int16_t p[MAX_COMMAND_PARAMS], RingStream * ringStream);
+    static bool stashCallback(Print * stream, int16_t p[MAX_COMMAND_PARAMS], RingStream * ringStream);
     static void callback_W(int16_t result);
+    static void callback_W4(int16_t result);
     static void callback_B(int16_t result);        
     static void callback_R(int16_t result);
     static void callback_Rloco(int16_t result);
     static void callback_Wloco(int16_t result);
+    static void callback_Wconsist(int16_t result);
     static void callback_Vbit(int16_t result);
     static void callback_Vbyte(int16_t result);
     static FILTER_CALLBACK  filterCallback;
     static FILTER_CALLBACK  filterRMFTCallback;
     static AT_COMMAND_CALLBACK  atCommandCallback;
-    static void funcmap(int16_t cab, byte value, byte fstart, byte fstop);
+    static void sendFlashList(Print * stream,const int16_t flashList[]);
 
 };
 

DCCPacket.h

@@ -0,0 +1,83 @@
+/*
+ *  © 2025 Harald Barth
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#include <Arduino.h>
+#ifndef DCCPacket_h
+#define DCCPacket_h
+#include <strings.h>
+#include "defines.h"
+
+class DCCPacket {
+public:
+  DCCPacket() {
+    _len = 0;
+    _data = NULL;
+  };
+  DCCPacket(byte *d, byte l) {
+    _len = l;
+    _data = new byte[_len];
+    for (byte n = 0; n<_len; n++)
+      _data[n] = d[n];
+  };
+  DCCPacket(const DCCPacket &old) {
+    _len = old._len;
+    _data = new byte[_len];
+    for (byte n = 0; n<_len; n++)
+      _data[n] = old._data[n];
+  };
+  DCCPacket &operator=(const DCCPacket &rhs) {
+    if (this == &rhs)
+      return *this;
+    delete[]_data;
+    _len = rhs._len;
+    _data = new byte[_len];
+    for (byte n = 0; n<_len; n++)
+      _data[n] = rhs._data[n];
+    return *this;
+  };
+  ~DCCPacket() {
+    if (_len) {
+      delete[]_data;
+      _len = 0;
+      _data = NULL;
+    }
+  };
+  inline bool operator==(const DCCPacket &right) {
+    if (_len != right._len)
+      return false;
+    if (_len == 0)
+      return true;
+    return (bcmp(_data, right._data, _len) == 0);
+  };
+  void print() {
+    static const char hexchars[]="0123456789ABCDEF";
+    USB_SERIAL.print(F("<* DCCPACKET "));
+    for (byte n = 0; n< _len; n++) {
+      USB_SERIAL.print(hexchars[_data[n]>>4]);
+      USB_SERIAL.print(hexchars[_data[n] & 0x0f]);
+      USB_SERIAL.print(' ');
+    }
+    USB_SERIAL.print(F("*>\n"));
+  };
+  inline byte len() {return _len;};
+  inline byte *data() {return _data;};
+private:
+  byte _len = 0;
+  byte *_data = NULL;
+};
+#endif

DCCRMT.cpp

@@ -0,0 +1,278 @@
+/*
+ *  © 2021-2024, Harald Barth.
+ *  
+ *  This file is part of DCC-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/*
+ * RMT has "channels" which us FIFO RAM where you place what you want to send
+ * or receive. Channels can be merged to get more words per channel.
+ *
+ * WROOM: 8 channels total of 512 words, 64 words per channel. We use currently
+ * channel 0+1 for 128 words for DCC MAIN and 2+3 for DCC PROG.
+ *
+ * S3: 8 channels total of 384 words. 4 channels dedicated for TX and 4 channels
+ * dedicated for RX. 48 words per channel. So for TX there are 4 channels and we
+ * could use them with 96 words for MAIN and PROG if DCC data does fit in there.
+ *
+ * C3: 4 channels total of 192 words. As we do not use RX we can use all for TX
+ * so the situation is the same as for the -S3
+ *
+ * C6, H2: 4 channels total of 192 words. 2 channels dedictaed for TX and
+ * 2 channels dedicated for RX. Half RMT capacity compared to the C3.
+ *
+ */
+
+#if defined(ARDUINO_ARCH_ESP32)
+#include "defines.h"
+#include "DIAG.h"
+#include "DCCRMT.h"
+#include "DCCTimer.h"
+#include "DCCWaveform.h" // for MAX_PACKET_SIZE
+#include "soc/gpio_sig_map.h"
+
+// check for right type of ESP32
+#include "soc/soc_caps.h"
+#ifndef SOC_RMT_MEM_WORDS_PER_CHANNEL
+#error This symobol should be defined
+#endif
+#if SOC_RMT_MEM_WORDS_PER_CHANNEL < 64
+#warning This is not an ESP32-WROOM but some other unsupported variant
+#warning You are outside of the DCC-EX supported hardware
+#endif
+
+static const byte RMT_CHAN_PER_DCC_CHAN = 2;
+
+// Number of bits resulting out of X bytes of DCC payload data
+// Each byte has one bit extra and at the end we have one EOF marker
+#define DATA_LEN(X) ((X)*9+1)
+
+#if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(4,2,0)
+#error wrong IDF version
+#endif
+
+void setDCCBit1(rmt_item32_t* item) {
+  item->level0    = 1;
+  item->duration0 = DCC_1_HALFPERIOD;
+  item->level1    = 0;
+  item->duration1 = DCC_1_HALFPERIOD;
+}
+
+void setDCCBit0(rmt_item32_t* item) {
+  item->level0    = 1;
+  item->duration0 = DCC_0_HALFPERIOD;
+  item->level1    = 0;
+  item->duration1 = DCC_0_HALFPERIOD;
+}
+
+// special long zero to trigger scope
+void setDCCBit0Long(rmt_item32_t* item) {
+  item->level0    = 1;
+  item->duration0 = DCC_0_HALFPERIOD + DCC_0_HALFPERIOD/10;
+  item->level1    = 0;
+  item->duration1 = DCC_0_HALFPERIOD + DCC_0_HALFPERIOD/10;
+}
+
+void setEOT(rmt_item32_t* item) {
+  item->val = 0;
+}
+
+// This is an array that contains the this pointers
+// to all uses channel objects. This is used to determine
+// which of the channels was triggering the ISR as there
+// is only ONE common ISR routine for all channels.
+RMTChannel *channelHandle[8] = { 0 };
+
+void IRAM_ATTR interrupt(rmt_channel_t channel, void *t) {
+  RMTChannel *tt = channelHandle[channel];
+  if (tt) tt->RMTinterrupt();
+  if (channel == 0)
+    DCCTimer::updateMinimumFreeMemoryISR(0);
+}
+
+RMTChannel::RMTChannel(pinpair pins, bool isMain) {
+  byte ch;
+  byte plen;
+
+  // Below we check if the DCC packet actually fits into the RMT hardware
+  // Currently MAX_PACKET_SIZE = 5 so with checksum there are
+  // MAX_PACKET_SIZE+1 data packets. Each need DATA_LEN (9) bits.
+  // To that we add the preamble length, the fencepost DCC end bit
+  // and the RMT EOF marker.
+  // SOC_RMT_MEM_WORDS_PER_CHANNEL is either 64 (original WROOM) or
+  // 48 (all other ESP32 like the -C3 or -S2
+  // The formula to get the possible MAX_PACKET_SIZE is
+  //
+  // ALLOCATED = RMT_CHAN_PER_DCC_CHAN * SOC_RMT_MEM_WORDS_PER_CHANNEL
+  // MAX_PACKET_SIZE = floor((ALLOCATED - PREAMBLE_LEN - 2)/9 - 1)
+  //
+
+  if (isMain) {
+    ch = 0;
+    plen = PREAMBLE_BITS_MAIN;
+    static_assert (DATA_LEN(MAX_PACKET_SIZE+1) + PREAMBLE_BITS_MAIN + 2 <= RMT_CHAN_PER_DCC_CHAN * SOC_RMT_MEM_WORDS_PER_CHANNEL,
+		  "Number of DCC packet bits greater than ESP32 RMT memory available");
+  } else {
+    ch = RMT_CHAN_PER_DCC_CHAN; // number == offset
+    plen = PREAMBLE_BITS_PROG;
+    static_assert (DATA_LEN(MAX_PACKET_SIZE+1) + PREAMBLE_BITS_PROG + 2 <= RMT_CHAN_PER_DCC_CHAN * SOC_RMT_MEM_WORDS_PER_CHANNEL,
+		   "Number of DCC packet bits greater than ESP32 RMT memory available");
+  }
+    
+  // preamble
+  preambleLen = plen+2; // plen 1 bits, one 0 bit and one EOF marker
+  preamble = (rmt_item32_t*)malloc(preambleLen*sizeof(rmt_item32_t));
+  for (byte n=0; n<plen; n++)
+    setDCCBit1(preamble + n);      // preamble bits
+#ifdef SCOPE
+  setDCCBit0Long(preamble + plen); // start of packet 0 bit long version
+#else
+  setDCCBit0(preamble + plen);     // start of packet 0 bit normal version
+#endif
+  setEOT(preamble + plen + 1);     // EOT marker
+
+  // idle
+  idleLen = 28;
+  idle = (rmt_item32_t*)malloc(idleLen*sizeof(rmt_item32_t));
+  if (isMain) {
+    for (byte n=0; n<8; n++)   // 0 to 7
+      setDCCBit1(idle + n);
+    for (byte n=8; n<18; n++)  // 8, 9 to 16, 17
+      setDCCBit0(idle + n);
+    for (byte n=18; n<26; n++) // 18 to 25
+      setDCCBit1(idle + n);
+  } else {
+    for (byte n=0; n<26; n++)  // all zero
+      setDCCBit0(idle + n);
+  }
+  setDCCBit1(idle + 26);     // end bit
+  setEOT(idle + 27);         // EOT marker
+
+  // data: max packet size today is 5 + checksum
+  maxDataLen = DATA_LEN(MAX_PACKET_SIZE+1);  // plus checksum
+  data = (rmt_item32_t*)malloc(maxDataLen*sizeof(rmt_item32_t));
+
+  rmt_config_t config;
+  // Configure the RMT channel for TX
+  bzero(&config, sizeof(rmt_config_t));
+  config.rmt_mode = RMT_MODE_TX;
+  config.channel = channel = (rmt_channel_t)ch;
+  config.clk_div = RMT_CLOCK_DIVIDER;
+  config.gpio_num = (gpio_num_t)pins.pin;
+  config.mem_block_num = RMT_CHAN_PER_DCC_CHAN;
+  // use config
+  ESP_ERROR_CHECK(rmt_config(&config));
+  addPin(pins.invpin, true);
+  
+  // NOTE: ESP_INTR_FLAG_IRAM is *NOT* included in this bitmask
+  ESP_ERROR_CHECK(rmt_driver_install(config.channel, 0, ESP_INTR_FLAG_LOWMED|ESP_INTR_FLAG_SHARED));
+
+  // DIAG(F("Register interrupt on core %d"), xPortGetCoreID());
+
+  ESP_ERROR_CHECK(rmt_set_tx_loop_mode(channel, true));
+  channelHandle[channel] = this; // used by interrupt
+  rmt_register_tx_end_callback(interrupt, 0);
+  rmt_set_tx_intr_en(channel, true);
+
+  DIAG(F("Channel %d DCC signal for %s start"), config.channel, isMain ? "MAIN" : "PROG");
+
+  // send one bit to kickstart the signal, remaining data will come from the
+  // packet queue. We intentionally do not wait for the RMT TX complete here.
+  //rmt_write_items(channel, preamble, preambleLen, false);
+  RMTprefill();
+  dataReady = false;
+}
+
+void RMTChannel::RMTprefill() {
+  rmt_fill_tx_items(channel, preamble, preambleLen, 0);
+  rmt_fill_tx_items(channel, idle, idleLen, preambleLen-1);
+}
+
+const byte transmitMask[] = {0x80, 0x40, 0x20, 0x10, 0x08, 0x04, 0x02, 0x01};
+
+int RMTChannel::RMTfillData(const byte buffer[], byte byteCount, byte repeatCount=0) {
+  //int RMTChannel::RMTfillData(dccPacket packet) {
+  // dataReady: Signals to then interrupt routine. It is set when
+  // we have data in the channel buffer which can be copied out
+  // to the HW. dataRepeat on the other hand signals back to
+  // the caller of this function if the data has been sent enough
+  // times (0 to 3 means 1 to 4 times in total).
+  if (dataRepeat > 0) // we have still old work to do
+    return dataRepeat;
+  if (dataReady == true) // the packet is not copied out yet
+    return 1000;
+  if (DATA_LEN(byteCount) > maxDataLen) {  // this would overun our allocated memory for data
+    DIAG(F("Can not convert DCC bytes # %d to DCC bits %d, buffer too small"), byteCount, maxDataLen);
+    return -1;                          // something very broken, can not convert packet
+  }
+
+  // convert bytes to RMT stream of "bits"
+  byte bitcounter = 0;
+  for(byte n=0; n<byteCount; n++) {
+    for(byte bit=0; bit<8; bit++) {
+      if (buffer[n] & transmitMask[bit])
+	setDCCBit1(data + bitcounter++);
+      else
+	setDCCBit0(data + bitcounter++);
+    }
+    setDCCBit0(data + bitcounter++); // zero at end of each byte
+  }
+  setDCCBit1(data + bitcounter-1);     // overwrite previous zero bit with one bit
+  setEOT(data + bitcounter++);         // EOT marker
+  dataLen = bitcounter;
+  noInterrupts();                      // keep dataReady and dataRepeat consistnet to each other
+  dataReady = true;
+  dataRepeat = repeatCount+1;         // repeatCount of 0 means send once
+  interrupts();
+  return 0;
+}
+
+void IRAM_ATTR RMTChannel::RMTinterrupt() {
+  //no rmt_tx_start(channel,true) as we run in loop mode
+  //preamble is always loaded at beginning of buffer
+  packetCounter++;
+  if (!dataReady && dataRepeat == 0) { // we did run empty
+    rmt_fill_tx_items(channel, idle, idleLen, preambleLen-1);
+    return; // nothing to do about that
+  }
+
+  // take care of incoming data
+  if (dataReady) {            // if we have new data, fill while preamble is running
+    rmt_fill_tx_items(channel, data, dataLen, preambleLen-1);
+    dataReady = false;
+    if (dataRepeat == 0)       // all data should go out at least once
+      DIAG(F("Channel %d DCC signal lost data"), channel);
+  }
+  if (dataRepeat > 0)         // if a repeat count was specified, work on that
+    dataRepeat--;
+}
+
+bool RMTChannel::addPin(byte pin, bool inverted) {
+  if (pin == UNUSED_PIN)
+    return true;
+  gpio_num_t gpioNum = (gpio_num_t)(pin);
+  esp_err_t err;
+  PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[gpioNum], PIN_FUNC_GPIO);
+  err = gpio_set_direction(gpioNum, GPIO_MODE_OUTPUT);
+  if (err != ESP_OK) return false;
+  gpio_matrix_out(gpioNum, RMT_SIG_OUT0_IDX+channel, inverted, 0);
+  if (err != ESP_OK) return false;
+  return true;
+}
+bool RMTChannel::addPin(pinpair pins) {
+  return addPin(pins.pin) && addPin(pins.invpin, true);
+}
+#endif //ESP32

DCCRMT.h

@@ -0,0 +1,72 @@
+/*
+ *  © 2021-2022, Harald Barth.
+ *  
+ *  This file is part of DCC-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#if defined(ARDUINO_ARCH_ESP32)
+#pragma once
+#include <Arduino.h>
+#include "driver/rmt.h"
+#include "soc/rmt_reg.h"
+#include "soc/rmt_struct.h"
+#include "MotorDriver.h" // for class pinpair
+
+// make calculations easy and set up for microseconds
+#define RMT_CLOCK_DIVIDER 80
+#define DCC_1_HALFPERIOD 58  //4640 // 1 / 80000000 * 4640 = 58us
+#define DCC_0_HALFPERIOD 100 //8000
+
+class RMTChannel {
+ public:
+  RMTChannel(pinpair pins, bool isMain);
+  bool addPin(byte pin, bool inverted=0);
+  bool addPin(pinpair pins);
+  void IRAM_ATTR RMTinterrupt();
+  void RMTprefill();
+  //int RMTfillData(dccPacket packet);
+  int RMTfillData(const byte buffer[], byte byteCount, byte repeatCount);
+  inline bool busy() {
+    if (dataRepeat > 0) // we have still old work to do
+      return true;
+    return dataReady;
+  };
+  inline void waitForDataCopy() {
+    while(1) { // do nothing and wait for interrupt clearing dataReady to happen
+      if (dataReady == false)
+	break;
+    }
+  };
+  inline uint32_t packetCount() { return packetCounter; };
+  
+ private:
+    
+  rmt_channel_t channel;
+  // 3 types of data to send, preamble and then idle or data
+  // if this is prog track, idle will contain reset instead
+  rmt_item32_t *idle;
+  byte idleLen;
+  rmt_item32_t *preamble;
+  byte preambleLen;
+  rmt_item32_t *data;
+  byte dataLen;
+  byte maxDataLen;
+  uint32_t packetCounter = 0;
+  // flags 
+  volatile bool dataReady = false;    // do we have real data available or send idle
+  volatile byte dataRepeat = 0;
+};
+#endif //ESP32

DCCTimer.cpp

@@ -1,213 +0,0 @@
-/*
- *  © 2021, Chris Harlow & David Cutting. All rights reserved.
- *  
- *  This file is part of Asbelos DCC API
- *
- *  This 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.
- *
- *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-
-/* This timer class is used to manage the single timer required to handle the DCC waveform.
- *  All timer access comes through this class so that it can be compiled for 
- *  various hardware CPU types. 
- *  
- *  DCCEX works on a single timer interrupt at a regular 58uS interval.
- *  The DCCWaveform class generates the signals to the motor shield  
- *  based on this timer. 
- *  
- *  If the motor drivers are BOTH configured to use the correct 2 pins for the architecture,
- *  (see isPWMPin() function. )
- *  then this allows us to use a hardware driven pin switching arrangement which is
- *  achieved by setting the duty cycle of the NEXT clock interrupt to 0% or 100% depending on 
- *  the required pin state. (see setPWM())  
- *  This is more accurate than the software interrupt but at the expense of 
- *  limiting the choice of available pins. 
- *  Fortunately, a standard motor shield on a Mega uses pins that qualify for PWM... 
- *  Other shields may be jumpered to PWM pins or run directly using the software interrupt.
- *  
- *  Because the PWM-based waveform is effectively set half a cycle after the software version,
- *  it is not acceptable to drive the two tracks on different methiods or it would cause
- *  problems for <1 JOIN> etc.
- *  
- */
-
-#include "DCCTimer.h"
-const int DCC_SIGNAL_TIME=58;  // this is the 58uS DCC 1-bit waveform half-cycle 
-const long CLOCK_CYCLES=(F_CPU / 1000000 * DCC_SIGNAL_TIME) >>1;
-
-INTERRUPT_CALLBACK interruptHandler=0;
-
-#ifdef ARDUINO_ARCH_MEGAAVR
-  // Arduino unoWifi Rev2 and nanoEvery architectire 
-  
-  void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
-    interruptHandler=callback;
-    noInterrupts(); 
-    ADC0.CTRLC = (ADC0.CTRLC & 0b00110000) | 0b01000011;  // speed up analogRead sample time   
-    TCB0.CTRLB = TCB_CNTMODE_INT_gc & ~TCB_CCMPEN_bm; // timer compare mode with output disabled
-    TCB0.CTRLA = TCB_CLKSEL_CLKDIV2_gc; //   8 MHz ~ 0.125 us      
-    TCB0.CCMP =  CLOCK_CYCLES -1;  // 1 tick less for timer reset
-    TCB0.INTFLAGS = TCB_CAPT_bm; // clear interrupt request flag
-    TCB0.INTCTRL = TCB_CAPT_bm;  // Enable the interrupt
-    TCB0.CNT = 0;
-    TCB0.CTRLA |= TCB_ENABLE_bm;  // start
-    interrupts();
-  }
-
-  // ISR called by timer interrupt every 58uS
-  ISR(TCB0_INT_vect){
-    TCB0.INTFLAGS = TCB_CAPT_bm;
-    interruptHandler();
-  }
-
-  bool DCCTimer::isPWMPin(byte pin) {
-       (void) pin; 
-       return false;  // TODO what are the relevant pins? 
-  }
-
- void DCCTimer::setPWM(byte pin, bool high) {
-    (void) pin;
-    (void) high;
-    // TODO what are the relevant pins?
- }
-
-  void   DCCTimer::getSimulatedMacAddress(byte mac[6]) {
-    memcpy(mac,(void *) &SIGROW.SERNUM0,6);  // serial number
-    mac[0] &= 0xFE;
-    mac[0] |= 0x02;
-  }
-
-#elif defined(TEENSYDUINO)
-  IntervalTimer myDCCTimer;
-
-  void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
-    interruptHandler=callback;
-
-  myDCCTimer.begin(interruptHandler, DCC_SIGNAL_TIME);
-
-  }
-
-  bool DCCTimer::isPWMPin(byte pin) {
-       //Teensy: digitalPinHasPWM, todo
-      (void) pin;
-       return false;  // TODO what are the relevant pins? 
-  }
-
- void DCCTimer::setPWM(byte pin, bool high) {
-    // TODO what are the relevant pins?
-    (void) pin;
-    (void) high;
-}
-
-  void   DCCTimer::getSimulatedMacAddress(byte mac[6]) {
-#if defined(__IMXRT1062__)  //Teensy 4.0 and Teensy 4.1
-    uint32_t m1 = HW_OCOTP_MAC1;
-    uint32_t m2 = HW_OCOTP_MAC0;
-    mac[0] = m1 >> 8;
-    mac[1] = m1 >> 0;
-    mac[2] = m2 >> 24;
-    mac[3] = m2 >> 16;
-    mac[4] = m2 >> 8;
-    mac[5] = m2 >> 0;
-#else
-    read_mac(mac);
-#endif
-  }
-
-#if !defined(__IMXRT1062__)
-  void DCCTimer::read_mac(byte mac[6]) {
-    read(0xe,mac,0);
-    read(0xf,mac,3);
-  }
-
-// http://forum.pjrc.com/threads/91-teensy-3-MAC-address
-void DCCTimer::read(uint8_t word, uint8_t *mac, uint8_t offset) {
-  FTFL_FCCOB0 = 0x41;             // Selects the READONCE command
-  FTFL_FCCOB1 = word;             // read the given word of read once area
-
-  // launch command and wait until complete
-  FTFL_FSTAT = FTFL_FSTAT_CCIF;
-  while(!(FTFL_FSTAT & FTFL_FSTAT_CCIF));
-
-  *(mac+offset) =   FTFL_FCCOB5;       // collect only the top three bytes,
-  *(mac+offset+1) = FTFL_FCCOB6;       // in the right orientation (big endian).
-  *(mac+offset+2) = FTFL_FCCOB7;       // Skip FTFL_FCCOB4 as it's always 0.
-}
-#endif
-
-#else 
-  // Arduino nano, uno, mega etc
-#if defined(__AVR_ATmega1280__) || defined(__AVR_ATmega2560__)
-    #define TIMER1_A_PIN   11
-    #define TIMER1_B_PIN   12
-    #define TIMER1_C_PIN   13
-#else
-   #define TIMER1_A_PIN   9
-   #define TIMER1_B_PIN   10
-#endif
-
-  void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
-    interruptHandler=callback;
-    noInterrupts();          
-    ADCSRA = (ADCSRA & 0b11111000) | 0b00000100;   // speed up analogRead sample time 
-    TCCR1A = 0;
-    ICR1 = CLOCK_CYCLES;
-    TCNT1 = 0;   
-    TCCR1B = _BV(WGM13) | _BV(CS10);     // Mode 8, clock select 1
-    TIMSK1 = _BV(TOIE1); // Enable Software interrupt
-    interrupts();
-  }
-
-// ISR called by timer interrupt every 58uS
-  ISR(TIMER1_OVF_vect){ interruptHandler(); }
-
-// Alternative pin manipulation via PWM control.
-  bool DCCTimer::isPWMPin(byte pin) {
-       return pin==TIMER1_A_PIN 
-           || pin==TIMER1_B_PIN
-       #ifdef TIMER1_C_PIN 
-           || pin==TIMER1_C_PIN
-       #endif       
-       ;
-  }
-
- void DCCTimer::setPWM(byte pin, bool high) {
-    if (pin==TIMER1_A_PIN) {
-      TCCR1A |= _BV(COM1A1);
-      OCR1A= high?1024:0;
-    }
-    else if (pin==TIMER1_B_PIN) { 
-      TCCR1A |= _BV(COM1B1);
-      OCR1B= high?1024:0;
-    }
- #ifdef TIMER1_C_PIN 
-    else if (pin==TIMER1_C_PIN) { 
-      TCCR1A |= _BV(COM1C1);
-      OCR1C= high?1024:0;
-    }
- #endif       
- }
-
-
-  #include <avr/boot.h> 
-  void DCCTimer::getSimulatedMacAddress(byte mac[6]) {
-    for (byte i=0; i<6; i++) {
-      mac[i]=boot_signature_byte_get(0x0E + i);
-    }
-    mac[0] &= 0xFE;
-    mac[0] |= 0x02;
-
-  }
-
-#endif

DCCTimer.h

@@ -1,6 +1,9 @@
 /*
- *  (c) 2021 Mike S. All rights reserved.
- *  (c) 2021 Fred Decker.  All rights reserved.
+ *  © 2022-2024 Paul M. Antoine
+ *  © 2021 Mike S
+ *  © 2021-2023 Harald Barth
+ *  © 2021 Fred Decker
+ *  All rights reserved.
  *  
  *  This file is part of CommandStation-EX
  *
@@ -18,6 +21,34 @@
  *  along with CommandStation.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+/* There are several different implementations of this class which the compiler will select 
+   according to the hardware.
+   */
+
+/* This timer class is used to manage the single timer required to handle the DCC waveform.
+ *  All timer access comes through this class so that it can be compiled for 
+ *  various hardware CPU types. 
+ *  
+ *  DCCEX works on a single timer interrupt at a regular 58uS interval.
+ *  The DCCWaveform class generates the signals to the motor shield  
+ *  based on this timer. 
+ *  
+ *  If the motor drivers are BOTH configured to use the correct 2 pins for the architecture,
+ *  (see isPWMPin() function. )
+ *  then this allows us to use a hardware driven pin switching arrangement which is
+ *  achieved by setting the duty cycle of the NEXT clock interrupt to 0% or 100% depending on 
+ *  the required pin state. (see setPWM())  
+ *  This is more accurate than the software interrupt but at the expense of 
+ *  limiting the choice of available pins. 
+ *  Fortunately, a standard motor shield on a Mega uses pins that qualify for PWM... 
+ *  Other shields may be jumpered to PWM pins or run directly using the software interrupt.
+ *  
+ *  Because the PWM-based waveform is effectively set half a cycle after the software version,
+ *  it is not acceptable to drive the two tracks on different methiods or it would cause
+ *  problems for <1 JOIN> etc.
+ *  
+ */
+
 #ifndef DCCTimer_h
 #define DCCTimer_h
 #include "Arduino.h"
@@ -30,11 +61,90 @@ class DCCTimer {
   static void getSimulatedMacAddress(byte mac[6]);
   static bool isPWMPin(byte pin);
   static void setPWM(byte pin, bool high);
-#if (defined(TEENSYDUINO) && !defined(__IMXRT1062__))
-  static void read_mac(byte mac[6]);
-  static void read(uint8_t word, uint8_t *mac, uint8_t offset);
+  static void clearPWM();
+  static void startRailcomTimer(byte brakePin);
+  static void ackRailcomTimer();
+  static void DCCEXanalogWriteFrequency(uint8_t pin, uint32_t frequency);
+  static void DCCEXanalogWrite(uint8_t pin, int value, bool invert);
+  static void DCCEXledcDetachPin(uint8_t pin);
+  static void DCCEXanalogCopyChannel(int8_t frompin, int8_t topin);
+  static void DCCEXInrushControlOn(uint8_t pin, int duty, bool invert);
+  static void DCCEXledcAttachPin(uint8_t pin, int8_t channel, bool inverted);
+
+// Update low ram level.  Allow for extra bytes to be specified
+// by estimation or inspection, that may be used by other 
+// called subroutines.  Must be called with interrupts disabled.
+// 
+// Although __brkval may go up and down as heap memory is allocated
+// and freed, this function records only the worst case encountered.
+// So even if all of the heap is freed, the reported minimum free 
+// memory will not increase.
+//
+  static void inline updateMinimumFreeMemoryISR(unsigned char extraBytes=0)
+    __attribute__((always_inline)) {
+    int spare = freeMemory()-extraBytes;
+    if (spare < 0) spare = 0;
+    if (spare < minimum_free_memory) minimum_free_memory = spare;
+  };
+
+  static int  getMinimumFreeMemory();
+  static void reset();
+  
+private:
+  static void DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t frequency);
+  static int freeMemory();
+  static volatile int minimum_free_memory;
+  static const int DCC_SIGNAL_TIME=58;  // this is the 58uS DCC 1-bit waveform half-cycle 
+#if defined(ARDUINO_ARCH_STM32)  // TODO: PMA temporary hack - assumes 100Mhz F_CPU as STM32 can change frequency
+  static const long CLOCK_CYCLES=(100000000L / 1000000 * DCC_SIGNAL_TIME) >>1;
+#else
+  static const long CLOCK_CYCLES=(F_CPU / 1000000 * DCC_SIGNAL_TIME) >>1;
 #endif
-  private:
+
 };
 
+// Class ADCee implements caching of the ADC value for platforms which
+// have a too slow ADC read to wait for. On these platforms the ADC is
+// scanned continiously in the background from an ISR. On such
+// architectures that use the analog read during DCC waveform with
+// specially configured ADC, for example AVR, init must be called
+// PRIOR to the start of the waveform. It returns the current value so
+// that an offset can be initialized.
+class ADCee {
+public:
+  // begin is called for any setup that must be done before
+  // **init** can be called. On some architectures this involves ADC
+  // initialisation and clock routing, sampling times etc.
+  static void begin();
+  // init adds the pin to the list of scanned pins (if this
+  // platform's implementation scans pins) and returns the first
+  // read value (which is why it required begin to have been called first!)
+  // It must be called before the regular scan is started.
+  static int init(uint8_t pin);
+  // read does read the pin value from the scanned cache or directly
+  // if this is a platform that does not scan. fromISR is a hint if
+  // it was called from ISR because for some implementations that
+  // makes a difference.
+  static int read(uint8_t pin, bool fromISR=false);
+  // returns possible max value that the ADC can return
+  static int16_t ADCmax();
+private:
+  // On platforms that scan, it is called from waveform ISR
+  // only on a regular basis.
+  static void scan();
+  #if defined (ARDUINO_ARCH_STM32)
+  // bit array of used pins (max 32)
+  static uint32_t usedpins;
+  static uint32_t * analogchans;        // Array of channel numbers to be scanned
+  static ADC_TypeDef * * adcchans;      // Array to capture which ADC is each input channel on
+#else
+  // bit array of used pins (max 16)
+  static uint16_t usedpins;
+#endif
+  static uint8_t highestPin;
+  // cached analog values (malloc:ed to actual number of ADC channels)
+  static int *analogvals;
+  // friend so that we can call scan() and begin()
+  friend class DCCWaveform;
+  };
 #endif

DCCTimerAVR.cpp

@@ -0,0 +1,398 @@
+/*
+ *  © 2021 Mike S
+ *  © 2021-2023 Harald Barth
+ *  © 2021 Fred Decker
+ *  © 2021 Chris Harlow
+ *  © 2021 David Cutting
+ *  All rights reserved.
+ *  
+ *  This file is part of Asbelos DCC API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// ATTENTION: this file only compiles on a UNO or MEGA
+// Please refer to DCCTimer.h for general comments about how this class works
+// This is to avoid repetition and duplication.
+#ifdef ARDUINO_ARCH_AVR
+#include <avr/boot.h> 
+#include <avr/wdt.h>
+#include "DCCTimer.h"
+#include "DIAG.h"
+#ifdef DEBUG_ADC
+#include "TrackManager.h"
+#endif
+INTERRUPT_CALLBACK interruptHandler=0;
+
+  // Arduino nano, uno, mega etc
+#if defined(__AVR_ATmega1280__) || defined(__AVR_ATmega2560__)
+    #define TIMER1_A_PIN   11
+    #define TIMER1_B_PIN   12
+    #define TIMER1_C_PIN   13
+    #define TIMER2_A_PIN   10
+    #define TIMER2_B_PIN   9
+    
+#else
+   #define TIMER1_A_PIN   9
+   #define TIMER1_B_PIN   10
+#endif
+
+void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
+    interruptHandler=callback;
+    noInterrupts();
+    TCCR1A = 0;
+    ICR1 = CLOCK_CYCLES;
+    TCNT1 = 0;   
+    TCCR1B = _BV(WGM13) | _BV(CS10);     // Mode 8, clock select 1
+    TIMSK1 = _BV(TOIE1); // Enable Software interrupt
+    interrupts();
+  }
+
+
+void DCCTimer::startRailcomTimer(byte brakePin) {
+#if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)
+  /* The Railcom timer is started in such a way that it 
+     - First triggers 28uS after the last TIMER1 tick. 
+       This provides an accurate offset (in High Accuracy mode)
+       for the start of the Railcom cutout.
+     - Sets the Railcom pin high at first tick, 
+       because its been setup with 100% PWM duty cycle.
+        
+     - Cycles at 436uS so the second tick is the 
+        correct distance from the cutout.
+        
+     - Waveform code is responsible for altering the PWM 
+       duty cycle to 0% any time between the first and last tick.
+       (there will be 7 DCC timer1 ticks in which to do this.)
+    
+    */
+  (void) brakePin; // Ignored... works on pin 9 only 
+  const int cutoutDuration = 430; // Desired interval in microseconds
+  
+  // Set up Timer2 for CTC mode (Clear Timer on Compare Match)
+  TCCR2A = 0; // Clear Timer2 control register A
+  TCCR2B = 0; // Clear Timer2 control register B
+  TCNT2 = 0;  // Initialize Timer2 counter value to 0
+   // Configure Phase and Frequency Correct PWM mode
+   TCCR2A =  (1 << COM2B1); // enable pwm on pin 9
+   TCCR2A |= (1 << WGM20);
+  
+   
+  // Set Timer 2 prescaler to 32
+  TCCR2B = (1 << CS21) | (1 << CS20); // 32 prescaler
+
+  // Set the compare match value for desired interval
+  OCR2A = (F_CPU / 1000000) * cutoutDuration / 64 - 1;
+
+  // Calculate the compare match value for desired duty cycle
+  OCR2B = OCR2A+1;  // set duty cycle to 100%= OCR2A)
+
+  // Enable Timer2 output on pin 9 (OC2B)
+  DDRB |= (1 << DDB1);
+  // TODO Fudge TCNT2 to sync with last tcnt1 tick + 28uS
+
+ // Previous TIMER1 Tick was at rising end-of-packet bit
+ // Cutout starts half way through first preamble
+ // that is 2.5 * 58uS later.
+ // TCNT1 ticks 8 times / microsecond
+ // auto microsendsToFirstRailcomTick=(58+58+29)-(TCNT1/8);
+  // set the railcom timer counter allowing for phase-correct
+
+  // CHris's NOTE: 
+  // I dont kniow quite how this calculation works out but
+  // it does seems to get a good answer. 
+
+  TCNT2=193 + (ICR1 - TCNT1)/8;
+#endif
+}
+
+void DCCTimer::ackRailcomTimer() {
+#if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)
+  OCR2B= 0x00;  // brake pin pwm duty cycle 0 at next tick
+#endif
+}
+
+
+// ISR called by timer interrupt every 58uS
+  ISR(TIMER1_OVF_vect){ interruptHandler(); }
+
+// Alternative pin manipulation via PWM control.
+  bool DCCTimer::isPWMPin(byte pin) {
+       return pin==TIMER1_A_PIN 
+           || pin==TIMER1_B_PIN
+       #ifdef TIMER1_C_PIN 
+           || pin==TIMER1_C_PIN
+       #endif       
+       ;
+  }
+
+ void DCCTimer::setPWM(byte pin, bool high) {
+    if (pin==TIMER1_A_PIN) {
+      TCCR1A |= _BV(COM1A1);
+      OCR1A= high?1024:0;
+    }
+    else if (pin==TIMER1_B_PIN) { 
+      TCCR1A |= _BV(COM1B1);
+      OCR1B= high?1024:0;
+    }
+ #ifdef TIMER1_C_PIN 
+    else if (pin==TIMER1_C_PIN) { 
+      TCCR1A |= _BV(COM1C1);
+      OCR1C= high?1024:0;
+    }
+ #endif       
+ }
+
+void DCCTimer::clearPWM() {
+  TCCR1A= 0;
+}
+
+  void DCCTimer::getSimulatedMacAddress(byte mac[6]) {
+    for (byte i=0; i<6; i++) {
+      // take the fist 3 and last 3 of the serial.
+      // the first 5 of 8 are at 0x0E to 0x013
+      // the last  3 of 8 are at 0x15 to 0x017
+      mac[i]=boot_signature_byte_get(0x0E + i + (i>2? 4 : 0));
+    }
+    mac[0] &= 0xFE;
+    mac[0] |= 0x02;
+  }
+
+
+volatile int DCCTimer::minimum_free_memory=__INT_MAX__;
+
+// Return low memory value... 
+int DCCTimer::getMinimumFreeMemory() {
+  noInterrupts(); // Disable interrupts to get volatile value 
+  int retval = minimum_free_memory;
+  interrupts();
+  return retval;
+}
+
+extern char *__brkval;
+extern char *__malloc_heap_start;
+
+int DCCTimer::freeMemory() {
+  char top;
+  return __brkval ? &top - __brkval : &top - __malloc_heap_start;
+}
+
+void DCCTimer::reset() {
+  // 250ms chosen to circumwent bootloader bug which
+  // hangs at too short timepout (like 15ms)
+  wdt_enable( WDTO_250MS); // set Arduino watchdog timer for 250ms 
+  delay(500);              // wait for it to happen
+
+}
+
+void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) {
+  DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, f);
+}
+void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t fbits) {
+#if defined(ARDUINO_AVR_UNO)
+      (void)fbits;
+      (void) pin;
+      // Not worth doin something here as:
+      // If we are on pin 9 or 10 we are on Timer1 and we can not touch Timer1 as that is our DCC source.
+      // If we are on pin 5 or 6 we are on Timer 0 ad we can not touch Timer0 as that is millis() etc.
+      // We are most likely not on pin 3 or 11 as no known motor shield has that as brake.
+#endif
+#if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)
+  // Speed mapping is done like this:
+  // No functions buttons:   000  0   -> low          131Hz
+  // Only F29 pressed        001  1   -> mid          490Hz
+  // F30 with or w/o F29     01x  2-3 -> high        3400Hz
+  // F31 with or w/o F29/30  1xx  4-7 -> supersonic 62500Hz
+  uint8_t abits;
+  uint8_t bbits;
+  if (pin == 9 || pin == 10) { // timer 2 is different
+
+    if (fbits >= 4)
+      abits = B00000011;
+    else
+      abits = B00000001;
+
+    if (fbits >= 4)
+      bbits = B0001;
+    else if (fbits >= 2)
+      bbits = B0010;
+    else if (fbits == 1)
+      bbits = B0100;
+    else //  fbits == 0
+      bbits = B0110;
+
+    TCCR2A = (TCCR2A & B11111100) | abits; // set WGM0 and WGM1
+    TCCR2B = (TCCR2B & B11110000) | bbits; // set WGM2 and 3 bits of prescaler
+    DIAG(F("Timer 2 A=%x B=%x"), TCCR2A, TCCR2B);
+
+  } else { // not timer 9 or 10
+    abits = B01;
+
+    if (fbits >= 4)
+      bbits = B1001;
+    else if (fbits >= 2)
+      bbits = B0010;
+    else if (fbits == 1)
+      bbits = B0011;
+    else
+      bbits = B0100;
+
+    switch (pin) {
+      // case 9 and 10 taken care of above by if()
+    case 6:
+    case 7:
+    case 8:
+      // Timer4
+      TCCR4A = (TCCR4A & B11111100) | abits; // set WGM0 and WGM1
+      TCCR4B = (TCCR4B & B11100000) | bbits; // set WGM2 and WGM3 and divisor
+      //DIAG(F("Timer 4 A=%x B=%x"), TCCR4A, TCCR4B);
+      break;
+    case 46:
+    case 45:
+    case 44:
+      // Timer5
+      TCCR5A = (TCCR5A & B11111100) | abits; // set WGM0 and WGM1
+      TCCR5B = (TCCR5B & B11100000) | bbits; // set WGM2 and WGM3 and divisor
+      //DIAG(F("Timer 5 A=%x B=%x"), TCCR5A, TCCR5B);
+      break;
+    default:
+      break;
+    }
+  }
+#endif
+}
+
+#if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)
+#define NUM_ADC_INPUTS 16
+#else
+#define NUM_ADC_INPUTS 8
+#endif
+uint16_t ADCee::usedpins = 0;
+uint8_t ADCee::highestPin = 0;
+int * ADCee::analogvals = NULL;
+static bool ADCusesHighPort = false;
+
+/*
+ * Register a new pin to be scanned
+ * Returns current reading of pin and
+ * stores that as well
+ */
+int ADCee::init(uint8_t pin) {
+  uint8_t id = pin - A0;
+  if (id >= NUM_ADC_INPUTS)
+    return -1023;
+  if (id > 7)
+    ADCusesHighPort = true;
+  pinMode(pin, INPUT);
+  int value = analogRead(pin);
+  if (analogvals == NULL)
+    analogvals = (int *)calloc(NUM_ADC_INPUTS, sizeof(int));
+  analogvals[id] = value;
+  usedpins |= (1<<id);
+  if (id > highestPin) highestPin = id;
+  return value;
+}
+int16_t ADCee::ADCmax() {
+  return 1023;
+}
+/*
+ * Read function ADCee::read(pin) to get value instead of analogRead(pin)
+ */
+int ADCee::read(uint8_t pin, bool fromISR) {
+  uint8_t id = pin - A0;
+  if ((usedpins & (1<<id) ) == 0)
+    return -1023;
+  // we do not need to check (analogvals == NULL)
+  // because usedpins would still be 0 in that case
+  if (!fromISR) noInterrupts();
+  int a = analogvals[id];
+  if (!fromISR) interrupts();
+  return a;
+}
+/*
+ * Scan function that is called from interrupt
+ */
+#pragma GCC push_options
+#pragma GCC optimize ("-O3")
+void ADCee::scan() {
+  static byte id = 0;       // id and mask are the same thing but it is faster to
+  static uint16_t mask = 1; // increment and shift instead to calculate mask from id
+  static bool waiting = false;
+
+  if (waiting) {
+    // look if we have a result
+    byte low, high;
+    if (bit_is_set(ADCSRA, ADSC))
+      return; // no result, continue to wait
+    // found value
+    low = ADCL; //must read low before high
+    high = ADCH;
+    bitSet(ADCSRA, ADIF);
+    analogvals[id] = (high << 8) | low;
+    // advance at least one track
+#ifdef DEBUG_ADC
+    if (id == 1) TrackManager::track[1]->setBrake(0);
+#endif
+    waiting = false;
+    id++;
+    mask = mask << 1;
+    if (id > highestPin) {
+      id = 0;
+      mask = 1;
+    }
+  }
+  if (!waiting) {
+    if (usedpins == 0) // otherwise we would loop forever
+      return;
+    // look for a valid track to sample or until we are around
+    while (true) {
+      if (mask  & usedpins) {
+	// start new ADC aquire on id
+#if defined(ADCSRB) && defined(MUX5)
+	if (ADCusesHighPort) { // if we ever have started to use high pins)
+	  if (id > 7)          // if we use a high ADC pin
+	    bitSet(ADCSRB, MUX5); // set MUX5 bit
+	  else
+	    bitClear(ADCSRB, MUX5);
+	}
+#endif
+	ADMUX=(1<<REFS0)|(id & 0x07); //select AVCC as reference and set MUX
+	bitSet(ADCSRA,ADSC); // start conversion
+#ifdef DEBUG_ADC
+	if (id == 1) TrackManager::track[1]->setBrake(1);
+#endif
+	waiting = true;
+	return;
+      }
+      id++;
+      mask = mask << 1;
+      if (id > highestPin) {
+      	id = 0;
+	      mask = 1;
+      }
+    }
+  }
+}
+#pragma GCC pop_options
+
+void ADCee::begin() {
+  noInterrupts();
+  // ADCSRA = (ADCSRA & 0b11111000) | 0b00000100;   // speed up analogRead sample time
+  // Set up ADC for free running mode
+  ADMUX=(1<<REFS0); //select AVCC as reference. We set MUX later
+  ADCSRA = (1<<ADEN)|(1 << ADPS2); // ADPS2 means divisor 32 and 16Mhz/32=500kHz.
+  //bitSet(ADCSRA, ADSC); //do not start the ADC yet. Done when we have set the MUX
+  interrupts();
+}
+#endif

DCCTimerESP.cpp

@@ -0,0 +1,334 @@
+/*
+ *  © 2020-2022 Harald Barth
+ *
+ *  This file is part of CommandStation-EX
+ *  
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// ATTENTION: this file only compiles on an ESP8266 and ESP32
+// On ESP32 we do not even use the functions but they are here for completeness sake
+// Please refer to DCCTimer.h for general comments about how this class works
+// This is to avoid repetition and duplication.
+
+#ifdef ARDUINO_ARCH_ESP8266
+
+#include "DCCTimer.h"
+INTERRUPT_CALLBACK interruptHandler=0;
+
+void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
+  interruptHandler=callback;
+  timer1_disable();
+
+  // There seem to be differnt ways to attach interrupt handler
+  //    ETS_FRC_TIMER1_INTR_ATTACH(NULL, NULL);
+  //    ETS_FRC_TIMER1_NMI_INTR_ATTACH(interruptHandler);
+  // Let us choose the one from the API
+  timer1_attachInterrupt(interruptHandler);
+
+  // not exactly sure of order:
+  timer1_enable(TIM_DIV1, TIM_EDGE, TIM_LOOP);
+  timer1_write(CLOCK_CYCLES);
+}
+// We do not support to use PWM to make the Waveform on ESP
+bool IRAM_ATTR DCCTimer::isPWMPin(byte pin) {
+  return false;
+}
+void IRAM_ATTR DCCTimer::setPWM(byte pin, bool high) {
+}
+void IRAM_ATTR DCCTimer::clearPWM() {
+}
+
+// Fake this as it should not be used
+void   DCCTimer::getSimulatedMacAddress(byte mac[6]) {
+  mac[0] = 0xFE;
+  mac[1] = 0xBE;
+  mac[2] = 0xEF;
+  mac[3] = 0xC0;
+  mac[4] = 0xFF;
+  mac[5] = 0xEE;
+}
+
+volatile int DCCTimer::minimum_free_memory=__INT_MAX__;
+
+// Return low memory value... 
+int DCCTimer::getMinimumFreeMemory() {
+  noInterrupts(); // Disable interrupts to get volatile value 
+  int retval = minimum_free_memory;
+  interrupts();
+  return retval;
+}
+
+int DCCTimer::freeMemory() {
+  return ESP.getFreeHeap();
+}
+#endif
+
+////////////////////////////////////////////////////////////////////////
+#ifdef ARDUINO_ARCH_ESP32
+
+#if __has_include("esp_idf_version.h")
+#include "esp_idf_version.h"
+#endif
+#if ESP_IDF_VERSION_MAJOR == 4
+// all well correct IDF version
+#else
+#error "DCC-EX does not support compiling with IDF version 5.0 or later. Downgrade your ESP32 library to a version that contains IDF version 4. Arduino ESP32 library 3.0.0 is too new. Downgrade to one of 2.0.9 to 2.0.17"
+#endif
+
+// protect all the rest of the code from IDF version 5
+#if ESP_IDF_VERSION_MAJOR == 4
+#include "DIAG.h"
+#include <driver/adc.h>
+#include <soc/sens_reg.h>
+#include <soc/sens_struct.h>
+#undef ADC_INPUT_MAX_VALUE
+#define ADC_INPUT_MAX_VALUE 4095 // 12 bit ADC
+#define pinToADC1Channel(X) (adc1_channel_t)(((X) > 35) ? (X)-36 : (X)-28)
+
+int IRAM_ATTR local_adc1_get_raw(int channel) {
+  uint16_t adc_value;
+  SENS.sar_meas_start1.sar1_en_pad = (1 << channel); // only one channel is selected
+  while (SENS.sar_slave_addr1.meas_status != 0);
+  SENS.sar_meas_start1.meas1_start_sar = 0;
+  SENS.sar_meas_start1.meas1_start_sar = 1;
+  while (SENS.sar_meas_start1.meas1_done_sar == 0);
+  adc_value = SENS.sar_meas_start1.meas1_data_sar;
+  return adc_value;
+}
+
+#include "DCCTimer.h"
+INTERRUPT_CALLBACK interruptHandler=0;
+
+// https://www.visualmicro.com/page/Timer-Interrupts-Explained.aspx
+
+portMUX_TYPE timerMux = portMUX_INITIALIZER_UNLOCKED;
+
+void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
+  // This should not be called on ESP32 so disable it
+  return;
+  interruptHandler = callback;
+  hw_timer_t *timer = NULL;
+  timer = timerBegin(0, 2, true); // prescaler can be 2 to 65536 so choose 2
+  timerAttachInterrupt(timer, interruptHandler, true);
+  timerAlarmWrite(timer, CLOCK_CYCLES / 6, true); // divide by prescaler*3 (Clockbase is 80Mhz and not F_CPU 240Mhz)
+  timerAlarmEnable(timer);
+}
+
+// We do not support to use PWM to make the Waveform on ESP
+bool IRAM_ATTR DCCTimer::isPWMPin(byte pin) {
+  return false;
+}
+void IRAM_ATTR DCCTimer::setPWM(byte pin, bool high) {
+}
+void IRAM_ATTR DCCTimer::clearPWM() {
+}
+
+// Fake this as it should not be used
+void   DCCTimer::getSimulatedMacAddress(byte mac[6]) {
+  mac[0] = 0xFE;
+  mac[1] = 0xBE;
+  mac[2] = 0xEF;
+  mac[3] = 0xC0;
+  mac[4] = 0xFF;
+  mac[5] = 0xEE;
+}
+
+volatile int DCCTimer::minimum_free_memory=__INT_MAX__;
+
+// Return low memory value... 
+int DCCTimer::getMinimumFreeMemory() {
+  noInterrupts(); // Disable interrupts to get volatile value 
+  int retval = minimum_free_memory;
+  interrupts();
+  return retval;
+}
+
+int DCCTimer::freeMemory() {
+  return ESP.getFreeHeap();
+}
+
+void DCCTimer::reset() {
+   ESP.restart();
+}
+
+void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) {
+  if (f >= 16)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, f);
+/*
+  else if (f == 7) // not used on ESP32
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 62500);
+*/
+  else if (f >= 4)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 32000);
+  else if (f >= 3)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 16000);
+  else if (f >= 2)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 3400);
+  else if (f == 1)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 480);
+  else
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 131);
+}
+
+#include "esp32-hal.h"
+#include "soc/soc_caps.h"
+
+#ifdef SOC_LEDC_SUPPORT_HS_MODE
+#define LEDC_CHANNELS           (SOC_LEDC_CHANNEL_NUM<<1)
+#else
+#define LEDC_CHANNELS           (SOC_LEDC_CHANNEL_NUM)
+#endif
+
+static int8_t pin_to_channel[SOC_GPIO_PIN_COUNT] = { 0 };
+static int cnt_channel = LEDC_CHANNELS;
+
+void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t frequency) {
+  if (pin < SOC_GPIO_PIN_COUNT) {
+    if (pin_to_channel[pin] != 0) {
+      ledcSetup(pin_to_channel[pin], frequency, 8);
+    }
+  }
+}
+
+void DCCTimer::DCCEXledcDetachPin(uint8_t pin) {
+#ifdef DIAG_IO
+  DIAG(F("Clear pin %d from ledc channel"), pin);
+#endif
+  pin_to_channel[pin] = 0;
+  pinMatrixOutDetach(pin, false, false);
+}
+
+static byte LEDCToMux[] = {
+  LEDC_HS_SIG_OUT0_IDX,
+  LEDC_HS_SIG_OUT1_IDX,
+  LEDC_HS_SIG_OUT2_IDX,
+  LEDC_HS_SIG_OUT3_IDX,
+  LEDC_HS_SIG_OUT4_IDX,
+  LEDC_HS_SIG_OUT5_IDX,
+  LEDC_HS_SIG_OUT6_IDX,
+  LEDC_HS_SIG_OUT7_IDX,
+  LEDC_LS_SIG_OUT0_IDX,
+  LEDC_LS_SIG_OUT1_IDX,
+  LEDC_LS_SIG_OUT2_IDX,
+  LEDC_LS_SIG_OUT3_IDX,
+  LEDC_LS_SIG_OUT4_IDX,
+  LEDC_LS_SIG_OUT5_IDX,
+  LEDC_LS_SIG_OUT6_IDX,
+  LEDC_LS_SIG_OUT7_IDX,
+};
+
+void DCCTimer::DCCEXledcAttachPin(uint8_t pin, int8_t channel, bool inverted) {
+  DIAG(F("Attaching pin %d to channel %d %c"), pin, channel, inverted ? 'I' : ' ');
+  ledcAttachPin(pin, channel);
+  if (inverted) // we attach again but with inversion
+    gpio_matrix_out(pin, LEDCToMux[channel], inverted, 0);
+}
+
+void DCCTimer::DCCEXanalogCopyChannel(int8_t frompin, int8_t topin) {
+  // arguments are signed depending on inversion of pins
+  DIAG(F("Pin %d copied to %d"), frompin, topin);
+  bool inverted = false;
+  if (frompin<0)
+    frompin = -frompin;
+  if (topin<0) {
+    inverted = true;
+    topin = -topin;
+  }
+  int channel = pin_to_channel[frompin]; // after abs(frompin)
+  pin_to_channel[topin] = channel;
+  DCCTimer::DCCEXledcAttachPin(topin, channel, inverted);
+}
+
+void DCCTimer::DCCEXanalogWrite(uint8_t pin, int value, bool invert) {
+  // This allocates channels 15, 13, 11, ....
+  // so each channel gets its own timer.
+  if (pin < SOC_GPIO_PIN_COUNT) {
+    if (pin_to_channel[pin] == 0) {
+      int search_channel;
+      int n;
+      if (!cnt_channel) {
+          log_e("No more PWM channels available! All %u already used", LEDC_CHANNELS);
+          return;
+      }
+      // search for free channels top down
+      for (search_channel=LEDC_CHANNELS-1; search_channel >=cnt_channel; search_channel -= 2) {
+	bool chanused = false;
+	for (n=0; n < SOC_GPIO_PIN_COUNT; n++) {
+	  if (pin_to_channel[n] == search_channel) { // current search_channel used
+	    chanused = true;
+	    break;
+	  }
+	}
+	if (chanused)
+	  continue;
+	if (n == SOC_GPIO_PIN_COUNT) // current search_channel unused
+	  break;
+      }
+      if (search_channel >= cnt_channel) {
+	pin_to_channel[pin] = search_channel;
+	DIAG(F("Pin %d assigned to search channel %d"), pin, search_channel);
+      } else {
+	pin_to_channel[pin] = --cnt_channel; // This sets 15, 13, ...
+	DIAG(F("Pin %d assigned to new channel %d"), pin, cnt_channel);
+	--cnt_channel;                       // Now we are at 14, 12, ...
+      }
+      ledcSetup(pin_to_channel[pin], 1000, 8);
+      DCCEXledcAttachPin(pin, pin_to_channel[pin], invert);
+    } else {
+      // This else is only here so we can enable diag
+      // Pin should be already attached to channel
+      // DIAG(F("Pin %d assigned to old channel %d"), pin, pin_to_channel[pin]);
+    }
+    ledcWrite(pin_to_channel[pin], value);
+  }
+}
+
+void DCCTimer::DCCEXInrushControlOn(uint8_t pin, int duty, bool inverted) {
+  // this uses hardcoded channel 0
+  ledcSetup(0, 62500, 8);
+  DCCEXledcAttachPin(pin, 0, inverted);
+  ledcWrite(0, duty);
+}
+
+int ADCee::init(uint8_t pin) {
+  pinMode(pin, ANALOG);
+  adc1_config_width(ADC_WIDTH_BIT_12);
+// Espressif deprecated ADC_ATTEN_DB_11 somewhere between 2.0.9 and 2.0.17
+#ifdef ADC_ATTEN_11db
+  adc1_config_channel_atten(pinToADC1Channel(pin),ADC_ATTEN_11db);
+#else
+  adc1_config_channel_atten(pinToADC1Channel(pin),ADC_ATTEN_DB_11);
+#endif
+  return adc1_get_raw(pinToADC1Channel(pin));
+}
+int16_t ADCee::ADCmax() {
+  return 4095;
+}
+/*
+ * Read function ADCee::read(pin) to get value instead of analogRead(pin)
+ */
+int ADCee::read(uint8_t pin, bool fromISR) {
+  return local_adc1_get_raw(pinToADC1Channel(pin));
+}
+/*
+ * Scan function that is called from interrupt
+ */
+void ADCee::scan() {
+}
+
+void ADCee::begin() {
+}
+#endif //IDF v4
+#endif //ESP32

DCCTimerMEGAAVR.cpp

@@ -0,0 +1,169 @@
+/*
+ *  © 2022 Paul M. Antoine
+ *  © 2021 Mike S
+ *  © 2021 Harald Barth
+ *  © 2021 Fred Decker
+ *  © 2021 Chris Harlow
+ *  © 2021 David Cutting
+ *  All rights reserved.
+ *  
+ *  This file is part of Asbelos DCC API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+/* This timer class is used to manage the single timer required to handle the DCC waveform.
+ *  All timer access comes through this class so that it can be compiled for 
+ *  various hardware CPU types. 
+ *  
+ *  DCCEX works on a single timer interrupt at a regular 58uS interval.
+ *  The DCCWaveform class generates the signals to the motor shield  
+ *  based on this timer. 
+ *  
+ *  If the motor drivers are BOTH configured to use the correct 2 pins for the architecture,
+ *  (see isPWMPin() function. )
+ *  then this allows us to use a hardware driven pin switching arrangement which is
+ *  achieved by setting the duty cycle of the NEXT clock interrupt to 0% or 100% depending on 
+ *  the required pin state. (see setPWM())  
+ *  This is more accurate than the software interrupt but at the expense of 
+ *  limiting the choice of available pins. 
+ *  Fortunately, a standard motor shield on a Mega uses pins that qualify for PWM... 
+ *  Other shields may be jumpered to PWM pins or run directly using the software interrupt.
+ *  
+ *  Because the PWM-based waveform is effectively set half a cycle after the software version,
+ *  it is not acceptable to drive the two tracks on different methiods or it would cause
+ *  problems for <1 JOIN> etc.
+ *  
+ */
+
+// ATTENTION: this file only compiles on a UnoWifiRev3 or NanoEvery
+// Please refer to DCCTimer.h for general comments about how this class works
+// This is to avoid repetition and duplication.
+#ifdef ARDUINO_ARCH_MEGAAVR
+
+#include "DCCTimer.h"
+
+INTERRUPT_CALLBACK interruptHandler=0;
+extern char *__brkval;
+extern char *__malloc_heap_start;
+
+  
+  void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
+    interruptHandler=callback;
+    noInterrupts(); 
+    ADC0.CTRLC = (ADC0.CTRLC & 0b00110000) | 0b01000011;  // speed up analogRead sample time   
+    TCB0.CTRLB = TCB_CNTMODE_INT_gc & ~TCB_CCMPEN_bm; // timer compare mode with output disabled
+    TCB0.CTRLA = TCB_CLKSEL_CLKDIV2_gc; //   8 MHz ~ 0.125 us      
+    TCB0.CCMP =  CLOCK_CYCLES -1;  // 1 tick less for timer reset
+    TCB0.INTFLAGS = TCB_CAPT_bm; // clear interrupt request flag
+    TCB0.INTCTRL = TCB_CAPT_bm;  // Enable the interrupt
+    TCB0.CNT = 0;
+    TCB0.CTRLA |= TCB_ENABLE_bm;  // start
+    interrupts();
+  }
+
+  // ISR called by timer interrupt every 58uS
+  ISR(TCB0_INT_vect){
+    TCB0.INTFLAGS = TCB_CAPT_bm; // Clear interrupt request flag
+    interruptHandler();
+  }
+
+void DCCTimer::startRailcomTimer(byte brakePin) {
+  // TODO: for intended operation see DCCTimerAVR.cpp
+  (void) brakePin; 
+}
+
+void DCCTimer::ackRailcomTimer() {
+  // TODO: for intended operation see DCCTimerAVR.cpp
+}
+
+  bool DCCTimer::isPWMPin(byte pin) {
+       (void) pin; 
+       return false;  // TODO what are the relevant pins? 
+  }
+
+ void DCCTimer::setPWM(byte pin, bool high) {
+    (void) pin;
+    (void) high;
+    // TODO what are the relevant pins?
+ }
+
+void DCCTimer::clearPWM() {
+    // Do nothing unless we implent HA
+}
+
+  void   DCCTimer::getSimulatedMacAddress(byte mac[6]) {
+    memcpy(mac,(void *) &SIGROW.SERNUM0,6);  // serial number
+    mac[0] &= 0xFE;
+    mac[0] |= 0x02;
+  }
+
+volatile int DCCTimer::minimum_free_memory=__INT_MAX__;
+
+// Return low memory value... 
+int DCCTimer::getMinimumFreeMemory() {
+  noInterrupts(); // Disable interrupts to get volatile value 
+  int retval = minimum_free_memory;
+  interrupts();
+  return retval;
+}
+
+extern char *__brkval;
+extern char *__malloc_heap_start;
+
+int DCCTimer::freeMemory() {
+  char top;
+  return __brkval ? &top - __brkval : &top - __malloc_heap_start;
+}
+
+void DCCTimer::reset() {
+  CPU_CCP=0xD8;
+  WDT.CTRLA=0x4;
+  while(true){}
+}
+
+void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) {
+}
+void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t fbits) {
+}
+
+int16_t ADCee::ADCmax() {
+  return 4095;
+}
+
+int ADCee::init(uint8_t pin) {
+  return analogRead(pin);
+}
+/*
+ * Read function ADCee::read(pin) to get value instead of analogRead(pin)
+ */
+int ADCee::read(uint8_t pin, bool fromISR) {
+  int current;
+  if (!fromISR) noInterrupts();
+  current = analogRead(pin);
+  if (!fromISR) interrupts();
+  return current;
+}
+/*
+ * Scan function that is called from interrupt
+ */
+void ADCee::scan() {
+}
+
+void ADCee::begin() {
+  noInterrupts();
+  interrupts();
+}
+#endif

DCCTimerSAMD.cpp

@@ -0,0 +1,291 @@
+/*
+ *  © 2022 Paul M. Antoine
+ *  © 2021 Mike S
+ *  © 2021-2022 Harald Barth
+ *  © 2021 Fred Decker
+ *  © 2021 Chris Harlow
+ *  © 2021 David Cutting
+ *  All rights reserved.
+ *  
+ *  This file is part of Asbelos DCC API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// ATTENTION: this file only compiles on a SAMD21 based board
+// Please refer to DCCTimer.h for general comments about how this class works
+// This is to avoid repetition and duplication.
+#ifdef ARDUINO_ARCH_SAMD
+
+#include "DCCTimer.h"
+#include <wiring_private.h>
+
+INTERRUPT_CALLBACK interruptHandler=0;
+
+void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
+  interruptHandler=callback;
+  noInterrupts();
+  // Timer setup - setup clock sources first
+  REG_GCLK_GENDIV =   GCLK_GENDIV_DIV(1) |            // Divide 48MHz by 1
+                      GCLK_GENDIV_ID(4);              // Apply to GCLK4
+  while (GCLK->STATUS.bit.SYNCBUSY);                  // Wait for synchronization
+                
+  REG_GCLK_GENCTRL =  GCLK_GENCTRL_GENEN |            // Enable GCLK
+                      GCLK_GENCTRL_SRC_DFLL48M |      // Set the 48MHz clock source
+                      GCLK_GENCTRL_ID(4);             // Select GCLK4
+  while (GCLK->STATUS.bit.SYNCBUSY);                  // Wait for synchronization
+            
+  REG_GCLK_CLKCTRL =  GCLK_CLKCTRL_CLKEN |            // Enable generic clock
+                      4 << GCLK_CLKCTRL_GEN_Pos |     // Apply to GCLK4
+                      GCLK_CLKCTRL_ID_TCC0_TCC1;      // Feed GCLK to TCC0/1
+  while (GCLK->STATUS.bit.SYNCBUSY);
+
+  // Assume we're using TCC0... as we're bit-bashing the DCC waveform output pins anyway
+  // for "normal accuracy" DCC waveform generation. For high accuracy we're going to need
+  // to a good deal more. The TCC waveform output pins are mux'd on the SAMD, and output
+  // pins for each TCC are only available on certain pins
+  TCC0->WAVE.reg = TCC_WAVE_WAVEGEN_NPWM;     // Select NPWM as waveform
+  while (TCC0->SYNCBUSY.bit.WAVE);            // Wait for sync
+
+  // Set the frequency
+  TCC0->CTRLA.reg |= TCC_CTRLA_PRESCALER(TCC_CTRLA_PRESCALER_DIV1_Val);
+  TCC0->PER.reg = CLOCK_CYCLES * 2;
+  while (TCC0->SYNCBUSY.bit.PER);
+
+  // Start the timer
+  TCC0->CTRLA.bit.ENABLE = 1;
+  while (TCC0->SYNCBUSY.bit.ENABLE);
+
+  // Set the interrupt condition, priority and enable it in the NVIC
+  TCC0->INTENSET.reg = TCC_INTENSET_OVF;      // Only interrupt on overflow
+  int USBprio = NVIC_GetPriority((IRQn_Type) USB_IRQn);  // Fetch the USB priority
+  NVIC_SetPriority((IRQn_Type)TCC0_IRQn, USBprio);  // Match the USB priority
+//  NVIC_SetPriority((IRQn_Type)TCC0_IRQn, 0);  // Make this highest priority
+  NVIC_EnableIRQ((IRQn_Type)TCC0_IRQn);       // Enable the interrupt
+  interrupts();
+}
+
+void DCCTimer::startRailcomTimer(byte brakePin) {
+  // TODO: for intended operation see DCCTimerAVR.cpp
+  (void) brakePin; 
+}
+
+void DCCTimer::ackRailcomTimer() {
+  // TODO: for intended operation see DCCTimerAVR.cpp
+}
+
+// Timer IRQ handlers replace the dummy handlers (in cortex_handlers)
+// copied from rf24 branch
+void TCC0_Handler() {
+    if(TCC0->INTFLAG.bit.OVF) {
+        TCC0->INTFLAG.bit.OVF = 1; // writing a 1 clears the flag
+        interruptHandler();
+    }
+}
+
+void TCC1_Handler() {
+    if(TCC1->INTFLAG.bit.OVF) {
+        TCC1->INTFLAG.bit.OVF = 1; // writing a 1 clears the flag
+        interruptHandler();
+    }
+}
+
+void TCC2_Handler() {
+    if(TCC2->INTFLAG.bit.OVF) {
+        TCC2->INTFLAG.bit.OVF = 1; // writing a 1 clears the flag
+        interruptHandler();
+    }
+}
+
+
+bool DCCTimer::isPWMPin(byte pin) {
+  //TODO: SAMD whilst this call to digitalPinHasPWM will reveal which pins can do PWM,
+  //      there's no support yet for High Accuracy, so for now return false
+  //  return digitalPinHasPWM(pin);
+  return false;
+}
+
+void DCCTimer::setPWM(byte pin, bool high) {
+    // TODO: High Accuracy mode is not supported as yet, and may never need to be
+    (void) pin;
+    (void) high;
+}
+
+void DCCTimer::clearPWM() {
+  return;
+}
+
+void   DCCTimer::getSimulatedMacAddress(byte mac[6]) {
+  volatile uint32_t *serno1 = (volatile uint32_t *)0x0080A00C;
+  volatile uint32_t *serno2 = (volatile uint32_t *)0x0080A040;
+//  volatile uint32_t *serno3 = (volatile uint32_t *)0x0080A044;
+//  volatile uint32_t *serno4 = (volatile uint32_t *)0x0080A048;
+
+  volatile uint32_t m1 = *serno1;
+  volatile uint32_t m2 = *serno2;
+  mac[0] = m1 >> 8;
+  mac[1] = m1 >> 0;
+  mac[2] = m2 >> 24;
+  mac[3] = m2 >> 16;
+  mac[4] = m2 >> 8;
+  mac[5] = m2 >> 0;
+}
+
+volatile int DCCTimer::minimum_free_memory=__INT_MAX__;
+
+// Return low memory value... 
+int DCCTimer::getMinimumFreeMemory() {
+  noInterrupts(); // Disable interrupts to get volatile value 
+  int retval = freeMemory();
+  interrupts();
+  return retval;
+}
+
+extern "C" char* sbrk(int incr);
+
+int DCCTimer::freeMemory() {
+  char top;
+  return (int)(&top - reinterpret_cast<char *>(sbrk(0)));
+}
+
+void DCCTimer::reset() {
+   __disable_irq();
+    NVIC_SystemReset();
+    while(true) {};
+}
+
+void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) {
+}
+void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t fbits) {
+}
+
+#define NUM_ADC_INPUTS NUM_ANALOG_INPUTS
+
+uint16_t ADCee::usedpins = 0;
+int * ADCee::analogvals = NULL;
+
+int ADCee::init(uint8_t pin) {
+  uint8_t id = pin - A0;
+  int value = 0;
+
+  if (id > NUM_ADC_INPUTS)
+    return -1023;
+
+  // Permanently configure SAMD IO MUX for that pin
+  pinPeripheral(pin, PIO_ANALOG);
+  ADC->INPUTCTRL.bit.MUXPOS = g_APinDescription[pin].ulADCChannelNumber; // Selection for the positive ADC input
+
+  // Start conversion
+  ADC->SWTRIG.bit.START = 1;
+
+  // Wait for the conversion to be ready
+  while (ADC->INTFLAG.bit.RESRDY == 0);   // Waiting for conversion to complete
+
+  // Read the value
+  value = ADC->RESULT.reg;
+
+  if (analogvals == NULL)
+    analogvals = (int *)calloc(NUM_ADC_INPUTS+1, sizeof(int));
+  analogvals[id] = value;
+  usedpins |= (1<<id);
+
+  return value;
+}
+
+int16_t ADCee::ADCmax() {
+  return 4095;
+}
+
+/*
+ * Read function ADCee::read(pin) to get value instead of analogRead(pin)
+ */
+int ADCee::read(uint8_t pin, bool fromISR) {
+  uint8_t id = pin - A0;
+  if ((usedpins & (1<<id) ) == 0)
+    return -1023;
+  // we do not need to check (analogvals == NULL)
+  // because usedpins would still be 0 in that case
+  return analogvals[id];
+}
+/*
+ * Scan function that is called from interrupt
+ */
+#pragma GCC push_options
+#pragma GCC optimize ("-O3")
+void ADCee::scan() {
+  static uint8_t id = 0;        // id and mask are the same thing but it is faster to 
+  static uint16_t mask = 1;  // increment and shift instead to calculate mask from id
+  static bool waiting = false;
+
+  if (waiting) {
+    // look if we have a result
+    if (ADC->INTFLAG.bit.RESRDY == 0)
+      return; // no result, continue to wait
+    // found value
+    analogvals[id] = ADC->RESULT.reg;
+    // advance at least one track
+    // for scope debug TrackManager::track[1]->setBrake(0);
+    waiting = false;
+    id++;
+    mask = mask << 1;
+    if (id == NUM_ADC_INPUTS+1) {
+      id = 0;
+      mask = 1;
+    }
+  }
+  if (!waiting) {
+    if (usedpins == 0) // otherwise we would loop forever
+      return;
+    // look for a valid track to sample or until we are around
+    while (true) {
+      if (mask  & usedpins) {
+    	  // start new ADC aquire on id
+        ADC->INPUTCTRL.bit.MUXPOS = g_APinDescription[id + A0].ulADCChannelNumber; // Selection for the positive ADC input
+          // Start conversion
+        ADC->SWTRIG.bit.START = 1;
+	      // for scope debug TrackManager::track[1]->setBrake(1);
+	      waiting = true;
+	      return;
+      }
+      id++;
+      mask = mask << 1;
+      if (id == NUM_ADC_INPUTS+1) {
+	      id = 0;
+	      mask = 1;
+      }
+    }
+  }
+}
+#pragma GCC pop_options
+
+void ADCee::begin() {
+  noInterrupts();
+  // Set up ADC to do faster reads... default for Arduino Zero platform configs is 436uS,
+  // and we need sub-58uS. This code sets it to a read speed of around 5-6uS, and enables
+  // 12-bit mode
+  // Reconfigure ADC
+  ADC->CTRLA.bit.ENABLE = 0;                      // disable ADC
+  while( ADC->STATUS.bit.SYNCBUSY == 1 );         // wait for synchronization
+
+  ADC->CTRLB.reg &= 0b1111100011001111;           // mask PRESCALER and RESSEL bits
+  ADC->CTRLB.reg |= ADC_CTRLB_PRESCALER_DIV64 |   // divide Clock by 16
+                    ADC_CTRLB_RESSEL_12BIT;       // Result 12 bits, 10 bits possible
+  ADC->AVGCTRL.reg = ADC_AVGCTRL_SAMPLENUM_1 |    // take 1 sample at a time
+                     ADC_AVGCTRL_ADJRES(0x00ul);  // adjusting result by 0
+  ADC->SAMPCTRL.reg = 0x00ul;                     // sampling Time Length = 0
+  ADC->CTRLA.bit.ENABLE = 1;                      // enable ADC
+  while( ADC->STATUS.bit.SYNCBUSY == 1 );         // wait for synchronization
+  interrupts();
+}
+#endif

DCCTimerSTM32.cpp

@@ -0,0 +1,662 @@
+/*
+ *  © 2023 Neil McKechnie
+ *  © 2022-2024 Paul M. Antoine
+ *  © 2021 Mike S
+ *  © 2021, 2023 Harald Barth
+ *  © 2021 Fred Decker
+ *  © 2021 Chris Harlow
+ *  © 2021 David Cutting
+ *  All rights reserved.
+ *  
+ *  This file is part of Asbelos DCC API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// ATTENTION: this file only compiles on a STM32 based boards
+// Please refer to DCCTimer.h for general comments about how this class works
+// This is to avoid repetition and duplication.
+#ifdef ARDUINO_ARCH_STM32
+
+#include "DCCTimer.h"
+#ifdef DEBUG_ADC
+#include "TrackManager.h"
+#endif
+#include "DIAG.h"
+#include <wiring_private.h>
+
+#if defined(ARDUINO_NUCLEO_F401RE)
+// Nucleo-64 boards don't have additional serial ports defined by default
+// Serial1 is available on the F401RE, but not hugely convenient.
+// Rx pin on PB7 is useful, but all the Tx pins map to Arduino digital pins, specifically:
+//   PA9 == D8
+//   PB6 == D10
+// of which D8 is needed by the standard and EX8874 motor shields. D10 would be used if a second
+// EX8874 is stacked. So only disable this if using a second motor shield.
+HardwareSerial Serial1(PB7, PB6);  // Rx=PB7, Tx=PB6 -- CN7 pin 17 and CN10 pin 17
+// Serial2 is defined to use USART2 by default, but is in fact used as the diag console
+// via the debugger on the Nucleo-64. It is therefore unavailable for other DCC-EX uses like WiFi, DFPlayer, etc.
+// Let's define Serial6 as an additional serial port (the only other option for the F401RE)
+HardwareSerial Serial6(PA12, PA11);  // Rx=PA12, Tx=PA11 -- CN10 pins 12 and 14 - F401RE
+#elif defined(ARDUINO_NUCLEO_F411RE)
+// Nucleo-64 boards don't have additional serial ports defined by default
+HardwareSerial Serial1(PB7, PA15);  // Rx=PB7, Tx=PA15 -- CN7 pins 17 and 21 - F411RE
+// Serial2 is defined to use USART2 by default, but is in fact used as the diag console
+// via the debugger on the Nucleo-64. It is therefore unavailable for other DCC-EX uses like WiFi, DFPlayer, etc.
+// Let's define Serial6 as an additional serial port (the only other option for the Nucleo-64s)
+HardwareSerial Serial6(PA12, PA11);  // Rx=PA12, Tx=PA11 -- CN10 pins 12 and 14 - F411RE
+#elif defined(ARDUINO_NUCLEO_F446RE)
+// Nucleo-64 boards don't have additional serial ports defined by default
+// On the F446RE, Serial1 isn't really useable as it's Rx/Tx pair sit on already used D2/D10 pins
+// HardwareSerial Serial1(PA10, PB6);  // Rx=PA10 (D2), Tx=PB6 (D10) -- CN10 pins 17 and 9 - F446RE 
+// Serial2 is defined to use USART2 by default, but is in fact used as the diag console
+// via the debugger on the Nucleo-64. It is therefore unavailable for other DCC-EX uses like WiFi, DFPlayer, etc.
+// On the F446RE, Serial3 and Serial5 are easy to use:
+HardwareSerial Serial3(PC11, PC10);  // Rx=PC11, Tx=PC10 -- USART3 - F446RE
+HardwareSerial Serial5(PD2, PC12);  // Rx=PD2, Tx=PC12 -- UART5 - F446RE
+// On the F446RE, Serial4 and Serial6 also use pins we can't readily map while using the Arduino pins
+#elif defined(ARDUINO_NUCLEO_F412ZG) || defined(ARDUINO_NUCLEO_F413ZH) || defined(ARDUINO_NUCLEO_F446ZE) || \
+      defined(ARDUINO_NUCLEO_F429ZI) || defined(ARDUINO_NUCLEO_F439ZI) || defined(ARDUINO_NUCLEO_F4X9ZI)
+// Nucleo-144 boards don't have Serial1 defined by default
+HardwareSerial Serial6(PG9, PG14);  // Rx=PG9, Tx=PG14 -- USART6
+HardwareSerial Serial2(PD6, PD5);  // Rx=PD6, Tx=PD5 -- UART2
+#if !defined(ARDUINO_NUCLEO_F412ZG)  // F412ZG does not have UART5
+  HardwareSerial Serial5(PD2, PC12);  // Rx=PD2, Tx=PC12 -- UART5
+#endif  
+// Serial3 is defined to use USART3 by default, but is in fact used as the diag console
+// via the debugger on the Nucleo-144. It is therefore unavailable for other DCC-EX uses like WiFi, DFPlayer, etc.
+#else
+#error STM32 board selected is not yet explicitly supported - so Serial1 peripheral is not defined
+#endif
+
+///////////////////////////////////////////////////////////////////////////////////////////////
+// Experimental code for High Accuracy (HA) DCC Signal mode
+// Warning - use of TIM2 and TIM3 can affect the use of analogWrite() function on certain pins,
+// which is used by the DC motor types.
+///////////////////////////////////////////////////////////////////////////////////////////////
+
+// INTERRUPT_CALLBACK interruptHandler=0;
+// // Let's use STM32's timer #2 which supports hardware pulse generation on pin D13.
+// // Also, timer #3 will do hardware pulses on pin D12. This gives
+// // accurate timing, independent of the latency of interrupt handling.
+// // We only need to interrupt on one of these (TIM2), the other will just generate
+// // pulses.
+// HardwareTimer timer(TIM2);
+// HardwareTimer timerAux(TIM3);
+// static bool tim2ModeHA = false;
+// static bool tim3ModeHA = false;
+
+// // Timer IRQ handler
+// void Timer_Handler() {
+//   interruptHandler();
+// }
+
+// void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
+//   interruptHandler=callback;
+//   noInterrupts();
+
+//   // adc_set_sample_rate(ADC_SAMPLETIME_480CYCLES);
+//   timer.pause();
+//   timerAux.pause();
+//   timer.setPrescaleFactor(1);
+//   timer.setOverflow(DCC_SIGNAL_TIME, MICROSEC_FORMAT);
+//   timer.attachInterrupt(Timer_Handler);
+//   timer.refresh();
+//   timerAux.setPrescaleFactor(1);
+//   timerAux.setOverflow(DCC_SIGNAL_TIME, MICROSEC_FORMAT);
+//   timerAux.refresh();
+  
+//   timer.resume();
+//   timerAux.resume();
+
+//   interrupts();
+// }
+
+// bool DCCTimer::isPWMPin(byte pin) {
+//   // Timer 2 Channel 1 controls pin D13, and Timer3 Channel 1 controls D12.
+//   //  Enable the appropriate timer channel.
+//   switch (pin) {
+//     case 12:
+//       return true;
+//     case 13:
+//       return true;
+//     default:
+//       return false;
+//   }
+// }
+
+// void DCCTimer::setPWM(byte pin, bool high) {
+//   // Set the timer so that, at the next counter overflow, the requested
+//   // pin state is activated automatically before the interrupt code runs.
+//   // TIM2 is timer, TIM3 is timerAux.
+//   switch (pin) {
+//     case 12:
+//       if (!tim3ModeHA) {
+//         timerAux.setMode(1, TIMER_OUTPUT_COMPARE_INACTIVE, D12);
+//         tim3ModeHA = true;
+//       }
+//       if (high) 
+//         TIM3->CCMR1 = (TIM3->CCMR1 & ~TIM_CCMR1_OC1M_Msk) | TIM_CCMR1_OC1M_0;
+//       else
+//         TIM3->CCMR1 = (TIM3->CCMR1 & ~TIM_CCMR1_OC1M_Msk) | TIM_CCMR1_OC1M_1;
+//       break;
+//     case 13:
+//       if (!tim2ModeHA) {
+//         timer.setMode(1, TIMER_OUTPUT_COMPARE_INACTIVE, D13);
+//         tim2ModeHA = true;
+//       }
+//       if (high) 
+//         TIM2->CCMR1 = (TIM2->CCMR1 & ~TIM_CCMR1_OC1M_Msk) | TIM_CCMR1_OC1M_0;
+//       else
+//         TIM2->CCMR1 = (TIM2->CCMR1 & ~TIM_CCMR1_OC1M_Msk) | TIM_CCMR1_OC1M_1;
+//       break;
+//   }   
+// }
+
+// void DCCTimer::clearPWM() {
+//   timer.setMode(1, TIMER_OUTPUT_COMPARE_INACTIVE, NC);
+//   tim2ModeHA = false;
+//   timerAux.setMode(1, TIMER_OUTPUT_COMPARE_INACTIVE, NC);  
+//   tim3ModeHA = false;
+// }
+///////////////////////////////////////////////////////////////////////////////////////////////
+
+INTERRUPT_CALLBACK interruptHandler=0;
+
+// On STM32F4xx models that have them, Timers 6 and 7 have no PWM output capability,
+// so are good choices for general timer duties - they are used for tone and servo
+// in stm32duino so we shall usurp those as DCC-EX doesn't use tone or servo libs.
+// NB: the F401, F410 and F411 do **not** have Timer 6 or 7, so we use Timer 11
+#ifndef DCC_EX_TIMER
+#if defined(TIM6)
+#define DCC_EX_TIMER TIM6
+#elif defined(TIM7)
+#define DCC_EX_TIMER TIM7
+#elif defined(TIM11)
+#define DCC_EX_TIMER TIM11
+#else
+#warning This STM32F4XX variant does not have Timers 6,7 or 11!!
+#endif
+#endif // ifndef DCC_EX_TIMER
+
+HardwareTimer dcctimer(DCC_EX_TIMER);
+void DCCTimer_Handler() __attribute__((interrupt));
+
+// Timer IRQ handler
+void DCCTimer_Handler() {
+  interruptHandler();
+}
+
+void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
+  interruptHandler=callback;
+  noInterrupts();
+
+  dcctimer.pause();
+  dcctimer.setPrescaleFactor(1);
+//  timer.setOverflow(CLOCK_CYCLES * 2);
+  dcctimer.setOverflow(DCC_SIGNAL_TIME, MICROSEC_FORMAT);
+  // dcctimer.attachInterrupt(Timer11_Handler);
+  dcctimer.attachInterrupt(DCCTimer_Handler);
+  dcctimer.setInterruptPriority(0, 0); // Set highest preemptive priority!
+  dcctimer.refresh();
+  dcctimer.resume();
+
+  interrupts();
+}
+
+void DCCTimer::startRailcomTimer(byte brakePin) {
+  // TODO: for intended operation see DCCTimerAVR.cpp
+  (void) brakePin; 
+}
+
+void DCCTimer::ackRailcomTimer() {
+  // TODO: for intended operation see DCCTimerAVR.cpp
+}
+
+bool DCCTimer::isPWMPin(byte pin) {
+  //TODO: STM32 whilst this call to digitalPinHasPWM will reveal which pins can do PWM,
+  //      there's no support yet for High Accuracy, so for now return false
+  //  return digitalPinHasPWM(pin);
+  (void) pin;
+  return false;
+}
+
+void DCCTimer::setPWM(byte pin, bool high) {
+    // TODO: High Accuracy mode is not supported as yet, and may never need to be
+    (void) pin;
+    (void) high;
+}
+
+void DCCTimer::clearPWM() {
+  return;
+}
+
+void   DCCTimer::getSimulatedMacAddress(byte mac[6]) {
+  volatile uint32_t *serno1 = (volatile uint32_t *)UID_BASE;
+  volatile uint32_t *serno2 = (volatile uint32_t *)UID_BASE+4;
+  // volatile uint32_t *serno3 = (volatile uint32_t *)UID_BASE+8;
+
+  volatile uint32_t m1 = *serno1;
+  volatile uint32_t m2 = *serno2;
+  mac[0] = m1 >> 8;
+  mac[1] = m1 >> 0;
+  mac[2] = m2 >> 24;
+  mac[3] = m2 >> 16;
+  mac[4] = m2 >> 8;
+  mac[5] = m2 >> 0;
+}
+
+volatile int DCCTimer::minimum_free_memory=__INT_MAX__;
+
+// Return low memory value... 
+int DCCTimer::getMinimumFreeMemory() {
+  noInterrupts(); // Disable interrupts to get volatile value 
+  int retval = freeMemory();
+  interrupts();
+  return retval;
+}
+
+extern "C" char* sbrk(int incr);
+
+int DCCTimer::freeMemory() {
+  char top;
+  return (int)(&top - reinterpret_cast<char *>(sbrk(0)));
+}
+
+void DCCTimer::reset() {
+   __disable_irq();
+    NVIC_SystemReset();
+    while(true) {};
+}
+
+void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) {
+  if (f >= 16)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, f);
+  else if (f == 7)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 62500);
+  else if (f >= 4)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 32000);
+  else if (f >= 3)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 16000);
+  else if (f >= 2)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 3400);
+  else if (f == 1)
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 480);
+  else
+    DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 131);
+}
+
+// TODO: rationalise the size of these... could really use sparse arrays etc.
+static HardwareTimer * pin_timer[100] = {0};
+static uint32_t channel_frequency[100] = {0};
+static uint32_t pin_channel[100] = {0};
+
+// Using the HardwareTimer library API included in stm32duino core to handle PWM duties
+// TODO: in order to use the HA code above which Neil kindly wrote, we may have to do something more
+// sophisticated about detecting any clash between the timer we'd like to use for PWM and the ones
+// currently used for HA so they don't interfere with one another. For now we'll just make PWM
+// work well... then work backwards to integrate with HA mode if we can.
+void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t frequency)
+{
+  if (pin_timer[pin] == NULL) {
+    // Automatically retrieve TIM instance and channel associated to pin
+    // This is used to be compatible with all STM32 series automatically.
+    TIM_TypeDef *Instance = (TIM_TypeDef *)pinmap_peripheral(digitalPinToPinName(pin), PinMap_PWM);
+    if (Instance == NULL) {
+      // We shouldn't get here (famous last words) as it ought to have been caught by brakeCanPWM()!
+      DIAG(F("DCCEXanalogWriteFrequency::Pin %d has no PWM function!"), pin);
+      return;
+    }
+    pin_channel[pin] = STM_PIN_CHANNEL(pinmap_function(digitalPinToPinName(pin), PinMap_PWM));
+
+    // Instantiate HardwareTimer object. Thanks to 'new' instantiation,
+    // HardwareTimer is not destructed when setup function is finished.
+    pin_timer[pin] = new HardwareTimer(Instance);
+    // Configure and start PWM
+    // MyTim->setPWM(channel, pin, 5, 10, NULL, NULL); // No callback required, we can simplify the function call
+    if (pin_timer[pin] != NULL)
+    {
+      pin_timer[pin]->setPWM(pin_channel[pin], pin, frequency, 0); // set frequency in Hertz, 0% dutycycle
+      DIAG(F("DCCEXanalogWriteFrequency::Pin %d on Timer Channel %d, frequency %d"), pin, pin_channel[pin], frequency);
+    }
+    else
+      DIAG(F("DCCEXanalogWriteFrequency::failed to allocate HardwareTimer instance!"));
+  }
+  else
+  {
+    // Frequency change request
+    if (frequency != channel_frequency[pin])
+    {
+      pinmap_pinout(digitalPinToPinName(pin), PinMap_TIM); // ensure the pin has been configured!
+      pin_timer[pin]->setOverflow(frequency, HERTZ_FORMAT); // Just change the frequency if it's already running!
+      DIAG(F("DCCEXanalogWriteFrequency::setting frequency to %d"), frequency);
+    }
+  }
+  channel_frequency[pin] = frequency;
+  return;
+}
+
+void DCCTimer::DCCEXanalogWrite(uint8_t pin, int value, bool invert) {
+    if (invert)
+      value = 255-value;
+    // Calculate percentage duty cycle from value given
+    uint32_t duty_cycle = (value * 100 / 256) + 1;
+    if (pin_timer[pin] != NULL) {
+      // if (duty_cycle == 100)
+      // {
+      //   pin_timer[pin]->pauseChannel(pin_channel[pin]);
+      //   DIAG(F("DCCEXanalogWrite::Pausing timer channel on pin %d"), pin);
+      // }
+      // else
+      // {
+        pinmap_pinout(digitalPinToPinName(pin), PinMap_TIM); // ensure the pin has been configured!
+        // pin_timer[pin]->resumeChannel(pin_channel[pin]);
+        pin_timer[pin]->setCaptureCompare(pin_channel[pin], duty_cycle, PERCENT_COMPARE_FORMAT); // DCC_EX_PWM_FREQ Hertz, duty_cycle% dutycycle
+        DIAG(F("DCCEXanalogWrite::Pin %d, value %d, duty cycle %d"), pin, value, duty_cycle);
+      // }
+    }
+    else
+      DIAG(F("DCCEXanalogWrite::Pin %d is not configured for PWM!"), pin);
+}
+
+
+// Now we can handle more ADCs, maybe this works!
+#define NUM_ADC_INPUTS NUM_ANALOG_INPUTS
+
+uint32_t ADCee::usedpins = 0;         // Max of 32 ADC input channels!
+uint8_t ADCee::highestPin = 0;        // Highest pin to scan
+int * ADCee::analogvals = NULL;       // Array of analog values last captured
+uint32_t * ADCee::analogchans = NULL;        // Array of channel numbers to be scanned
+// bool adc1configured = false;
+ADC_TypeDef * * ADCee::adcchans = NULL;      // Array to capture which ADC is each input channel on
+
+int16_t ADCee::ADCmax()
+{
+    return 4095;
+}
+
+int ADCee::init(uint8_t pin) {
+
+  int value = 0;
+  PinName stmpin = analogInputToPinName(pin);
+  if (stmpin == NC) // do not continue if this is not an analog pin at all
+    return -1024;   // some silly value as error
+
+  uint32_t stmgpio = STM_PORT(stmpin); // converts to the GPIO port (16-bits per port group on STM32)
+  uint32_t adcchan =  STM_PIN_CHANNEL(pinmap_function(stmpin, PinMap_ADC)); // find ADC input channel
+  ADC_TypeDef *adc = (ADC_TypeDef *)pinmap_find_peripheral(stmpin, PinMap_ADC); // find which ADC this pin is on ADC1/2/3 etc.
+  int adcnum = 1;
+  // All variants have ADC1
+  if (adc == ADC1)
+    DIAG(F("ADCee::init(): found pin %d on ADC1"), pin);
+  // Checking for ADC2 and ADC3 being defined helps cater for more variants
+#if defined(ADC2)
+  else if (adc == ADC2)
+  {
+    DIAG(F("ADCee::init(): found pin %d on ADC2"), pin);
+    adcnum = 2;
+  }
+#endif
+#if defined(ADC3)
+  else if (adc == ADC3)
+  {
+    DIAG(F("ADCee::init(): found pin %d on ADC3"), pin);
+    adcnum = 3;
+  }
+#endif
+  else DIAG(F("ADCee::init(): found pin %d on unknown ADC!"), pin);
+
+    // Port config - find which port we're on and power it up
+    GPIO_TypeDef *gpioBase;
+
+    switch (stmgpio)
+    {
+    case 0x00:
+        RCC->AHB1ENR |= RCC_AHB1ENR_GPIOAEN; //Power up PORTA
+        gpioBase = GPIOA;
+        break;
+    case 0x01:
+        RCC->AHB1ENR |= RCC_AHB1ENR_GPIOBEN; //Power up PORTB
+        gpioBase = GPIOB;
+        break;
+    case 0x02:
+        RCC->AHB1ENR |= RCC_AHB1ENR_GPIOCEN; //Power up PORTC
+        gpioBase = GPIOC;
+        break;
+    case 0x03:
+        RCC->AHB1ENR |= RCC_AHB1ENR_GPIODEN; //Power up PORTD
+        gpioBase = GPIOD;
+        break;
+    case 0x04:
+        RCC->AHB1ENR |= RCC_AHB1ENR_GPIOEEN; //Power up PORTE
+        gpioBase = GPIOE;
+        break;
+#if defined(GPIOF)
+    case 0x05:
+        RCC->AHB1ENR |= RCC_AHB1ENR_GPIOFEN; //Power up PORTF
+        gpioBase = GPIOF;
+        break;
+#endif
+#if defined(GPIOG)
+    case 0x06:
+        RCC->AHB1ENR |= RCC_AHB1ENR_GPIOGEN; //Power up PORTG
+        gpioBase = GPIOG;
+        break;
+#endif
+#if defined(GPIOH)
+    case 0x07:
+        RCC->AHB1ENR |= RCC_AHB1ENR_GPIOHEN; //Power up PORTH
+        gpioBase = GPIOH;
+        break;
+#endif
+    default:
+      return -1023; // some silly value as error
+  }
+
+  // Set pin mux mode to analog input, the 32 bit port mode register has 2 bits per pin
+  gpioBase->MODER |= (0b011 << (STM_PIN(stmpin) << 1)); // Set pin mux to analog mode (binary 11)
+
+  // Set the sampling rate for that analog input
+  // This is F411x specific! Different on for example F334
+  // STM32F11xC/E Reference manual
+  // 11.12.4 ADC sample time register 1 (ADC_SMPR1) (channels 10 to 18)
+  // 11.12.5 ADC sample time register 2 (ADC_SMPR2) (channels 0 to 9)
+  if (adcchan > 18)
+    return -1022; // silly value as error
+  if (adcchan < 10)
+    adc->SMPR2 |= (0b111 << (adcchan * 3)); // Channel sampling rate 480 cycles
+  else
+    adc->SMPR1 |= (0b111 << ((adcchan - 10) * 3)); // Channel sampling rate 480 cycles
+
+  // Read the inital ADC value for this analog input
+  adc->SQR3 = adcchan;           // 1st conversion in regular sequence
+  adc->CR2 |= ADC_CR2_SWSTART;   //(1 << 30);                     // Start 1st conversion SWSTART
+  while(!(adc->SR & (1 << 1)));  // Wait until conversion is complete
+  value = adc->DR;               // Read value from register
+
+  uint8_t id = pin - PNUM_ANALOG_BASE;
+  // if (id > 15) { // today we have not enough bits in the mask to support more
+  //   return -1021;
+  // }
+
+  if (analogvals == NULL) {  // allocate analogvals, analogchans and adcchans if this is the first invocation of init
+    analogvals = (int *)calloc(NUM_ADC_INPUTS+1, sizeof(int));
+    analogchans = (uint32_t *)calloc(NUM_ADC_INPUTS+1, sizeof(uint32_t));
+    adcchans = (ADC_TypeDef **)calloc(NUM_ADC_INPUTS+1, sizeof(ADC_TypeDef));
+  }
+  analogvals[id] = value;     // Store sampled value
+  analogchans[id] = adcchan;  // Keep track of which ADC channel is used for reading this pin
+  adcchans[id] = adc;         // Keep track of which ADC this channel is on
+  usedpins |= (1 << id);                // This pin is now ready
+  if (id > highestPin) highestPin = id; // Store our highest pin in use
+
+  DIAG(F("ADCee::init(): value=%d, ADC%d: channel=%d, id=%d"), value, adcnum, adcchan, id);
+
+  return value;
+}
+
+/*
+ * Read function ADCee::read(pin) to get value instead of analogRead(pin)
+ */
+int ADCee::read(uint8_t pin, bool fromISR) {
+  uint8_t id = pin - PNUM_ANALOG_BASE;
+  // Was this pin initialised yet?
+  if ((usedpins & (1<<id) ) == 0)
+    return -1023;
+  // We do not need to check (analogvals == NULL)
+  // because usedpins would still be 0 in that case
+  return analogvals[id];
+}
+
+/*
+ * Scan function that is called from interrupt
+ */
+#pragma GCC push_options
+#pragma GCC optimize ("-O3")
+void ADCee::scan() {
+  static uint8_t id = 0;     // id and mask are the same thing but it is faster to
+  static uint16_t mask = 1;  // increment and shift instead to calculate mask from id
+  static bool waiting = false;
+  static ADC_TypeDef *adc;
+
+  adc = adcchans[id];
+  if (waiting)
+  {
+    // look if we have a result
+    if (!(adc->SR & (1 << 1)))
+      return; // no result, continue to wait
+    // found value
+    analogvals[id] = adc->DR;
+    // advance at least one track
+#ifdef DEBUG_ADC
+    if (id == 1) TrackManager::track[1]->setBrake(0);
+#endif
+    waiting = false;
+    id++;
+    mask = mask << 1;
+    if (id > highestPin) { // the 1 has been shifted out
+      id = 0;
+      mask = 1;
+    }
+  }
+  if (!waiting) {
+    if (usedpins == 0) // otherwise we would loop forever
+      return;
+    // look for a valid track to sample or until we are around
+    while (true) {
+      if (mask  & usedpins) {
+        // start new ADC aquire on id
+        adc = adcchans[id];
+        adc->SQR3 = analogchans[id]; // 1st conversion in regular sequence
+        adc->CR2 |= (1 << 30);       // Start 1st conversion SWSTART
+#ifdef DEBUG_ADC
+	if (id == 1) TrackManager::track[1]->setBrake(1);
+#endif
+	waiting = true;
+	return;
+      }
+      id++;
+      mask = mask << 1;
+      if (id > highestPin) {
+      	id = 0;
+      	mask = 1;
+      }
+    }
+  }
+}
+#pragma GCC pop_options
+
+void ADCee::begin() {
+  noInterrupts();
+  //ADC1 config sequence
+  RCC->APB2ENR |= RCC_APB2ENR_ADC1EN; // Enable ADC1 clock
+  // Set ADC prescaler - DIV8 ~ 40ms, DIV6 ~ 30ms, DIV4 ~ 20ms, DIV2 ~ 11ms
+  ADC->CCR = (0 << 16); // Set prescaler 0=DIV2, 1=DIV4, 2=DIV6, 3=DIV8
+  ADC1->CR1 &= ~(1 << 8); //SCAN mode disabled (Bit8)
+  ADC1->CR1 &= ~(3 << 24); //12bit resolution (Bit24,25 0b00)
+  ADC1->SQR1 = (1 << 20); //Set number of conversions projected (L[3:0] 0b0001) -> 1 conversion
+  // Disable the DMA controller for ADC1
+  ADC1->CR2 &= ~ADC_CR2_DMA;
+  ADC1->CR2 &= ~(1 << 1); //Single conversion
+  ADC1->CR2 &= ~(1 << 11); //Right alignment of data bits bit12....bit0
+  ADC1->SQR1 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register
+  ADC1->SQR2 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register
+  ADC1->SQR3 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register
+  ADC1->CR2 |= (1 << 0); // Switch on ADC1
+  // Wait for ADC1 to become ready (calibration complete)
+  while (!(ADC1->CR2 & ADC_CR2_ADON)) {
+  }
+#if defined(ADC2)
+  // Enable the ADC2 clock
+  RCC->APB2ENR |= RCC_APB2ENR_ADC2EN;
+
+  // Initialize ADC2
+  ADC2->CR1 = 0; // Disable all channels
+  ADC2->CR2 = 0; // Clear CR2 register
+
+  ADC2->CR1 &= ~(1 << 8); //SCAN mode disabled (Bit8)
+  ADC2->CR1 &= ~(3 << 24); //12bit resolution (Bit24,25 0b00)
+  ADC2->SQR1 = (1 << 20); //Set number of conversions projected (L[3:0] 0b0001) -> 1 conversion
+  ADC2->CR2 &= ~ADC_CR2_DMA;   // Disable the DMA controller for ADC3
+  ADC2->CR2 &= ~(1 << 1); //Single conversion
+  ADC2->CR2 &= ~(1 << 11); //Right alignment of data bits bit12....bit0
+  ADC2->SQR1 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register
+  ADC2->SQR2 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register
+  ADC2->SQR3 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register
+
+  // Enable the ADC
+  ADC2->CR2 |= ADC_CR2_ADON;
+
+  // Wait for ADC2 to become ready (calibration complete)
+  while (!(ADC2->CR2 & ADC_CR2_ADON)) {
+  }
+
+  // Perform ADC3 calibration (optional)
+  // ADC3->CR2 |= ADC_CR2_CAL;
+  // while (ADC3->CR2 & ADC_CR2_CAL) {
+  // }
+#endif
+#if defined(ADC3)
+  // Enable the ADC3 clock
+  RCC->APB2ENR |= RCC_APB2ENR_ADC3EN;
+
+  // Initialize ADC3
+  ADC3->CR1 = 0; // Disable all channels
+  ADC3->CR2 = 0; // Clear CR2 register
+
+  ADC3->CR1 &= ~(1 << 8); //SCAN mode disabled (Bit8)
+  ADC3->CR1 &= ~(3 << 24); //12bit resolution (Bit24,25 0b00)
+  ADC3->SQR1 = (1 << 20); //Set number of conversions projected (L[3:0] 0b0001) -> 1 conversion
+  ADC3->CR2 &= ~ADC_CR2_DMA;   // Disable the DMA controller for ADC3
+  ADC3->CR2 &= ~(1 << 1); //Single conversion
+  ADC3->CR2 &= ~(1 << 11); //Right alignment of data bits bit12....bit0
+  ADC3->SQR1 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register
+  ADC3->SQR2 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register
+  ADC3->SQR3 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register
+
+  // Enable the ADC
+  ADC3->CR2 |= ADC_CR2_ADON;
+
+  // Wait for ADC3 to become ready (calibration complete)
+  while (!(ADC3->CR2 & ADC_CR2_ADON)) {
+  }
+
+  // Perform ADC3 calibration (optional)
+  // ADC3->CR2 |= ADC_CR2_CAL;
+  // while (ADC3->CR2 & ADC_CR2_CAL) {
+  // }
+#endif
+  interrupts();
+}
+#endif

DCCTimerTEENSY.cpp

@@ -0,0 +1,185 @@
+/*
+ *  © 2022 Paul M Antoine
+ *  © 2021 Mike S
+ *  © 2021 Harald Barth
+ *  © 2021 Fred Decker
+ *  © 2021 Chris Harlow
+ *  © 2021 David Cutting
+ *  All rights reserved.
+ *  
+ *  This file is part of Asbelos DCC API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// ATTENTION: this file only compiles on a TEENSY
+// Please refer to DCCTimer.h for general comments about how this class works
+// This is to avoid repetition and duplication.
+#ifdef TEENSYDUINO
+
+#include "DCCTimer.h"
+
+INTERRUPT_CALLBACK interruptHandler=0;
+
+IntervalTimer myDCCTimer;
+
+void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
+  interruptHandler=callback;
+  myDCCTimer.begin(interruptHandler, DCC_SIGNAL_TIME);
+  }
+
+void DCCTimer::startRailcomTimer(byte brakePin) {
+  // TODO: for intended operation see DCCTimerAVR.cpp
+  (void) brakePin; 
+}
+
+void DCCTimer::ackRailcomTimer() {
+  // TODO: for intended operation see DCCTimerAVR.cpp
+}
+
+bool DCCTimer::isPWMPin(byte pin) {
+       //Teensy: digitalPinHasPWM, todo
+      (void) pin;
+       return false;  // TODO what are the relevant pins? 
+  }
+
+void DCCTimer::setPWM(byte pin, bool high) {
+    // TODO what are the relevant pins?
+    (void) pin;
+    (void) high;
+}
+
+void DCCTimer::clearPWM() {
+    // Do nothing unless we implent HA
+}
+
+#if defined(__IMXRT1062__)  //Teensy 4.0 and Teensy 4.1
+void   DCCTimer::getSimulatedMacAddress(byte mac[6]) {
+    uint32_t m1 = HW_OCOTP_MAC1;
+    uint32_t m2 = HW_OCOTP_MAC0;
+    mac[0] = m1 >> 8;
+    mac[1] = m1 >> 0;
+    mac[2] = m2 >> 24;
+    mac[3] = m2 >> 16;
+    mac[4] = m2 >> 8;
+    mac[5] = m2 >> 0;
+  }
+
+#else
+
+// http://forum.pjrc.com/threads/91-teensy-3-MAC-address
+void teensyRead(uint8_t word, uint8_t *mac, uint8_t offset) {
+  FTFL_FCCOB0 = 0x41;             // Selects the READONCE command
+  FTFL_FCCOB1 = word;             // read the given word of read once area
+
+  // launch command and wait until complete
+  FTFL_FSTAT = FTFL_FSTAT_CCIF;
+  while(!(FTFL_FSTAT & FTFL_FSTAT_CCIF));
+
+  *(mac+offset) =   FTFL_FCCOB5;       // collect only the top three bytes,
+  *(mac+offset+1) = FTFL_FCCOB6;       // in the right orientation (big endian).
+  *(mac+offset+2) = FTFL_FCCOB7;       // Skip FTFL_FCCOB4 as it's always 0.
+}
+
+void   DCCTimer::getSimulatedMacAddress(byte mac[6]) {
+    teensyRead(0xe,mac,0);
+    teensyRead(0xf,mac,3);
+  }
+#endif 
+
+volatile int DCCTimer::minimum_free_memory=__INT_MAX__;
+
+// Return low memory value... 
+int DCCTimer::getMinimumFreeMemory() {
+  noInterrupts(); // Disable interrupts to get volatile value 
+  int retval = freeMemory();
+  interrupts();
+  return retval;
+}
+
+extern "C" char* sbrk(int incr);
+
+#if !defined(__IMXRT1062__)
+int DCCTimer::freeMemory() {
+  char top;
+  return &top - reinterpret_cast<char*>(sbrk(0));
+}
+
+#else
+#if defined(ARDUINO_TEENSY40)
+  static const unsigned DTCM_START = 0x20000000UL;
+  static const unsigned OCRAM_START = 0x20200000UL;
+  static const unsigned OCRAM_SIZE = 512;
+  static const unsigned FLASH_SIZE = 1984;
+#elif defined(ARDUINO_TEENSY41)
+  static const unsigned DTCM_START = 0x20000000UL;
+  static const unsigned OCRAM_START = 0x20200000UL;
+  static const unsigned OCRAM_SIZE = 512;
+  static const unsigned FLASH_SIZE = 7936;
+#if TEENSYDUINO>151
+  extern "C" uint8_t external_psram_size;
+#endif
+#endif
+
+int DCCTimer::freeMemory() {
+  extern unsigned long _ebss;
+  extern unsigned long _sdata;
+  extern unsigned long _estack;
+  const unsigned DTCM_START = 0x20000000UL;
+  unsigned dtcm = (unsigned)&_estack - DTCM_START;
+  unsigned stackinuse = (unsigned) &_estack -  (unsigned) __builtin_frame_address(0);
+  unsigned varsinuse = (unsigned)&_ebss - (unsigned)&_sdata;
+  unsigned freemem = dtcm - (stackinuse + varsinuse);
+  return freemem;
+}
+
+#endif
+void DCCTimer::reset() {
+  // found at https://forum.pjrc.com/threads/59935-Reboot-Teensy-programmatically
+  SCB_AIRCR = 0x05FA0004;
+}
+
+void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) {
+}
+void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t fbits) {
+}
+
+int16_t ADCee::ADCmax() {
+  return 4095;
+}
+
+int ADCee::init(uint8_t pin) {
+  return analogRead(pin);
+}
+/*
+ * Read function ADCee::read(pin) to get value instead of analogRead(pin)
+ */
+int ADCee::read(uint8_t pin, bool fromISR) {
+  int current;
+  if (!fromISR) noInterrupts();
+  current = analogRead(pin);
+  if (!fromISR) interrupts();
+  return current;
+}
+/*
+ * Scan function that is called from interrupt
+ */
+void ADCee::scan() {
+}
+
+void ADCee::begin() {
+  noInterrupts();
+  interrupts();
+}
+#endif

DCCWaveform.cpp

@@ -1,8 +1,12 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
- *  © 2020, Harald Barth.
+ *  © 2021 Neil McKechnie
+ *  © 2021 Mike S
+ *  © 2021 Fred Decker
+ *  © 2020-2022 Harald Barth
+ *  © 2020-2021 Chris Harlow
+ *  All rights reserved.
  *  
- *  This file is part of Asbelos DCC API
+ *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
@@ -17,173 +21,30 @@
  *  You should have received a copy of the GNU General Public License
  *  along with CommandStation.  If not, see <https://www.gnu.org/licenses/>.
  */
-
+#ifndef ARDUINO_ARCH_ESP32
+  // This code is replaced entirely on an ESP32
 #include <Arduino.h>
 
 #include "DCCWaveform.h"
+#include "TrackManager.h"
 #include "DCCTimer.h"
+#include "DCCACK.h"
 #include "DIAG.h"
-#include "freeMemory.h"
+
 
 DCCWaveform  DCCWaveform::mainTrack(PREAMBLE_BITS_MAIN, true);
 DCCWaveform  DCCWaveform::progTrack(PREAMBLE_BITS_PROG, false);
 
-bool DCCWaveform::progTrackSyncMain=false; 
-bool DCCWaveform::progTrackBoosted=false; 
-int  DCCWaveform::progTripValue=0;
-volatile uint8_t DCCWaveform::numAckGaps=0;
-volatile uint8_t DCCWaveform::numAckSamples=0;
-uint8_t DCCWaveform::trailingEdgeCounter=0;
-
-void DCCWaveform::begin(MotorDriver * mainDriver, MotorDriver * progDriver) {
-  mainTrack.motorDriver=mainDriver;
-  progTrack.motorDriver=progDriver;
-  progTripValue = progDriver->mA2raw(TRIP_CURRENT_PROG); // need only calculate once hence static
-  mainTrack.setPowerMode(POWERMODE::OFF);      
-  progTrack.setPowerMode(POWERMODE::OFF);
-  // Fault pin config for odd motor boards (example pololu)
-  MotorDriver::commonFaultPin = ((mainDriver->getFaultPin() == progDriver->getFaultPin())
-				 && (mainDriver->getFaultPin() != UNUSED_PIN));
-  // Only use PWM if both pins are PWM capable. Otherwise JOIN does not work
-  MotorDriver::usePWM= mainDriver->isPWMCapable() && progDriver->isPWMCapable();
-  DIAG(F("Signal pin config: %S accuracy waveform"),
-	 MotorDriver::usePWM ? F("high") : F("normal") );
-  DCCTimer::begin(DCCWaveform::interruptHandler);     
-}
-
-void DCCWaveform::loop(bool ackManagerActive) {
-  mainTrack.checkPowerOverload(false);
-  progTrack.checkPowerOverload(ackManagerActive);
-}
-
-#pragma GCC push_options
-#pragma GCC optimize ("-O3")
-void DCCWaveform::interruptHandler() {
-  // call the timer edge sensitive actions for progtrack and maintrack
-  // member functions would be cleaner but have more overhead
-  byte sigMain=signalTransform[mainTrack.state];
-  byte sigProg=progTrackSyncMain? sigMain : signalTransform[progTrack.state];
-  
-  // Set the signal state for both tracks
-  mainTrack.motorDriver->setSignal(sigMain);
-  progTrack.motorDriver->setSignal(sigProg);
-  
-  // Move on in the state engine
-  mainTrack.state=stateTransform[mainTrack.state];    
-  progTrack.state=stateTransform[progTrack.state];    
-
-
-  // WAVE_PENDING means we dont yet know what the next bit is
-  if (mainTrack.state==WAVE_PENDING) mainTrack.interrupt2();  
-  if (progTrack.state==WAVE_PENDING) progTrack.interrupt2();
-  else if (progTrack.ackPending) progTrack.checkAck();
-
-}
-#pragma GCC push_options
-
-// An instance of this class handles the DCC transmissions for one track. (main or prog)
-// Interrupts are marshalled via the statics.
-// A track has a current transmit buffer, and a pending buffer.
-// When the current buffer is exhausted, either the pending buffer (if there is one waiting) or an idle buffer.
-
 
 // This bitmask has 9 entries as each byte is trasmitted as a zero + 8 bits.
 const byte bitMask[] = {0x00, 0x80, 0x40, 0x20, 0x10, 0x08, 0x04, 0x02, 0x01};
 
-
-DCCWaveform::DCCWaveform( byte preambleBits, bool isMain) {
-  isMainTrack = isMain;
-  packetPending = false;
-  memcpy(transmitPacket, idlePacket, sizeof(idlePacket));
-  state = WAVE_START;
-  // The +1 below is to allow the preamble generator to create the stop bit
-  // for the previous packet. 
-  requiredPreambles = preambleBits+1;  
-  bytes_sent = 0;
-  bits_sent = 0;
-  sampleDelay = 0;
-  lastSampleTaken = millis();
-  ackPending=false;
-}
-
-POWERMODE DCCWaveform::getPowerMode() {
-  return powerMode;
-}
-
-void DCCWaveform::setPowerMode(POWERMODE mode) {
-  powerMode = mode;
-  bool ison = (mode == POWERMODE::ON);
-  motorDriver->setPower( ison);
-  sentResetsSincePacket=0; 
-}
+const byte idlePacket[] = {0xFF, 0x00, 0xFF};
+const byte resetPacket[] = {0x00, 0x00, 0x00};
 
 
-void DCCWaveform::checkPowerOverload(bool ackManagerActive) {
-  if (millis() - lastSampleTaken  < sampleDelay) return;
-  lastSampleTaken = millis();
-  int tripValue= motorDriver->getRawCurrentTripValue();
-  if (!isMainTrack && !ackManagerActive && !progTrackSyncMain && !progTrackBoosted)
-    tripValue=progTripValue;
-  
-  // Trackname for diag messages later
-  const FSH*trackname = isMainTrack ? F("MAIN") : F("PROG");
-  switch (powerMode) {
-    case POWERMODE::OFF:
-      sampleDelay = POWER_SAMPLE_OFF_WAIT;
-      break;
-    case POWERMODE::ON:
-      // Check current
-      lastCurrent=motorDriver->getCurrentRaw();
-      if (lastCurrent < 0) {
-	  // We have a fault pin condition to take care of
-	  lastCurrent = -lastCurrent;
-	  setPowerMode(POWERMODE::OVERLOAD); // Turn off, decide later how fast to turn on again
-	  if (MotorDriver::commonFaultPin) {
-	      if (lastCurrent <= tripValue) {
-		setPowerMode(POWERMODE::ON); // maybe other track
-	      }
-	      // Write this after the fact as we want to turn on as fast as possible
-	      // because we don't know which output actually triggered the fault pin
-	      DIAG(F("COMMON FAULT PIN ACTIVE - TOGGLED POWER on %S"), trackname);
-	  } else {
-	    DIAG(F("%S FAULT PIN ACTIVE - OVERLOAD"), trackname);
-	      if (lastCurrent < tripValue) {
-		  lastCurrent = tripValue; // exaggerate
-	      }
-	  }
-      }
-      if (lastCurrent < tripValue) {
-        sampleDelay = POWER_SAMPLE_ON_WAIT;
-	if(power_good_counter<100)
-	  power_good_counter++;
-	else
-	  if (power_sample_overload_wait>POWER_SAMPLE_OVERLOAD_WAIT) power_sample_overload_wait=POWER_SAMPLE_OVERLOAD_WAIT;
-      } else {
-        setPowerMode(POWERMODE::OVERLOAD);
-        unsigned int mA=motorDriver->raw2mA(lastCurrent);
-        unsigned int maxmA=motorDriver->raw2mA(tripValue);
-	power_good_counter=0;
-        sampleDelay = power_sample_overload_wait;
-        DIAG(F("%S TRACK POWER OVERLOAD current=%d max=%d offtime=%d"), trackname, mA, maxmA, sampleDelay);
-	if (power_sample_overload_wait >= 10000)
-	    power_sample_overload_wait = 10000;
-	else
-	    power_sample_overload_wait *= 2;
-      }
-      break;
-    case POWERMODE::OVERLOAD:
-      // Try setting it back on after the OVERLOAD_WAIT
-      setPowerMode(POWERMODE::ON);
-      sampleDelay = POWER_SAMPLE_ON_WAIT;
-      // Debug code....
-      DIAG(F("%S TRACK POWER RESET delay=%d"), trackname, sampleDelay);
-      break;
-    default:
-      sampleDelay = 999; // cant get here..meaningless statement to avoid compiler warning.
-  }
-}
 // For each state of the wave  nextState=stateTransform[currentState] 
-const WAVE_STATE DCCWaveform::stateTransform[]={
+const WAVE_STATE stateTransform[]={
    /* WAVE_START   -> */ WAVE_PENDING,
    /* WAVE_MID_1   -> */ WAVE_START,
    /* WAVE_HIGH_0  -> */ WAVE_MID_0,
@@ -192,27 +53,104 @@ const WAVE_STATE DCCWaveform::stateTransform[]={
    /* WAVE_PENDING (should not happen) -> */ WAVE_PENDING};
 
 // For each state of the wave, signal pin is HIGH or LOW   
-const bool DCCWaveform::signalTransform[]={
+const bool signalTransform[]={
    /* WAVE_START   -> */ HIGH,
    /* WAVE_MID_1   -> */ LOW,
    /* WAVE_HIGH_0  -> */ HIGH,
    /* WAVE_MID_0   -> */ LOW,
    /* WAVE_LOW_0   -> */ LOW,
    /* WAVE_PENDING (should not happen) -> */ LOW};
-        
+
+void DCCWaveform::begin() {
+  DCCTimer::begin(DCCWaveform::interruptHandler);     
+}
+
+void DCCWaveform::loop() {
+ // empty placemarker in case ESP32 needs something here 
+}
+
+#pragma GCC push_options
+#pragma GCC optimize ("-O3")
+void DCCWaveform::interruptHandler() {
+  // call the timer edge sensitive actions for progtrack and maintrack
+  // member functions would be cleaner but have more overhead
+  byte sigMain=signalTransform[mainTrack.state];
+  byte sigProg=TrackManager::progTrackSyncMain? sigMain : signalTransform[progTrack.state];
+  
+  // Set the signal state for both tracks
+  TrackManager::setDCCSignal(sigMain);
+  TrackManager::setPROGSignal(sigProg);
+
+  // Refresh the values in the ADCee object buffering the values of the ADC HW
+  ADCee::scan();
+
+  // Move on in the state engine
+  mainTrack.state=stateTransform[mainTrack.state];    
+  progTrack.state=stateTransform[progTrack.state];    
+
+  // WAVE_PENDING means we dont yet know what the next bit is
+  if (mainTrack.state==WAVE_PENDING) mainTrack.interrupt2();  
+  if (progTrack.state==WAVE_PENDING) progTrack.interrupt2();
+  else DCCACK::checkAck(progTrack.getResets());
+
+}
+#pragma GCC pop_options
+
+// An instance of this class handles the DCC transmissions for one track. (main or prog)
+// Interrupts are marshalled via the statics.
+// A track has a current transmit buffer, and a pending buffer.
+// When the current buffer is exhausted, either the pending buffer (if there is one waiting) or an idle buffer.
+
+
+
+DCCWaveform::DCCWaveform( byte preambleBits, bool isMain) {
+  isMainTrack = isMain;
+  packetPending = false;
+  reminderWindowOpen = false;
+  memcpy(transmitPacket, idlePacket, sizeof(idlePacket));
+  state = WAVE_START;
+  // The +1 below is to allow the preamble generator to create the stop bit
+  // for the previous packet. 
+  requiredPreambles = preambleBits+1;  
+  bytes_sent = 0;
+  bits_sent = 0;
+}
+    
+volatile bool DCCWaveform::railcomActive=false;     // switched on by user
+volatile bool DCCWaveform::railcomDebug=false;     // switched on by user
+
+bool DCCWaveform::setRailcom(bool on, bool debug) {
+  if (on) {
+    // TODO check possible
+    railcomActive=true;
+    railcomDebug=debug;
+  }
+  else {
+    railcomActive=false;
+    railcomDebug=false;
+  } 
+  return railcomActive;
+}
+
 #pragma GCC push_options
 #pragma GCC optimize ("-O3")
 void DCCWaveform::interrupt2() {
   // calculate the next bit to be sent:
   // set state WAVE_MID_1  for a 1=bit
   //        or WAVE_HIGH_0 for a 0 bit.
-
   if (remainingPreambles > 0 ) {
     state=WAVE_MID_1;  // switch state to trigger LOW on next interrupt
     remainingPreambles--;
+  
+    // As we get to the end of the preambles, open the reminder window.
+    // This delays any reminder insertion until the last moment so
+    // that the reminder doesn't block a more urgent packet. 
+    reminderWindowOpen=transmitRepeats==0 && remainingPreambles<12 && remainingPreambles>1;
+    if (remainingPreambles==1) promotePendingPacket();
+    else if (remainingPreambles==10 && isMainTrack && railcomActive) DCCTimer::ackRailcomTimer();
     // Update free memory diagnostic as we don't have anything else to do this time.
     // Allow for checkAck and its called functions using 22 bytes more.
-    updateMinimumFreeMemory(22); 
+    else DCCTimer::updateMinimumFreeMemoryISR(22); 
     return;
   }
 
@@ -231,35 +169,19 @@ void DCCWaveform::interrupt2() {
     if (bytes_sent >= transmitLength) {
       // end of transmission buffer... repeat or switch to next message
       bytes_sent = 0;
+      // preamble for next packet will start...
       remainingPreambles = requiredPreambles;
-
-      if (transmitRepeats > 0) {
-        transmitRepeats--;
+      
+      // set the railcom coundown to trigger half way 
+      // through the first preamble bit.
+      // Note.. we are still sending the last packet bit
+      //    and we then have to allow for the packet end bit
+      if (isMainTrack && railcomActive) DCCTimer::startRailcomTimer(9);
       }
-      else if (packetPending) {
-        // Copy pending packet to transmit packet
-        // a fixed length memcpy is faster than a variable length loop for these small lengths
-        // for (int b = 0; b < pendingLength; b++) transmitPacket[b] = pendingPacket[b];
-        memcpy( transmitPacket, pendingPacket, sizeof(pendingPacket));
-        
-        transmitLength = pendingLength;
-        transmitRepeats = pendingRepeats;
-        packetPending = false;
-        sentResetsSincePacket=0;
-      }
-      else {
-        // Fortunately reset and idle packets are the same length
-        memcpy( transmitPacket, isMainTrack ? idlePacket : resetPacket, sizeof(idlePacket));
-        transmitLength = sizeof(idlePacket);
-        transmitRepeats = 0;
-        if (sentResetsSincePacket<250) sentResetsSincePacket++;
-      }
-    }
   }  
 }
 #pragma GCC pop_options
 
-
 // Wait until there is no packet pending, then make this pending
 void DCCWaveform::schedulePacket(const byte buffer[], byte byteCount, byte repeats) {
   if (byteCount > MAX_PACKET_SIZE) return; // allow for chksum
@@ -275,91 +197,132 @@ void DCCWaveform::schedulePacket(const byte buffer[], byte byteCount, byte repea
   pendingLength = byteCount + 1;
   pendingRepeats = repeats;
   packetPending = true;
-  sentResetsSincePacket=0;
+  clearResets();
 }
 
-// Operations applicable to PROG track ONLY.
-// (yes I know I could have subclassed the main track but...) 
-
-void DCCWaveform::setAckBaseline() {
-      if (isMainTrack) return;
-      int baseline=motorDriver->getCurrentRaw();
-      ackThreshold= baseline + motorDriver->mA2raw(ackLimitmA);
-      if (Diag::ACK) DIAG(F("ACK baseline=%d/%dmA Threshold=%d/%dmA Duration between %dus and %dus"),
-			  baseline,motorDriver->raw2mA(baseline),
-			  ackThreshold,motorDriver->raw2mA(ackThreshold),
-                          minAckPulseDuration, maxAckPulseDuration);
+bool DCCWaveform::isReminderWindowOpen() {
+  return reminderWindowOpen && ! packetPending;
 }
 
-void DCCWaveform::setAckPending() {
-      if (isMainTrack) return; 
-      ackMaxCurrent=0;
-      ackPulseStart=0;
-      ackPulseDuration=0;
-      ackDetected=false;
-      ackCheckStart=millis();
-      numAckSamples=0;
-      numAckGaps=0;
-      ackPending=true;  // interrupt routines will now take note
-}
+void DCCWaveform::promotePendingPacket() {
+    // fill the transmission packet from the pending packet
+    
+    // Just keep going if repeating  
+    if (transmitRepeats > 0) {
+        transmitRepeats--;
+        return;
+      }
 
-byte DCCWaveform::getAck() {
-      if (ackPending) return (2);  // still waiting
-      if (Diag::ACK) DIAG(F("%S after %dmS max=%d/%dmA pulse=%duS samples=%d gaps=%d"),ackDetected?F("ACK"):F("NO-ACK"), ackCheckDuration,
-			  ackMaxCurrent,motorDriver->raw2mA(ackMaxCurrent), ackPulseDuration, numAckSamples, numAckGaps);
-      if (ackDetected) return (1); // Yes we had an ack
-      return(0);  // pending set off but not detected means no ACK.   
-}
-
-#pragma GCC push_options
-#pragma GCC optimize ("-O3")
-void DCCWaveform::checkAck() {
-    // This function operates in interrupt() time so must be fast and can't DIAG 
-    if (sentResetsSincePacket > 6) {  //ACK timeout
-        ackCheckDuration=millis()-ackCheckStart;
-        ackPending = false;
-        return; 
-    }
-      
-    int current=motorDriver->getCurrentRaw();
-    numAckSamples++;
-    if (current > ackMaxCurrent) ackMaxCurrent=current;
-    // An ACK is a pulse lasting between minAckPulseDuration and maxAckPulseDuration uSecs (refer @haba)
+    if (packetPending) {
+        // Copy pending packet to transmit packet
+        // a fixed length memcpy is faster than a variable length loop for these small lengths
+        // for (int b = 0; b < pendingLength; b++) transmitPacket[b] = pendingPacket[b];
+        memcpy( transmitPacket, pendingPacket, sizeof(pendingPacket));
         
-    if (current>ackThreshold) {
-       if (trailingEdgeCounter > 0) {
-	 numAckGaps++;
-	 trailingEdgeCounter = 0;
-       }
-       if (ackPulseStart==0) ackPulseStart=micros();    // leading edge of pulse detected
-       return;
-    }
-    
-    // not in pulse
-    if (ackPulseStart==0) return; // keep waiting for leading edge 
-    
-    // if we reach to this point, we have
-    // detected trailing edge of pulse
-    if (trailingEdgeCounter == 0) {
-      ackPulseDuration=micros()-ackPulseStart;
-    }
-
-    // but we do not trust it yet and return (which will force another
-    // measurement) and first the third time around with low current
-    // the ack detection will be finalized. 
-    if (trailingEdgeCounter < 2) {
-      trailingEdgeCounter++;
-      return;
-    }
-    trailingEdgeCounter = 0;
-
-    if (ackPulseDuration>=minAckPulseDuration && ackPulseDuration<=maxAckPulseDuration) {
-        ackCheckDuration=millis()-ackCheckStart;
-        ackDetected=true;
-        ackPending=false;
-        transmitRepeats=0;  // shortcut remaining repeat packets 
-        return;  // we have a genuine ACK result
-    }      
-    ackPulseStart=0;  // We have detected a too-short or too-long pulse so ignore and wait for next leading edge 
+        transmitLength = pendingLength;
+        transmitRepeats = pendingRepeats;
+        packetPending = false;
+        clearResets();
+        return;
+      }
+      
+      // nothing to do, just send idles or resets
+      // Fortunately reset and idle packets are the same length
+      // Note: If railcomDebug is on, then we send resets to the main
+      //       track instead of idles. This means that all data will be zeros
+      //       and only the porersets will be ones, making it much
+      //       easier to read on a logic analyser.
+      memcpy( transmitPacket, (isMainTrack && (!railcomDebug)) ? idlePacket : resetPacket, sizeof(idlePacket));
+      transmitLength = sizeof(idlePacket);
+      transmitRepeats = 0;
+      if (getResets() < 250) sentResetsSincePacket++; // only place to increment (private!)
 }
-#pragma GCC pop_options
+#endif
+
+#ifdef ARDUINO_ARCH_ESP32
+#include "DCCWaveform.h"
+#include "DCCACK.h"
+
+DCCWaveform  DCCWaveform::mainTrack(PREAMBLE_BITS_MAIN, true);
+DCCWaveform  DCCWaveform::progTrack(PREAMBLE_BITS_PROG, false);
+RMTChannel *DCCWaveform::rmtMainChannel = NULL;
+RMTChannel *DCCWaveform::rmtProgChannel = NULL;
+
+DCCWaveform::DCCWaveform(byte preambleBits, bool isMain) {
+  isMainTrack = isMain;
+  requiredPreambles = preambleBits;
+}
+void DCCWaveform::begin() {
+  for(const auto& md: TrackManager::getMainDrivers()) {
+    pinpair p = md->getSignalPin();
+    if(rmtMainChannel) {
+      //DIAG(F("added pins %d %d to MAIN channel"), p.pin, p.invpin);
+      rmtMainChannel->addPin(p); // add pin to existing main channel
+    } else {
+      //DIAG(F("new MAIN channel with pins %d %d"), p.pin, p.invpin);
+      rmtMainChannel = new RMTChannel(p, true); /* create new main channel */
+    }
+  }
+  MotorDriver *md = TrackManager::getProgDriver();
+  if (md) {
+    pinpair p = md->getSignalPin();
+    if (rmtProgChannel) {
+      //DIAG(F("added pins %d %d to PROG channel"), p.pin, p.invpin);
+      rmtProgChannel->addPin(p); // add pin to existing prog channel
+    } else {
+      //DIAG(F("new PROGchannel with pins %d %d"), p.pin, p.invpin);
+      rmtProgChannel = new RMTChannel(p, false);
+    }
+  }
+}
+
+void DCCWaveform::schedulePacket(const byte buffer[], byte byteCount, byte repeats) {
+  if (byteCount > MAX_PACKET_SIZE) return; // allow for chksum
+  RMTChannel *rmtchannel = (isMainTrack ? rmtMainChannel : rmtProgChannel);
+  if (rmtchannel == NULL)
+    return; // no idea to prepare packet if we can not send it anyway
+
+  rmtchannel->waitForDataCopy(); // blocking wait so we can write into buffer
+  byte checksum = 0;
+  for (byte b = 0; b < byteCount; b++) {
+    checksum ^= buffer[b];
+    pendingPacket[b] = buffer[b];
+  }
+  // buffer is MAX_PACKET_SIZE but pendingPacket is one bigger
+  pendingPacket[byteCount] = checksum;
+  pendingLength = byteCount + 1;
+  pendingRepeats = repeats;
+// DIAG repeated commands (accesories)
+//  if (pendingRepeats > 0)
+//    DIAG(F("Repeats=%d on %s track"), pendingRepeats, isMainTrack ? "MAIN" : "PROG");
+  // The resets will be zero not only now but as well repeats packets into the future
+  clearResets(repeats+1);
+  {
+    int ret = 0;
+    do {
+      ret = rmtchannel->RMTfillData(pendingPacket, pendingLength, pendingRepeats);
+    } while(ret > 0);
+  }
+}
+
+bool DCCWaveform::isReminderWindowOpen() {
+  if(isMainTrack) {
+    if (rmtMainChannel == NULL)
+      return false;
+    return !rmtMainChannel->busy();
+  } else {
+    if (rmtProgChannel == NULL)
+      return false;
+    return !rmtProgChannel->busy();
+  }
+}
+void IRAM_ATTR DCCWaveform::loop() {
+  DCCACK::checkAck(progTrack.getResets());
+}
+
+bool DCCWaveform::setRailcom(bool on, bool debug) {
+  // TODO... ESP32 railcom waveform
+  return false;
+}
+
+#endif

DCCWaveform.h

@@ -1,8 +1,12 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
- *  © 2020, Harald Barth.
+ *  © 2021 M Steve Todd
+ *  © 2021 Mike S
+ *  © 2021 Fred Decker
+ *  © 2020-2024 Harald Barth
+ *  © 2020-2021 Chris Harlow
+ *  All rights reserved.
  *  
- *  This file is part of Asbelos DCC API
+ *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
@@ -21,107 +25,81 @@
 #define DCCWaveform_h
 
 #include "MotorDriver.h"
+#ifdef ARDUINO_ARCH_ESP32
+#include "DCCRMT.h"
+#include "TrackManager.h"
+#endif
+
 
-// Wait times for power management. Unit: milliseconds
-const int  POWER_SAMPLE_ON_WAIT = 100;
-const int  POWER_SAMPLE_OFF_WAIT = 1000;
-const int  POWER_SAMPLE_OVERLOAD_WAIT = 20;
 
 // Number of preamble bits.
-const int   PREAMBLE_BITS_MAIN = 16;
-const int   PREAMBLE_BITS_PROG = 22;
-const byte   MAX_PACKET_SIZE = 5;  // NMRA standard extended packets, payload size WITHOUT checksum.
+const byte PREAMBLE_BITS_MAIN = 16;
+const byte PREAMBLE_BITS_PROG = 22;
+const byte MAX_PACKET_SIZE = 5;     // NMRA standard extended packets, payload size WITHOUT checksum.
+
 
 // The WAVE_STATE enum is deliberately numbered because a change of order would be catastrophic
 // to the transform array.
-enum  WAVE_STATE : byte {WAVE_START=0,WAVE_MID_1=1,WAVE_HIGH_0=2,WAVE_MID_0=3,WAVE_LOW_0=4,WAVE_PENDING=5};
-
+enum  WAVE_STATE : byte {
+  WAVE_START=0,  // wave going high at start of bit 
+  WAVE_MID_1=1,  // middle of 1 bit 
+  WAVE_HIGH_0=2, // first part of 0 bit high
+  WAVE_MID_0=3,  // middle of 0 bit
+  WAVE_LOW_0=4,  // first part of 0 bit low
+  WAVE_PENDING=5 // next bit not yet known
+  };
 
 // NOTE: static functions are used for the overall controller, then
 // one instance is created for each track.
 
-
-enum class POWERMODE : byte { OFF, ON, OVERLOAD };
-
-const byte idlePacket[] = {0xFF, 0x00, 0xFF};
-const byte resetPacket[] = {0x00, 0x00, 0x00};
-
 class DCCWaveform {
   public:
     DCCWaveform( byte preambleBits, bool isMain);
-    static void begin(MotorDriver * mainDriver, MotorDriver * progDriver);
-    static void loop(bool ackManagerActive);
+    static void begin();
+    static void loop();
     static DCCWaveform  mainTrack;
     static DCCWaveform  progTrack;
-
-    void beginTrack();
-    void setPowerMode(POWERMODE);
-    POWERMODE getPowerMode();
-    void checkPowerOverload(bool ackManagerActive);
-    inline int get1024Current() {
-	  if (powerMode == POWERMODE::ON)
-	      return (int)(lastCurrent*(long int)1024/motorDriver->getRawCurrentTripValue());
-	  return 0;
-    }
-    inline int getCurrentmA() {
-      if (powerMode == POWERMODE::ON)
-        return motorDriver->raw2mA(lastCurrent);
-      return 0;
-    }
-    inline int getMaxmA() {
-      if (maxmA == 0) { //only calculate this for first request, it doesn't change
-        maxmA = motorDriver->raw2mA(motorDriver->getRawCurrentTripValue()); //TODO: replace with actual max value or calc
-      }
-      return maxmA;        
-    }
-    inline int getTripmA() { 
-      if (tripmA == 0) { //only calculate this for first request, it doesn't change
-        tripmA = motorDriver->raw2mA(motorDriver->getRawCurrentTripValue());
-      }
-      return tripmA;        
-    }
+    inline void clearRepeats() { transmitRepeats=0; }
+#ifndef ARDUINO_ARCH_ESP32
+    inline void clearResets() { sentResetsSincePacket=0; }
+    inline byte getResets() { return sentResetsSincePacket; }
+#else
+  // extrafudge is added when we know that the resets will first come extrafudge  packets in the future
+    inline void clearResets(byte extrafudge=0) {
+      if ((isMainTrack ? rmtMainChannel : rmtProgChannel) == NULL) return;
+      resetPacketBase = isMainTrack ? rmtMainChannel->packetCount() : rmtProgChannel->packetCount();
+      resetPacketBase += extrafudge;
+    };
+    inline byte getResets() {
+      if ((isMainTrack ? rmtMainChannel : rmtProgChannel) == NULL) return 0;
+      uint32_t packetcount = isMainTrack ?
+	rmtMainChannel->packetCount() : rmtProgChannel->packetCount();
+      uint32_t count = packetcount - resetPacketBase; // Beware of unsigned interger arithmetic.
+      if (count > UINT32_MAX/2)                       // we are in the extrafudge area
+	return 0;
+      if (count > 255)                                // cap to 255
+	return 255;
+      return count;                                   // all special cases handled above
+    };
+#endif
     void schedulePacket(const byte buffer[], byte byteCount, byte repeats);
-    volatile bool packetPending;
-    volatile byte sentResetsSincePacket;
-    volatile bool autoPowerOff=false;
-    void setAckBaseline();  //prog track only
-    void setAckPending();  //prog track only
-    byte getAck();               //prog track only 0=NACK, 1=ACK 2=keep waiting
-    static bool progTrackSyncMain;  // true when prog track is a siding switched to main
-    static bool progTrackBoosted;   // true when prog track is not current limited
-    inline void doAutoPowerOff() {
-	if (autoPowerOff) {
-	    setPowerMode(POWERMODE::OFF);
-	    autoPowerOff=false;
-	}
-    };
-    inline bool canMeasureCurrent() {
-      return motorDriver->canMeasureCurrent();
-    };
-    inline void setAckLimit(int mA) {
-	ackLimitmA = mA;
-    }
-    inline void setMinAckPulseDuration(unsigned int i) {
-	minAckPulseDuration = i;
-    }
-    inline void setMaxAckPulseDuration(unsigned int i) {
-	maxAckPulseDuration = i;
-    }
-
-  private:
+    bool isReminderWindowOpen();
+    void promotePendingPacket();
+    static bool setRailcom(bool on, bool debug);
+    static bool isRailcom() {return railcomActive;}
     
-// For each state of the wave  nextState=stateTransform[currentState] 
-   static const WAVE_STATE stateTransform[6];
-
-// For each state of the wave, signal pin is HIGH or LOW   
-   static const bool signalTransform[6];
-  
+  private:
+#ifndef ARDUINO_ARCH_ESP32
+    volatile bool packetPending;
+    volatile bool reminderWindowOpen;
+    volatile byte sentResetsSincePacket;
+#else
+    volatile uint32_t resetPacketBase;
+#endif
     static void interruptHandler();
     void interrupt2();
-    void checkAck();
     
     bool isMainTrack;
-    MotorDriver*  motorDriver;
     // Transmission controller
     byte transmitPacket[MAX_PACKET_SIZE+1]; // +1 for checksum
     byte transmitLength;
@@ -134,38 +112,12 @@ class DCCWaveform {
     byte pendingPacket[MAX_PACKET_SIZE+1]; // +1 for checksum
     byte pendingLength;
     byte pendingRepeats;
-    int  lastCurrent;
-    static int progTripValue;
-    int maxmA;
-    int tripmA;
+    static volatile bool railcomActive;     // switched on by user
+    static volatile bool railcomDebug;     // switched on by user
     
-    // current sampling
-    POWERMODE powerMode;
-    unsigned long lastSampleTaken;
-    unsigned int sampleDelay;
-    // Trip current for programming track, 250mA. Change only if you really
-    // need to be non-NMRA-compliant because of decoders that are not either.
-    static const int TRIP_CURRENT_PROG=250;
-    unsigned long power_sample_overload_wait = POWER_SAMPLE_OVERLOAD_WAIT;
-    unsigned int power_good_counter = 0;
-
-    // ACK management (Prog track only)  
-    volatile bool ackPending;
-    volatile bool ackDetected;
-    int  ackThreshold; 
-    int  ackLimitmA = 60;
-    int ackMaxCurrent;
-    unsigned long ackCheckStart; // millis
-    unsigned int ackCheckDuration; // millis       
-    
-    unsigned int ackPulseDuration;  // micros
-    unsigned long ackPulseStart; // micros
-
-    unsigned int minAckPulseDuration = 4000; // micros
-    unsigned int maxAckPulseDuration = 8500; // micros
-
-    volatile static uint8_t numAckGaps;
-    volatile static uint8_t numAckSamples;
-    static uint8_t trailingEdgeCounter;
+#ifdef ARDUINO_ARCH_ESP32
+  static RMTChannel *rmtMainChannel;
+  static RMTChannel *rmtProgChannel;
+#endif
 };
 #endif

DIAG.h

@@ -1,7 +1,9 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
+ *  © 2021 Fred Decker
+ *  © 2020 Chris Harlow
+ *  All rights reserved.
  *  
- *  This file is part of Asbelos DCC API
+ *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
@@ -22,4 +24,5 @@
 #include "StringFormatter.h"
 #define DIAG  StringFormatter::diag
 #define LCD   StringFormatter::lcd
+#define SCREEN  StringFormatter::lcd2
 #endif

Display.cpp

@@ -0,0 +1,220 @@
+/*
+ *  © 2021, Chris Harlow, Neil McKechnie. All rights reserved.
+ *
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// CAUTION: the device dependent parts of this class are created in the .ini
+// using LCD_Implementation.h
+
+/* The strategy for drawing the screen is as follows.
+ *  1) There are up to eight rows of text to be displayed.
+ *  2) Blank rows of text are ignored.
+ *  3) If there are more non-blank rows than screen lines,
+ *     then all of the rows are displayed, with the rest of the
+ *     screen being blank.
+ *  4) If there are fewer non-blank rows than screen lines,
+ *     then a scrolling strategy is adopted so that, on each screen
+ *     refresh, a different subset of the rows is presented.
+ *  5) On each entry into loop2(), a single operation is sent to the 
+ *     screen; this may be a position command or a character for
+ *     display.  This spreads the onerous work of updating the screen
+ *     and ensures that other loop() functions in the application are
+ *     not held up significantly.  The exception to this is when 
+ *     the loop2() function is called with force=true, where 
+ *     a screen update is executed to completion.  This is normally
+ *     only done during start-up.
+ *  The scroll mode is selected by defining SCROLLMODE as 0, 1 or 2
+ *  in the config.h.
+ *  #define SCROLLMODE 0 is scroll continuous (fill screen if poss),
+ *  #define SCROLLMODE 1 is by page (alternate between pages),
+ *  #define SCROLLMODE 2 is by row (move up 1 row at a time).
+
+ */
+
+#include "Display.h"
+
+// Constructor - allocates device driver.
+Display::Display(DisplayDevice *deviceDriver) {
+  _deviceDriver = deviceDriver;
+  // Get device dimensions in characters (e.g. 16x2).
+  numScreenColumns = _deviceDriver->getNumCols();
+  numScreenRows = _deviceDriver->getNumRows();
+  for (uint8_t row = 0; row < MAX_CHARACTER_ROWS; row++) 
+    rowBuffer[row][0] = '\0';
+  
+  addDisplay(0);  // Add this display as display number 0
+};
+
+void Display::begin() {
+  _deviceDriver->begin();
+  _deviceDriver->clearNative();
+}
+
+void Display::_clear() {
+  _deviceDriver->clearNative();
+  for (uint8_t row = 0; row < MAX_CHARACTER_ROWS; row++) 
+    rowBuffer[row][0] = '\0';
+}
+
+void Display::_setRow(uint8_t line) {
+  hotRow = line;
+  hotCol = 0;
+  rowBuffer[hotRow][0] = '\0';  // Clear existing text
+}
+
+size_t Display::_write(uint8_t b) {
+  if (hotRow >= MAX_CHARACTER_ROWS || hotCol >= MAX_CHARACTER_COLS) return -1;
+  rowBuffer[hotRow][hotCol] = b;
+  hotCol++;
+  rowBuffer[hotRow][hotCol] = '\0';
+  return 1;
+}
+
+// Refresh screen completely (will block until complete). Used
+// during start-up.
+void Display::_refresh() {
+  loop2(true);
+}
+
+// On normal loop entries, loop will only make one output request on each
+// entry, to avoid blocking while waiting for the I2C.
+void Display::_displayLoop() {
+  // If output device is busy, don't do anything on this loop
+  // This avoids blocking while waiting for the device to complete.
+  if (!_deviceDriver->isBusy()) loop2(false);
+}
+
+Display *Display::loop2(bool force) {
+  unsigned long currentMillis = millis();
+
+  if (!force) {
+    // See if we're in the time between updates
+    if ((currentMillis - lastScrollTime) < DISPLAY_SCROLL_TIME)
+      return NULL;
+  } else {
+    // force full screen update from the beginning.
+    rowFirst = 0;
+    rowCurrent = 0;
+    bufferPointer = 0;
+    noMoreRowsToDisplay = false;
+    slot = 0;
+  }
+
+  do {
+    if (bufferPointer == 0) {
+      // Search for non-blank row
+      while (!noMoreRowsToDisplay) {
+        if (!isCurrentRowBlank()) break;
+        moveToNextRow();
+        if (rowCurrent == rowFirst) noMoreRowsToDisplay = true;  
+      }
+
+      if (noMoreRowsToDisplay) {
+        // No non-blank lines left, so draw blank line
+        buffer[0] = '\0';
+      } else {
+        // Non-blank line found, so copy it (including terminator)
+        for (uint8_t i = 0; i <= MAX_CHARACTER_COLS; i++)
+          buffer[i] = rowBuffer[rowCurrent][i];
+      }
+      _deviceDriver->setRowNative(slot);  // Set position for display
+      charIndex = 0;
+      bufferPointer = &buffer[0];
+    } else {
+      // Write next character, or a space to erase current position.
+      char ch = *bufferPointer;
+      if (ch) {
+        _deviceDriver->writeNative(ch);
+        bufferPointer++;
+      } else {
+        _deviceDriver->writeNative(' ');
+      }
+
+      if (++charIndex >= MAX_CHARACTER_COLS) {
+        // Screen slot completed, move to next nonblank row
+        bufferPointer = 0;
+        for (;;) {
+          moveToNextRow();
+          if (rowCurrent == rowFirst) {
+            noMoreRowsToDisplay = true;
+            break;
+          }  
+          if (!isCurrentRowBlank()) break;
+        }
+        // Move to next screen slot, if available
+        slot++;
+        if (slot >= numScreenRows) {
+          // Last slot on screen written, so get ready for next screen update.
+#if SCROLLMODE==0
+          // Scrollmode 0 scrolls continuously.  If the rows fit on the screen,
+          // then restart at row 0, but otherwise continue with the row
+          // after the last one displayed.
+          if (countNonBlankRows() <= numScreenRows)
+            rowCurrent = 0;
+          rowFirst = rowCurrent;
+#elif SCROLLMODE==1
+          // Scrollmode 1 scrolls by page, so if the last page has just completed then
+          // next time restart with row 0.
+          if (noMoreRowsToDisplay) 
+            rowFirst = rowCurrent = 0;
+#else
+          // Scrollmode 2 scrolls by row.  If the rows don't fit on the screen,
+          // then start one row further on next time.  If they do fit, then 
+          // show them in order and start next page at row 0.
+          if (countNonBlankRows() <= numScreenRows) {
+            rowFirst = rowCurrent = 0;
+          } else {
+            // Find first non-blank row after the previous first row
+            rowCurrent = rowFirst;
+            do {
+              moveToNextRow();
+            } while (isCurrentRowBlank());
+            rowFirst = rowCurrent;
+          }
+#endif
+          noMoreRowsToDisplay = false;
+          slot = 0;
+          _deviceDriver->setRowNative(slot);  // Set position for display
+          lastScrollTime = currentMillis;
+          return NULL;
+        }
+      }
+    }
+  } while (force);
+
+  return NULL;
+}
+
+bool Display::isCurrentRowBlank() {
+  return (rowBuffer[rowCurrent][0] == '\0');
+}
+
+void Display::moveToNextRow() {
+  // Skip blank rows
+  if (++rowCurrent >= MAX_CHARACTER_ROWS) 
+      rowCurrent = 0;
+}
+
+uint8_t Display::countNonBlankRows() {
+  uint8_t count = 0;
+  for (uint8_t rowNumber=0; rowNumber<MAX_CHARACTER_ROWS; rowNumber++) {
+    if (rowBuffer[rowNumber][0] != '\0')
+      count++;
+  }
+  return count;
+}
+  

Display.h

@@ -0,0 +1,79 @@
+/*
+ *  © 2021, Chris Harlow, Neil McKechnie. All rights reserved.
+ *
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#ifndef Display_h
+#define Display_h
+#include <Arduino.h>
+#include "defines.h"
+#include "DisplayInterface.h"
+
+// Allow maximum message length to be overridden from config.h
+#if !defined(MAX_MSG_SIZE)
+#define MAX_MSG_SIZE 20 
+#endif
+
+// Set default scroll mode (overridable in config.h)
+#if !defined(SCROLLMODE) 
+#define SCROLLMODE 1
+#endif
+
+// This class is created in Display_Implementation.h
+
+class Display : public DisplayInterface {
+public:
+  Display(DisplayDevice *deviceDriver);
+#if !defined (MAX_CHARACTER_ROWS)
+  static const int MAX_CHARACTER_ROWS = 8;
+#endif
+  static const int MAX_CHARACTER_COLS = MAX_MSG_SIZE;
+  static const long DISPLAY_SCROLL_TIME = 3000;  // 3 seconds
+
+private:
+  DisplayDevice *_deviceDriver;
+
+  unsigned long lastScrollTime = 0;
+  uint8_t hotRow = 0;
+  uint8_t hotCol = 0;
+  uint8_t slot = 0;
+  uint8_t rowFirst = 0;
+  uint8_t rowCurrent = 0;
+  uint8_t charIndex = 0;
+  char buffer[MAX_CHARACTER_COLS + 1];
+  char* bufferPointer = 0;
+  bool noMoreRowsToDisplay = false;
+  uint16_t numScreenRows;
+  uint16_t numScreenColumns = MAX_CHARACTER_COLS;
+
+  char rowBuffer[MAX_CHARACTER_ROWS][MAX_CHARACTER_COLS+1];
+
+public:
+  void begin() override;  
+  void _clear() override;
+  void _setRow(uint8_t line) override;
+  size_t _write(uint8_t b) override;
+  void _refresh() override;
+  void _displayLoop() override;
+  Display *loop2(bool force);
+  bool findNonBlankRow();
+  bool isCurrentRowBlank();
+  void moveToNextRow();
+  uint8_t countNonBlankRows();
+
+};
+
+#endif

DisplayInterface.cpp

@@ -1,5 +1,7 @@
 /*
- *  © 2021, Chris Harlow, Neil McKechnie. All rights reserved.
+ *  © 2021 Neil McKechnie
+ *  © 2021 Chris Harlow
+ *  All rights reserved.
  *
  *  This file is part of CommandStation-EX
  *
@@ -19,4 +21,7 @@
 
 #include "DisplayInterface.h"
 
-DisplayInterface *DisplayInterface::lcdDisplay = 0;
+// Install null display driver initially - will be replaced if required.
+DisplayInterface *DisplayInterface::_displayHandler = new DisplayInterface();
+
+uint8_t DisplayInterface::_selectedDisplayNo = 255;

DisplayInterface.h

@@ -1,5 +1,7 @@
 /*
- *  © 2021, Chris Harlow, Neil McKechnie. All rights reserved.
+ *  © 2021 Neil McKechnie
+ *  © 2021 Chris Harlow
+ *  All rights reserved.
  *
  *  This file is part of CommandStation-EX
  *
@@ -23,13 +25,75 @@
 
 // Definition of base class for displays.  The base class does nothing.
 class DisplayInterface : public Print {
-public:
-  virtual DisplayInterface* loop2(bool force) { (void)force; return NULL; };
-  virtual void setRow(byte line) { (void)line; };
-  virtual void clear() {};
-  virtual size_t write(uint8_t c) { (void)c; return 0; };
+protected:
+  static DisplayInterface *_displayHandler;
+  static uint8_t _selectedDisplayNo;  // Nothing selected.
+  DisplayInterface *_nextHandler = NULL;
+  uint8_t _displayNo = 0;
 
-  static DisplayInterface *lcdDisplay;
+public:
+  // Add display object to list of displays
+  void addDisplay(uint8_t displayNo) {
+    _nextHandler = _displayHandler;
+    _displayHandler = this;
+    _displayNo = displayNo;
+  }
+  static DisplayInterface *getDisplayHandler() {
+    return _displayHandler;
+  }
+  uint8_t getDisplayNo() {
+    return _displayNo;
+  }
+
+  // The next functions are to provide compatibility with calls to the LCD function
+  // which does not specify a display number.  These always apply to display '0'.
+  static void refresh() { refresh(0); };
+  static void setRow(uint8_t line) { setRow(0, line); };
+  static void clear() { clear(0); };
+
+  // Additional functions to support multiple displays.  These perform a
+  // multicast to all displays that match the selected displayNo.
+  // Display number zero is the default one.
+  static void setRow(uint8_t displayNo, uint8_t line) { 
+    _selectedDisplayNo = displayNo;
+    for (DisplayInterface *p = _displayHandler; p!=0; p=p->_nextHandler) { 
+      if (displayNo == p->_displayNo) p->_setRow(line);
+    }
+  }
+  size_t write (uint8_t c) override {
+    for (DisplayInterface *p = _displayHandler; p!=0; p=p->_nextHandler) 
+      if (_selectedDisplayNo == p->_displayNo) p->_write(c);
+    return _displayHandler ? 1 : 0;
+  }
+  static void clear(uint8_t displayNo) { 
+    for (DisplayInterface *p = _displayHandler; p!=0; p=p->_nextHandler) 
+      if (displayNo == p->_displayNo) p->_clear();
+  }
+  static void refresh(uint8_t displayNo) {
+    for (DisplayInterface *p = _displayHandler; p!=0; p=p->_nextHandler)
+      if (displayNo == p->_displayNo) p->_refresh();
+  }
+  static void loop() {
+    for (DisplayInterface *p = _displayHandler; p!=0; p=p->_nextHandler) 
+      p->_displayLoop();
+  };
+  // The following are overridden within the specific device class
+  virtual void begin() {};
+  virtual size_t _write(uint8_t c) { (void)c; return 0; };
+  virtual void _setRow(uint8_t line) { (void)line; }
+  virtual void _clear() {}
+  virtual void _refresh() {}
+  virtual void _displayLoop() {}
 };
 
-#endif
+class DisplayDevice {
+public:
+  virtual bool begin() { return true; }
+  virtual void clearNative() = 0;
+  virtual void setRowNative(uint8_t line) = 0;
+  virtual size_t writeNative(uint8_t c) = 0;
+  virtual bool isBusy() = 0;
+  virtual uint16_t getNumRows() = 0;
+  virtual uint16_t getNumCols() = 0;
+};
+#endif

Display_Implementation.h

@@ -27,27 +27,36 @@
 
 #ifndef LCD_Implementation_h
 #define LCD_Implementation_h
-#include "LCDDisplay.h"
+#include "DisplayInterface.h"
 #include "SSD1306Ascii.h"
 #include "LiquidCrystal_I2C.h"
   
 
-// Implement the LCDDisplay shim class as a singleton.
-// The DisplayInterface class implements a displayy handler with no code (null device);
-// The LCDDisplay class sub-classes DisplayInterface to provide the common display code;
-// Then LCDDisplay class is subclassed to the specific device type classes:
+// Implement the Display shim class as a singleton.
+// The DisplayInterface class implements a display handler with no code (null device);
+// The Display class sub-classes DisplayInterface to provide the common display code;
+// Then Display class talks to the specific device type classes:
 //    SSD1306AsciiWire for I2C OLED driver with SSD1306 or SH1106 controllers;
 //    LiquidCrystal_I2C for I2C LCD driver for HD44780 with PCF8574 'backpack'.
 
 #if defined(OLED_DRIVER)
-  #define CONDITIONAL_LCD_START for (DisplayInterface * dummy=new SSD1306AsciiWire(OLED_DRIVER);dummy!=NULL; dummy=dummy->loop2(true))
+  #define DISPLAY_START(xxx) { \
+    DisplayInterface *t = new Display(new SSD1306AsciiWire(OLED_DRIVER)); \
+    t->begin(); \
+    xxx; \
+    t->refresh(); \
+  } 
   
 #elif defined(LCD_DRIVER)
-  #define CONDITIONAL_LCD_START for (DisplayInterface * dummy=new LiquidCrystal_I2C(LCD_DRIVER);dummy!=NULL; dummy=dummy->loop2(true))
-
+  #define DISPLAY_START(xxx) { \
+    DisplayInterface *t = new Display(new LiquidCrystal_I2C(LCD_DRIVER)); \
+    t->begin(); \
+    xxx;  \
+    t->refresh();}
 #else
-  // Create null display handler just in case someone calls lcdDisplay->something without checking if lcdDisplay is NULL!
-  #define CONDITIONAL_LCD_START { new DisplayInterface(); }
-#endif
+  #define DISPLAY_START(xxx) { \
+  xxx; \
+  }
 
+#endif
 #endif // LCD_Implementation_h

EEStore.cpp

@@ -1,9 +1,12 @@
 /*
+ *  © 2021 Neil McKechnie
+ *  © 2021 Fred Decker
+ *  © 2020-2022 Harald Barth
+ *  © 2020-2021 Chris Harlow
  *  © 2013-2016 Gregg E. Berman
- *  © 2020, Chris Harlow. All rights reserved.
- *  © 2020, Harald Barth.
+ *  All rights reserved.
  *
- *  This file is part of Asbelos DCC API
+ *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
@@ -18,6 +21,9 @@
  *  You should have received a copy of the GNU General Public License
  *  along with CommandStation.  If not, see <https://www.gnu.org/licenses/>.
  */
+
+#include "defines.h"
+#ifndef DISABLE_EEPROM
 #include "EEStore.h"
 
 #include "DIAG.h"
@@ -25,12 +31,12 @@
 #include "Sensors.h"
 #include "Turnouts.h"
 
-#if defined(ARDUINO_ARCH_SAMD)
+#if defined(ARDUINO_ARCH_SAMC)
 ExternalEEPROM EEPROM;
 #endif
 
 void EEStore::init() {
-#if defined(ARDUINO_ARCH_SAMD)
+#if defined(ARDUINO_ARCH_SAMC)
   EEPROM.begin(0x50);  // Address for Microchip 24-series EEPROM with all three
                        // A pins grounded (0b1010000 = 0x50)
 #endif
@@ -43,7 +49,7 @@ void EEStore::init() {
   if (strncmp(eeStore->data.id, EESTORE_ID, sizeof(EESTORE_ID)) != 0) {  
     // if not, create blank eeStore structure (no
     // turnouts, no sensors) and save it back to EEPROM  
-    strncpy(eeStore->data.id, EESTORE_ID, sizeof(EESTORE_ID));  
+    strncpy(eeStore->data.id, EESTORE_ID, sizeof(EESTORE_ID)+0);  
     eeStore->data.nTurnouts = 0;
     eeStore->data.nSensors = 0;
     eeStore->data.nOutputs = 0;
@@ -92,7 +98,7 @@ int EEStore::pointer() { return (eeAddress); }
 ///////////////////////////////////////////////////////////////////////////////
 
 void EEStore::dump(int num) {
-  byte b;
+  byte b = 0;
   DIAG(F("Addr  0x  char"));
   for (int n = 0; n < num; n++) {
     EEPROM.get(n, b);
@@ -103,3 +109,4 @@ void EEStore::dump(int num) {
 
 EEStore *EEStore::eeStore = NULL;
 int EEStore::eeAddress = 0;
+#endif

EEStore.h

@@ -1,6 +1,9 @@
 /*
- *  (c) 2020 Chris Harlow. All rights reserved.
- *  (c) 2020 Harald Barth. All rights reserved.
+ *  © 2021 Neil McKechnie
+ *  © 2021 Fred Decker
+ *  © 2020-2021 Harald Barth
+ *  © 2020 Chris Harlow
+ *  All rights reserved.
  *  
  *  This file is part of CommandStation-EX
  *
@@ -17,12 +20,13 @@
  *  You should have received a copy of the GNU General Public License
  *  along with CommandStation.  If not, see <https://www.gnu.org/licenses/>.
  */
+#ifndef DISABLE_EEPROM
 #ifndef EEStore_h
 #define EEStore_h
 
 #include <Arduino.h>
 
-#if defined(ARDUINO_ARCH_SAMD)
+#if defined(ARDUINO_ARCH_SAMC)
 #include <SparkFun_External_EEPROM.h>
 extern ExternalEEPROM EEPROM;
 #else
@@ -52,3 +56,4 @@ struct EEStore{
 };
 
 #endif
+#endif // DISABLE_EEPROM

EXRAIL.h

@@ -0,0 +1,43 @@
+/*
+ *  © 2021 Fred Decker
+ *  All rights reserved.
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef EXRAIL_H
+#define EXRAIL_H
+
+#if defined(EXRAIL_ACTIVE)
+ #include "EXRAIL2.h"
+
+  class RMFT {
+    public:
+      static void inline begin() {RMFT2::begin();}
+      static void inline loop() {RMFT2::loop();}
+  };
+
+  #include "EXRAILMacros.h"
+  
+#else 
+  // Dummy RMFT 
+  class RMFT {
+    public:
+      static void inline begin() {}
+      static void inline loop() {}
+  };
+#endif
+#endif

EXRAIL2.h

@@ -0,0 +1,319 @@
+/*
+ *  © 2021 Neil McKechnie
+ *  © 2020-2022 Chris Harlow
+ *  © 2022-2023 Colin Murdoch
+ *  © 2023 Harald Barth
+ *  © 2025 Morten Nielsen
+ *  All rights reserved.
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#ifndef EXRAIL2_H
+#define EXRAIL2_H
+#include "FSH.h"
+#include "IODevice.h"
+#include "Turnouts.h"
+#include "Turntables.h"
+   
+// The following are the operation codes (or instructions) for a kind of virtual machine.
+// Each instruction is normally 3 bytes long with an operation code followed by a parameter.
+// In cases where more than one parameter is required, the first parameter is followed by one  
+// or more OPCODE_PAD instructions with the subsequent parameters. This wastes a byte but makes 
+// searching easier as a parameter can never be confused with an opcode. 
+// 
+enum OPCODE : byte {OPCODE_THROW,OPCODE_CLOSE,OPCODE_TOGGLE_TURNOUT,
+             OPCODE_FWD,OPCODE_REV,OPCODE_SPEED,OPCODE_INVERT_DIRECTION,
+             OPCODE_RESERVE,OPCODE_FREE,
+             OPCODE_AT,OPCODE_AFTER,
+             OPCODE_AFTEROVERLOAD,OPCODE_AUTOSTART,
+             OPCODE_ATGTE,OPCODE_ATLT,
+             OPCODE_ATTIMEOUT1,OPCODE_ATTIMEOUT2,
+             OPCODE_LATCH,OPCODE_UNLATCH,OPCODE_SET,OPCODE_RESET,
+             OPCODE_BLINK,
+             OPCODE_ENDIF,OPCODE_ELSE,
+             OPCODE_DELAY,OPCODE_DELAYMINS,OPCODE_DELAYMS,OPCODE_RANDWAIT,
+             OPCODE_FON,OPCODE_FOFF,OPCODE_XFON,OPCODE_XFOFF,
+             OPCODE_FTOGGLE,OPCODE_XFTOGGLE,OPCODE_XFWD,OPCODE_XREV,
+             OPCODE_RED,OPCODE_GREEN,OPCODE_AMBER,OPCODE_DRIVE,
+             OPCODE_SERVO,OPCODE_SIGNAL,OPCODE_TURNOUT,OPCODE_WAITFOR,
+             OPCODE_PAD,OPCODE_FOLLOW,OPCODE_CALL,OPCODE_RETURN,
+#ifndef DISABLE_PROG
+             OPCODE_JOIN,OPCODE_UNJOIN,OPCODE_READ_LOCO1,OPCODE_READ_LOCO2,
+#endif
+             OPCODE_POM,
+             OPCODE_START,OPCODE_SETLOCO,OPCODE_SETFREQ,OPCODE_SENDLOCO,OPCODE_FORGET,
+             OPCODE_PAUSE, OPCODE_RESUME,OPCODE_POWEROFF,OPCODE_POWERON,
+             OPCODE_ONCLOSE, OPCODE_ONTHROW, OPCODE_SERVOTURNOUT, OPCODE_PINTURNOUT,
+             OPCODE_PRINT,OPCODE_DCCACTIVATE,OPCODE_ASPECT,
+             OPCODE_ONACTIVATE,OPCODE_ONDEACTIVATE,
+             OPCODE_ROSTER,OPCODE_KILLALL,
+             OPCODE_ROUTE,OPCODE_AUTOMATION,OPCODE_SEQUENCE,
+             OPCODE_ENDTASK,OPCODE_ENDEXRAIL,
+             OPCODE_SET_TRACK,OPCODE_SET_POWER,
+             OPCODE_ONRED,OPCODE_ONAMBER,OPCODE_ONGREEN,
+             OPCODE_ONCHANGE,
+             OPCODE_ONCLOCKTIME,
+             OPCODE_ONTIME,
+             OPCODE_TTADDPOSITION,OPCODE_DCCTURNTABLE,OPCODE_EXTTTURNTABLE,
+             OPCODE_ONROTATE,OPCODE_ROTATE,OPCODE_WAITFORTT,
+             OPCODE_LCC,OPCODE_LCCX,OPCODE_ONLCC,
+             OPCODE_ACON, OPCODE_ACOF, 
+             OPCODE_ONACON, OPCODE_ONACOF, 
+             OPCODE_ONOVERLOAD,
+	     OPCODE_ONRAILSYNCON,OPCODE_ONRAILSYNCOFF,
+             OPCODE_ROUTE_ACTIVE,OPCODE_ROUTE_INACTIVE,OPCODE_ROUTE_HIDDEN,
+             OPCODE_ROUTE_DISABLED,
+             OPCODE_STASH,OPCODE_CLEAR_STASH,OPCODE_CLEAR_ALL_STASH,OPCODE_PICKUP_STASH,
+             OPCODE_ONBUTTON,OPCODE_ONSENSOR,             
+             OPCODE_NEOPIXEL,
+             // OPcodes below this point are skip-nesting IF operations
+             // placed here so that they may be skipped as a group
+             // see skipIfBlock()
+            IF_TYPE_OPCODES, // do not move this... 
+             OPCODE_IFRED,OPCODE_IFAMBER,OPCODE_IFGREEN,
+             OPCODE_IFGTE,OPCODE_IFLT,
+             OPCODE_IFTIMEOUT,
+             OPCODE_IF,OPCODE_IFNOT,
+             OPCODE_IFRANDOM,OPCODE_IFRESERVE,
+             OPCODE_IFCLOSED,OPCODE_IFTHROWN,
+             OPCODE_IFRE,
+             OPCODE_IFLOCO,
+             OPCODE_IFTTPOSITION
+             };
+
+// Ensure thrunge_lcd is put last as there may be more than one display, 
+// sequentially numbered from thrunge_lcd.
+enum thrunger: byte {
+  thrunge_print, thrunge_broadcast, thrunge_withrottle,
+  thrunge_serial,thrunge_parse,
+  thrunge_serial1, thrunge_serial2, thrunge_serial3,
+  thrunge_serial4, thrunge_serial5, thrunge_serial6,
+  thrunge_lcn,thrunge_message,
+  thrunge_lcd,  // Must be last!!
+  };
+
+
+enum BlinkState: byte {
+    not_blink_task, 
+    blink_low, // blink task running with pin LOW
+    blink_high, // blink task running with pin high 
+    at_timeout  // ATTIMEOUT timed out flag
+    }; 
+enum SignalType {
+       sigtypeVIRTUAL,
+       sigtypeSIGNAL, 
+       sigtypeSIGNALH, 
+       sigtypeDCC,
+       sigtypeDCCX,
+       sigtypeSERVO,
+       sigtypeNEOPIXEL,
+       sigtypeContinuation,  // neopixels require a second line
+       sigtypeNoMoreSignals
+       }; 
+
+  struct SIGNAL_DEFINITION {
+       SignalType type;
+       VPIN id;  
+       VPIN  redpin,amberpin,greenpin; 
+  };
+
+  // Flag bits for compile time features.
+  static const byte FEATURE_SIGNAL= 0x80;
+  static const byte FEATURE_LCC   = 0x40;
+  static const byte FEATURE_ROSTER= 0x20;
+  static const byte FEATURE_ROUTESTATE= 0x10;
+  static const byte FEATURE_STASH = 0x08;
+  static const byte FEATURE_BLINK = 0x04;
+  static const byte FEATURE_SENSOR = 0x02;
+  
+ 
+  // Flag bits for status of hardware and TPL
+  static const byte SECTION_FLAG = 0x80;
+  static const byte LATCH_FLAG   = 0x40;
+  static const byte TASK_FLAG    = 0x20;
+  static const byte SPARE_FLAG   = 0x10;
+  static const byte SIGNAL_MASK  = 0x0C;
+  static const byte SIGNAL_RED   = 0x08;
+  static const byte SIGNAL_AMBER = 0x0C;
+  static const byte SIGNAL_GREEN = 0x04;
+
+  static const byte  MAX_STACK_DEPTH=4;
+ 
+   static const short MAX_FLAGS=256;
+  #define FLAGOVERFLOW(x) x>=MAX_FLAGS
+
+class LookList {
+  public: 
+    LookList(int16_t size);
+    void chain(LookList* chainTo);
+    void add(int16_t lookup, int16_t result);
+    int16_t find(int16_t value); // finds result value
+    int16_t findPosition(int16_t value); // finds index 
+    int16_t size();
+    void stream(Print * _stream); 
+    void handleEvent(const FSH* reason,int16_t id);
+
+  private:
+     int16_t m_size;
+     int16_t m_loaded;
+     int16_t * m_lookupArray;
+     int16_t * m_resultArray;
+     LookList* m_chain;     
+};
+
+ class RMFT2 {
+   public:
+    static void begin();
+    static void loop();
+    RMFT2(int progCounter);
+    RMFT2(int route, uint16_t cab);
+    ~RMFT2();
+    static void readLocoCallback(int16_t cv);
+    static void createNewTask(int route, uint16_t cab);
+    static void turnoutEvent(int16_t id, bool closed);  
+    static void activateEvent(int16_t addr, bool active);
+    static void changeEvent(int16_t id, bool change);
+    static void clockEvent(int16_t clocktime, bool change);
+    static void rotateEvent(int16_t id, bool change);
+    static void powerEvent(int16_t track, bool overload);
+#ifdef BOOSTER_INPUT
+    static void railsyncEvent(bool on);
+#endif
+    static bool signalAspectEvent(int16_t address, byte aspect );    
+    // Throttle Info Access functions built by exrail macros 
+  static const byte rosterNameCount;
+  static const int16_t HIGHFLASH routeIdList[];
+  static const int16_t HIGHFLASH automationIdList[];
+  static const int16_t HIGHFLASH rosterIdList[];
+  static const FSH *  getRouteDescription(int16_t id);
+  static char   getRouteType(int16_t id);
+  static const FSH *  getTurnoutDescription(int16_t id);
+  static const FSH *  getRosterName(int16_t id);
+  static const FSH *  getRosterFunctions(int16_t id);
+  static const FSH *  getTurntableDescription(int16_t id);
+  static const FSH *  getTurntablePositionDescription(int16_t turntableId, uint8_t positionId);
+  static void startNonRecursiveTask(const FSH* reason, int16_t id,int pc);
+  static bool readSensor(uint16_t sensorId);
+  static bool isSignal(int16_t id,char rag);
+  static SIGNAL_DEFINITION getSignalSlot(int16_t slotno); 
+   
+private: 
+    static void ComandFilter(Print * stream, byte & opcode, byte & paramCount, int16_t p[]);
+    static bool parseSlash(Print * stream, byte & paramCount, int16_t p[]) ;
+    static void streamFlags(Print* stream);
+    static bool setFlag(VPIN id,byte onMask, byte OffMask=0);
+    static bool getFlag(VPIN id,byte mask); 
+    static int16_t progtrackLocoId;
+    static void doSignal(int16_t id,char rag); 
+    static void setTurnoutHiddenState(Turnout * t);
+    #ifndef IO_NO_HAL
+    static void setTurntableHiddenState(Turntable * tto);
+    #endif
+    static LookList* LookListLoader(OPCODE op1,
+                      OPCODE op2=OPCODE_ENDEXRAIL,OPCODE op3=OPCODE_ENDEXRAIL);
+    static uint16_t getOperand(int progCounter,byte n);
+    static void killBlinkOnVpin(VPIN pin,uint16_t count=1);
+    static RMFT2 * loopTask;
+    static RMFT2 * pausingTask;
+    void delayMe(long millisecs);
+    void driveLoco(byte speedo);
+    bool skipIfBlock();
+    bool readLoco();
+    void loop2();
+    void kill(const FSH * reason=NULL,int operand=0);          
+    void printMessage(uint16_t id);  // Built by RMFTMacros.h
+    void printMessage2(const FSH * msg);
+    void thrungeString(uint32_t strfar, thrunger mode, byte id=0);
+    uint16_t getOperand(byte n); 
+    
+   static bool diag;
+   static const  HIGHFLASH3  byte RouteCode[];
+   static const  HIGHFLASH  SIGNAL_DEFINITION SignalDefinitions[];
+   static byte flags[MAX_FLAGS];
+   static Print * LCCSerial;
+   static LookList * routeLookup;
+   static LookList * signalLookup;
+   static LookList * onThrowLookup;
+   static LookList * onCloseLookup;
+   static LookList * onActivateLookup;
+   static LookList * onDeactivateLookup;
+   static LookList * onRedLookup;
+   static LookList * onAmberLookup;
+   static LookList * onGreenLookup;
+   static LookList * onChangeLookup;
+   static LookList * onClockLookup;
+#ifndef IO_NO_HAL
+   static LookList * onRotateLookup;
+#endif
+   static LookList * onOverloadLookup;
+#ifdef BOOSTER_INPUT
+   static LookList * onRailSyncOnLookup;
+   static LookList * onRailSyncOffLookup;
+#endif
+   static const int countLCCLookup;
+   static int onLCCLookup[];
+   static const byte compileFeatures;
+   static void manageRouteState(int16_t id, byte state);
+   static void manageRouteCaption(int16_t id, const FSH* caption);
+   static byte * routeStateArray;
+   static const FSH ** routeCaptionArray;
+   static int16_t * stashArray;
+   static int16_t maxStashId;
+    
+  // Local variables - exist for each instance/task 
+    RMFT2 *next;   // loop chain 
+    int progCounter;    // Byte offset of next route opcode in ROUTES table
+    unsigned long delayStart; // Used by opcodes that must be recalled before completing
+    unsigned long  delayTime;
+    union {
+      unsigned long waitAfter; // Used by OPCODE_AFTER
+      unsigned long timeoutStart; // Used by OPCODE_ATTIMEOUT
+      VPIN blinkPin;  // Used by blink tasks 
+    };
+    byte  taskId;
+    BlinkState blinkState; // includes AT_TIMEOUT flag. 
+    uint16_t loco;
+    bool forward;
+    bool invert;
+    byte speedo;
+    int onEventStartPosition;
+    byte stackDepth;
+    int callStack[MAX_STACK_DEPTH];
+};
+
+#define GET_OPCODE GETHIGHFLASH(RMFT2::RouteCode,progCounter)
+#define SKIPOP progCounter+=3
+
+// IO_I2CDFPlayer commands and values
+enum  : uint8_t{
+    DF_PLAY          = 0x0F,
+    DF_VOL           = 0x06,
+    DF_FOLDER        = 0x2B, // Not a DFPlayer command, used to set folder nr where audio file is
+    DF_REPEATPLAY    = 0x08,
+    DF_STOPPLAY      = 0x16,
+    DF_EQ            = 0x07, // Set equaliser, require parameter NORMAL, POP, ROCK, JAZZ, CLASSIC or BASS
+    DF_RESET         = 0x0C,
+    DF_DACON         = 0x1A,
+    DF_SETAM         = 0x2A, // Set audio mixer 1 or 2 for this DFPLayer   
+    DF_NORMAL        = 0x00, // Equalizer parameters
+    DF_POP           = 0x01,
+    DF_ROCK          = 0x02,
+    DF_JAZZ          = 0x03,
+    DF_CLASSIC       = 0x04,
+    DF_BASS          = 0x05,
+  };
+
+#endif

EXRAIL2MacroReset.h

@@ -0,0 +1,378 @@
+/*
+ *  © 2020-2022 Chris Harlow. All rights reserved.
+ *  © 2022-2023 Colin Murdoch
+ *  © 2023 Harald Barth
+ *  © 2025 Morten Nielsen
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// This file cleans and resets the RMFT2 Macros.
+// It is used between passes to reduce complexity in RMFT2Macros.h
+// DO NOT add an include guard to this file.
+
+// Undefine all RMFT macros
+#undef ACTIVATE
+#undef ACTIVATEL
+#undef AFTER
+#undef AFTEROVERLOAD
+#undef ALIAS
+#undef AMBER
+#undef ANOUT
+#undef ASPECT
+#undef AT
+#undef ATGTE
+#undef ATLT
+#undef ATTIMEOUT
+#undef AUTOMATION 
+#undef AUTOSTART
+#undef BLINK
+#undef BROADCAST
+#undef CALL 
+#undef CLEAR_STASH
+#undef CLEAR_ALL_STASH
+#undef CLOSE 
+#undef CONFIGURE_SERVO
+#undef DCC_SIGNAL
+#undef DCCX_SIGNAL
+#undef DCC_TURNTABLE
+#undef DEACTIVATE
+#undef DEACTIVATEL
+#undef DELAY
+#undef DELAYMINS
+#undef DELAYRANDOM 
+#undef DONE
+#undef DRIVE
+#undef ELSE
+#undef ENDEXRAIL 
+#undef ENDIF  
+#undef ENDTASK
+#undef ESTOP
+#undef EXRAIL
+#undef EXTT_TURNTABLE
+#undef FADE
+#undef FOFF
+#undef FOLLOW 
+#undef FON 
+#undef FORGET
+#undef FTOGGLE
+#undef FREE 
+#undef FWD 
+#undef GREEN
+#undef HAL
+#undef HAL_IGNORE_DEFAULTS
+#undef IF 
+#undef IFAMBER
+#undef IFCLOSED
+#undef IFGREEN
+#undef IFGTE
+#undef IFLOCO
+#undef IFLT
+#undef IFNOT
+#undef IFRANDOM 
+#undef IFRED
+#undef IFRESERVE
+#undef IFTHROWN
+#undef IFTIMEOUT
+#undef IFTTPOSITION
+#undef IFRE
+#undef INVERT_DIRECTION 
+#undef JMRI_SENSOR
+#undef JOIN 
+#undef KILLALL
+#undef LATCH 
+#undef LCD 
+#undef SCREEN
+#undef LCC 
+#undef LCCX 
+#undef LCN 
+#undef MOVETT
+#undef NEOPIXEL
+#undef NEOPIXEL_OFF
+#undef NEOPIXEL_SIGNAL
+#undef ACON
+#undef ACOF
+#undef ONACON
+#undef ONACOF
+#undef MESSAGE
+#undef ONACTIVATE
+#undef ONACTIVATEL
+#undef ONAMBER
+#undef ONDEACTIVATE
+#undef ONDEACTIVATEL 
+#undef ONCLOSE
+#undef ONLCC
+#undef ONTIME
+#undef ONCLOCKTIME
+#undef ONCLOCKMINS
+#undef ONOVERLOAD
+#undef ONRAILSYNCON
+#undef ONRAILSYNCOFF
+#undef ONGREEN
+#undef ONRED
+#undef ONROTATE
+#undef ONBUTTON
+#undef ONSENSOR
+#undef ONTHROW 
+#undef ONCHANGE
+#undef PARSE
+#undef PAUSE
+#undef PICKUP_STASH
+#undef PIN_TURNOUT 
+#undef PRINT
+#ifndef DISABLE_PROG
+#undef POM
+#endif
+#undef POWEROFF
+#undef POWERON
+#undef READ_LOCO 
+#undef RED 
+#undef RESERVE 
+#undef RESET 
+#undef RESUME 
+#undef RETURN 
+#undef REV
+#undef ROSTER
+#undef ROTATE
+#undef ROTATE_DCC
+#undef ROUTE
+#undef ROUTE_ACTIVE
+#undef ROUTE_INACTIVE
+#undef ROUTE_HIDDEN
+#undef ROUTE_DISABLED
+#undef ROUTE_CAPTION
+#undef SENDLOCO 
+#undef SEQUENCE 
+#undef SERIAL 
+#undef SERIAL1 
+#undef SERIAL2 
+#undef SERIAL3 
+#undef SERIAL4 
+#undef SERIAL5 
+#undef SERIAL6 
+#undef SERVO 
+#undef SERVO2 
+#undef SERVO_TURNOUT 
+#undef SERVO_SIGNAL
+#undef SET
+#undef SET_TRACK
+#undef SET_POWER
+#undef SETLOCO 
+#undef SETFREQ
+#undef SIGNAL 
+#undef SIGNALH 
+#undef SPEED 
+#undef START 
+#undef STASH
+#undef STEALTH
+#undef STEALTH_GLOBAL
+#undef STOP 
+#undef THROW
+#undef TOGGLE_TURNOUT
+#undef TT_ADDPOSITION
+#undef TURNOUT 
+#undef TURNOUTL
+#undef UNJOIN
+#undef UNLATCH 
+#undef VIRTUAL_SIGNAL
+#undef VIRTUAL_TURNOUT
+#undef WAITFOR
+#ifndef IO_NO_HAL
+#undef WAITFORTT
+#endif
+#undef WITHROTTLE
+#undef XFOFF
+#undef XFON
+#undef XFTOGGLE
+#undef XREV
+#undef XFWD
+
+#ifndef RMFT2_UNDEF_ONLY
+#define ACTIVATE(addr,subaddr)
+#define ACTIVATEL(addr)
+#define AFTER(sensor_id,timer...)
+#define AFTEROVERLOAD(track_id)
+#define ALIAS(name,value...)
+#define AMBER(signal_id)
+#define ANOUT(vpin,value,param1,param2)
+#define AT(sensor_id)
+#define ASPECT(address,value)
+#define ATGTE(sensor_id,value) 
+#define ATLT(sensor_id,value) 
+#define ATTIMEOUT(sensor_id,timeout_ms)
+#define AUTOMATION(id,description) 
+#define AUTOSTART
+#define BLINK(vpin,onDuty,offDuty)
+#define BROADCAST(msg)
+#define CALL(route)
+#define CLEAR_STASH(id)
+#define CLEAR_ALL_STASH
+#define CLOSE(id)
+#define CONFIGURE_SERVO(vpin,pos1,pos2,profile) 
+#define DCC_SIGNAL(id,add,subaddr)
+#define DCCX_SIGNAL(id,redAspect,amberAspect,greenAspect)
+#define DCC_TURNTABLE(id,home,description...)
+#define DEACTIVATE(addr,subaddr)
+#define DEACTIVATEL(addr)
+#define DELAY(mindelay)
+#define DELAYMINS(mindelay)
+#define DELAYRANDOM(mindelay,maxdelay) 
+#define DONE
+#define DRIVE(analogpin)
+#define ELSE
+#define ENDEXRAIL 
+#define ENDIF  
+#define ENDTASK
+#define ESTOP 
+#define EXRAIL
+#define EXTT_TURNTABLE(id,vpin,home,description...)
+#define FADE(pin,value,ms)
+#define FOFF(func)
+#define FOLLOW(route) 
+#define FON(func)
+#define FORGET
+#define FREE(blockid) 
+#define FTOGGLE(func)
+#define FWD(speed) 
+#define GREEN(signal_id)
+#define HAL(haltype,params...)
+#define HAL_IGNORE_DEFAULTS
+#define IF(sensor_id) 
+#define IFAMBER(signal_id)
+#define IFCLOSED(turnout_id) 
+#define IFGREEN(signal_id)
+#define IFGTE(sensor_id,value) 
+#define IFLOCO(loco_id)
+#define IFLT(sensor_id,value) 
+#define IFNOT(sensor_id)
+#define IFRANDOM(percent)
+#define IFRED(signal_id)
+#define IFTHROWN(turnout_id) 
+#define IFRESERVE(block)
+#define IFTIMEOUT
+#define IFTTPOSITION(turntable_id,position)
+#define IFRE(sensor_id,value)
+#define INVERT_DIRECTION 
+#define JMRI_SENSOR(vpin,count...)
+#define JOIN 
+#define KILLALL
+#define LATCH(sensor_id)
+#define LCC(eventid) 
+#define LCCX(senderid,eventid) 
+#define LCD(row,msg)
+#define SCREEN(display,row,msg)
+#define LCN(msg) 
+#define MESSAGE(msg)
+#define MOVETT(id,steps,activity)
+#define NEOPIXEL(id,r,g,b,count...)
+#define NEOPIXEL_SIGNAL(sigid,redcolour,ambercolour,greencolour)
+#define ACON(eventid)
+#define ACOF(eventid)
+#define ONACON(eventid)
+#define ONACOF(eventid)
+#define ONACTIVATE(addr,subaddr)
+#define ONACTIVATEL(linear)
+#define ONAMBER(signal_id) 
+#define ONTIME(value)
+#define ONCLOCKTIME(hours,mins)
+#define ONCLOCKMINS(mins)
+#define ONOVERLOAD(track_id)
+#define ONRAILSYNCON
+#define ONRAILSYNCOFF
+#define ONDEACTIVATE(addr,subaddr)
+#define ONDEACTIVATEL(linear) 
+#define ONCLOSE(turnout_id)
+#define ONLCC(sender,event)
+#define ONGREEN(signal_id) 
+#define ONRED(signal_id)
+#define ONROTATE(turntable_id)
+#define ONTHROW(turnout_id) 
+#define ONCHANGE(sensor_id)
+#define ONSENSOR(sensor_id)
+#define ONBUTTON(sensor_id)
+#define PAUSE
+#define PIN_TURNOUT(id,pin,description...) 
+#define PRINT(msg) 
+#define PARSE(msg)
+#define PICKUP_STASH(id)
+#ifndef DISABLE_PROG
+#define POM(cv,value)
+#endif
+#define POWEROFF
+#define POWERON
+#define READ_LOCO 
+#define RED(signal_id) 
+#define RESERVE(blockid) 
+#define RESET(pin,count...) 
+#define RESUME 
+#define RETURN 
+#define REV(speed) 
+#define ROTATE(turntable_id,position,activity)
+#define ROTATE_DCC(turntable_id,position)
+#define ROSTER(cab,name,funcmap...)
+#define ROUTE(id,description)
+#define ROUTE_ACTIVE(id)
+#define ROUTE_INACTIVE(id)
+#define ROUTE_HIDDEN(id)
+#define ROUTE_DISABLED(id)
+#define ROUTE_CAPTION(id,caption)
+#define SENDLOCO(cab,route) 
+#define SEQUENCE(id) 
+#define SERIAL(msg) 
+#define SERIAL1(msg) 
+#define SERIAL2(msg) 
+#define SERIAL3(msg) 
+#define SERIAL4(msg) 
+#define SERIAL5(msg) 
+#define SERIAL6(msg) 
+#define SERVO(id,position,profile) 
+#define SERVO2(id,position,duration) 
+#define SERVO_SIGNAL(vpin,redpos,amberpos,greenpos)
+#define SERVO_TURNOUT(id,pin,activeAngle,inactiveAngle,profile,description...) 
+#define SET(pin,count...) 
+#define SET_TRACK(track,mode)
+#define SET_POWER(track,onoff)
+#define SETLOCO(loco) 
+#define SETFREQ(freq)
+#define SIGNAL(redpin,amberpin,greenpin) 
+#define SIGNALH(redpin,amberpin,greenpin) 
+#define SPEED(speed) 
+#define START(route)
+#define STASH(id) 
+#define STEALTH(code...)
+#define STEALTH_GLOBAL(code...)
+#define STOP 
+#define THROW(id)
+#define TOGGLE_TURNOUT(id)
+#define TT_ADDPOSITION(turntable_id,position,value,angle,description...)
+#define TURNOUT(id,addr,subaddr,description...) 
+#define TURNOUTL(id,addr,description...) 
+#define UNJOIN 
+#define UNLATCH(sensor_id) 
+#define VIRTUAL_SIGNAL(id) 
+#define VIRTUAL_TURNOUT(id,description...) 
+#define WAITFOR(pin)
+#ifndef IO_NO_HAL
+#define WAITFORTT(turntable_id)
+#endif
+#define WITHROTTLE(msg)
+#define XFOFF(cab,func)
+#define XFON(cab,func)
+#define XFTOGGLE(cab,func)
+#define XFWD(cab,speed)
+#define XREV(cab,speed)
+
+#endif

EXRAIL2Parser.cpp

@@ -0,0 +1,365 @@
+/*
+ *  © 2021 Neil McKechnie
+ *  © 2021-2023 Harald Barth
+ *  © 2020-2023 Chris Harlow
+ *  © 2022-2023 Colin Murdoch
+ *  All rights reserved.
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// THIS file is an extension of the RMFT2 class 
+//  normally found in EXRAIL2.cpp
+
+#include <Arduino.h>
+#include "defines.h"
+#include "EXRAIL2.h"
+#include "DCC.h"
+#include "KeywordHasher.h"
+
+// This filter intercepts <> commands to do the following:
+// - Implement RMFT specific commands/diagnostics
+// - Reject/modify JMRI commands that would interfere with RMFT processing
+
+void RMFT2::ComandFilter(Print * stream, byte & opcode, byte & paramCount, int16_t p[]) {
+  (void)stream; // avoid compiler warning if we don't access this parameter
+  
+  switch(opcode) {
+    
+  case 'D':
+    if (p[0]=="EXRAIL"_hk) { // <D EXRAIL ON/OFF>
+      diag = paramCount==2 && (p[1]=="ON"_hk || p[1]==1);
+      opcode=0;
+    }
+    break;
+	
+  case '/':  // New EXRAIL command
+    if (parseSlash(stream,paramCount,p)) opcode=0;
+    break;
+  
+  case 'A': //  <A address aspect>
+    if (paramCount!=2) break; 
+    // Ask exrail if this is just changing the aspect on a 
+    // predefined DCCX_SIGNAL. Because this will handle all 
+    // the IFRED and ONRED type issues at the same time.  
+    if (signalAspectEvent(p[0],p[1])) opcode=0; // all done 
+    break;
+
+  case 'L':
+    // This entire code block is compiled out if LLC macros not used 
+    if (!(compileFeatures & FEATURE_LCC)) return;
+    static int lccProgCounter=0;
+    static int lccEventIndex=0;
+      
+    if (paramCount==0) {  //<L>  LCC adapter introducing self
+      LCCSerial=stream;   // now we know where to send events we raise
+      opcode=0;  // flag command as intercepted
+
+      // loop through all possible sent/waited events 
+      for (int progCounter=lccProgCounter;; SKIPOP) {
+        byte exrailOpcode=GET_OPCODE;
+        switch (exrailOpcode) {
+          case OPCODE_ENDEXRAIL:
+               stream->print(F("<LR>\n")); // ready to roll
+               lccProgCounter=0; // allow a second pass
+               lccEventIndex=0;
+               return;
+
+          case OPCODE_LCC:  
+               StringFormatter::send(stream,F("<LS x%h>\n"),getOperand(progCounter,0));
+               SKIPOP;
+               lccProgCounter=progCounter; 
+               return;
+
+          case OPCODE_LCCX:  // long form LCC
+               StringFormatter::send(stream,F("<LS x%h%h%h%h>\n"),
+                 getOperand(progCounter,1),
+                 getOperand(progCounter,2),
+                 getOperand(progCounter,3),
+                 getOperand(progCounter,0)
+                 );
+               SKIPOP;SKIPOP;SKIPOP;SKIPOP;          
+               lccProgCounter=progCounter; 
+               return;
+
+          case OPCODE_ACON:  // CBUS ACON 
+          case OPCODE_ACOF:  // CBUS ACOF 
+                StringFormatter::send(stream,F("<LS x%c%h%h>\n"),
+                  exrailOpcode==OPCODE_ACOF?'1':'0',
+                  getOperand(progCounter,0),getOperand(progCounter,1)); 
+               SKIPOP;SKIPOP;
+               lccProgCounter=progCounter; 
+               return;
+      
+      // we stream the hex events we wish to listen to
+      // and at the same time build the event index looku.
+      
+        case OPCODE_ONLCC:
+           StringFormatter::send(stream,F("<LL %d x%h%h%h:%h>\n"),
+                 lccEventIndex,
+                 getOperand(progCounter,1),
+                 getOperand(progCounter,2),
+                 getOperand(progCounter,3),
+                 getOperand(progCounter,0)
+                 );   
+           SKIPOP;SKIPOP;SKIPOP;SKIPOP;      
+           // start on handler at next      
+           onLCCLookup[lccEventIndex]=progCounter; 
+           lccEventIndex++;        
+           lccProgCounter=progCounter; 
+           return;
+
+        case OPCODE_ONACON:
+        case OPCODE_ONACOF:
+           StringFormatter::send(stream,F("<LL %d x%c%h%h>\n"),
+                 lccEventIndex,
+                 exrailOpcode==OPCODE_ONACOF?'1':'0',
+                 getOperand(progCounter,0),getOperand(progCounter,1)
+                 ); 
+           SKIPOP;SKIPOP;
+           // start on handler at next      
+           onLCCLookup[lccEventIndex]=progCounter; 
+           lccEventIndex++;        
+           lccProgCounter=progCounter; 
+           return;
+           
+         default:
+           break;
+        }  
+      }
+    }
+    if (paramCount==1) {  // <L eventid> LCC event arrived from adapter
+        int16_t eventid=p[0];
+        bool reject = eventid<0 || eventid>=countLCCLookup;
+        if (!reject) {
+          startNonRecursiveTask(F("LCC"),eventid,onLCCLookup[eventid]);
+          opcode=0;
+        }
+    }
+    break; 
+    
+    case 'J':  // throttle info commands
+        if (paramCount<1) return; 
+        switch(p[0]) {
+          case "A"_hk: // <JA> returns automations/routes
+            if (paramCount==1) {// <JA>
+              StringFormatter::send(stream, F("<jA"));
+              routeLookup->stream(stream);
+              StringFormatter::send(stream, F(">\n"));
+              opcode=0;
+              return; 
+            }
+            if (paramCount==2) {  // <JA id>
+              int16_t id=p[1];
+              StringFormatter::send(stream,F("<jA %d %c \"%S\">\n"), 
+                id, getRouteType(id), getRouteDescription(id));
+              
+              if (compileFeatures & FEATURE_ROUTESTATE) {
+                // Send any non-default button states or captions
+                int16_t statePos=routeLookup->findPosition(id);
+                if (statePos>=0) {
+                 if (routeStateArray[statePos]) 
+                 StringFormatter::send(stream,F("<jB %d %d>\n"), id, routeStateArray[statePos]);
+                  if (routeCaptionArray[statePos]) 
+                  StringFormatter::send(stream,F("<jB %d \"%S\">\n"), id,routeCaptionArray[statePos]);
+                }
+              }
+              opcode=0;
+              return;
+            }
+            break;
+        case "M"_hk:
+            // NOTE: we only need to handle valid calls here because 
+            // DCCEXParser has to have code to handle the <J<> cases where
+            // exrail isnt involved anyway. 
+            // This entire code block is compiled out if STASH macros not used 
+          if (!(compileFeatures & FEATURE_STASH)) return;
+          if (paramCount==1) { // <JM>
+              StringFormatter::send(stream,F("<jM %d>\n"),maxStashId);
+              opcode=0;
+              break;
+            } 
+          if (paramCount==2) {  // <JM id>
+              if (p[1]<=0 || p[1]>maxStashId) break;
+              StringFormatter::send(stream,F("<jM %d %d>\n"),
+                    p[1],stashArray[p[1]]);
+               opcode=0;     
+               break;    
+          } 
+          if (paramCount==3) {  // <JM id cab>
+              if (p[1]<=0 || p[1]>maxStashId) break;
+              stashArray[p[1]]=p[2];
+              opcode=0;
+              break;      
+          }
+          break; 
+
+        default:
+            break;
+        }
+  default:  // other commands pass through
+    break;
+  }
+}
+
+bool RMFT2::parseSlash(Print * stream, byte & paramCount, int16_t p[]) {
+
+  if (paramCount==0) { // STATUS
+    StringFormatter::send(stream, F("<* EXRAIL STATUS"));
+    RMFT2 * task=loopTask;
+    while(task) {
+      if ((compileFeatures & FEATURE_BLINK)
+       && (task->blinkState==blink_high || task->blinkState==blink_low)) {
+        StringFormatter::send(stream,F("\nID=%d,PC=%d,BLINK=%d"),
+			    (int)(task->taskId),task->progCounter,task->blinkPin
+			    );
+      }
+      else {
+      StringFormatter::send(stream,F("\nID=%d,PC=%d,LOCO=%d%c,SPEED=%d%c"),
+			    (int)(task->taskId),task->progCounter,task->loco,
+			    task->invert?'I':' ',
+			    task->speedo,
+			    task->forward?'F':'R'
+			    );
+      }
+      task=task->next;
+      if (task==loopTask) break;
+    }
+    // Now stream the flags
+    for (int id=0;id<MAX_FLAGS; id++) {
+      byte flag=flags[id];
+      if (flag & ~TASK_FLAG & ~SIGNAL_MASK) { // not interested in TASK_FLAG only. Already shown above
+	      StringFormatter::send(stream,F("\nflags[%d] "),id);
+	      if (flag & SECTION_FLAG) StringFormatter::send(stream,F(" RESERVED"));
+	      if (flag & LATCH_FLAG) StringFormatter::send(stream,F(" LATCHED"));
+      }
+    }
+
+    if (compileFeatures & FEATURE_SIGNAL) {
+      // do the signals
+      // flags[n] represents the state of the nth signal in the table 
+      for (int sigslot=0;;sigslot++) {
+        SIGNAL_DEFINITION slot=getSignalSlot(sigslot);
+        if (slot.type==sigtypeNoMoreSignals) break; // end of signal list
+	      if (slot.type==sigtypeContinuation) continue; // continueation of previous line
+	      byte flag=flags[sigslot] & SIGNAL_MASK; // obtain signal flags for this ids
+        StringFormatter::send(stream,F("\n%S[%d]"), 
+			      (flag == SIGNAL_RED)? F("RED") : (flag==SIGNAL_GREEN) ? F("GREEN") : F("AMBER"),
+			      slot.id);
+      } 
+    }
+
+    if (compileFeatures & FEATURE_STASH) {
+      for (int i=1;i<=maxStashId;i++) {
+        if (stashArray[i])
+          StringFormatter::send(stream,F("\nSTASH[%d] Loco=%d"),
+              i, stashArray[i]); 
+      } 
+    }
+    
+    StringFormatter::send(stream,F(" *>\n"));
+    return true;
+  }
+  switch (p[0]) {
+  case "PAUSE"_hk: // </ PAUSE>
+    if (paramCount!=1) return false;
+    DCC::setThrottle(0,1,true);  // pause all locos on the track
+    pausingTask=(RMFT2 *)1; // Impossible task address
+    return true;
+    
+  case "RESUME"_hk: // </ RESUME>
+    if (paramCount!=1) return false;
+    pausingTask=NULL;
+    {
+      RMFT2 * task=loopTask;
+      while(task) {
+	if (task->loco) task->driveLoco(task->speedo);
+	task=task->next;
+	if (task==loopTask) break;
+      }
+    }
+    return true;
+    
+    
+  case "START"_hk: // </ START [cab] route >
+    if (paramCount<2 || paramCount>3) return false;
+    {
+      int route=(paramCount==2) ? p[1] : p[2];
+      uint16_t cab=(paramCount==2)? 0 : p[1];
+      int pc=routeLookup->find(route);
+      if (pc<0) return false;
+      RMFT2* task=new RMFT2(pc);
+      task->loco=cab;
+    }
+    return true;
+    
+  default:
+    break;
+  }
+
+  // check KILL ALL here, otherwise the next validation confuses ALL with a flag  
+  if (p[0]=="KILL"_hk && p[1]=="ALL"_hk) {
+    while (loopTask) loopTask->kill(F("KILL ALL")); // destructor changes loopTask
+    return true;   
+  }
+
+  // all other / commands take 1 parameter
+  if (paramCount!=2 ) return false;
+  
+  switch (p[0]) {
+  case "KILL"_hk: // Kill taskid|ALL
+    {
+    if ( p[1]<0  || p[1]>=MAX_FLAGS) return false;
+    RMFT2 * task=loopTask;
+      while(task) {
+	      if (task->taskId==p[1]) {
+	        task->kill(F("KILL"));
+	        return  true;
+	      }
+	      task=task->next;
+	      if (task==loopTask) break;
+      }
+    }
+    return false;
+    
+  case "RESERVE"_hk:  // force reserve a section
+    return setFlag(p[1],SECTION_FLAG);
+    
+  case "FREE"_hk:  // force free a section
+    return setFlag(p[1],0,SECTION_FLAG);
+    
+  case "LATCH"_hk:
+    return setFlag(p[1], LATCH_FLAG);
+    
+  case "UNLATCH"_hk:
+    return setFlag(p[1], 0, LATCH_FLAG);
+ 
+  case "RED"_hk:
+    doSignal(p[1],SIGNAL_RED);
+    return true;
+ 
+  case "AMBER"_hk:
+    doSignal(p[1],SIGNAL_AMBER);
+    return true;
+ 
+  case "GREEN"_hk:
+    doSignal(p[1],SIGNAL_GREEN);
+    return true;
+    
+  default:
+    return false;
+  }
+}

EXRAILMacros.h

@@ -0,0 +1,687 @@
+/*
+ *  © 2021 Neil McKechnie
+ *  © 2020-2022 Chris Harlow
+ *  © 2022-2023 Colin Murdoch
+ *  © 2023 Harald Barth
+ *  © 2025 Morten Nielsen
+ *  All rights reserved.
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef EXRAILMacros_H
+#define EXRAILMacros_H
+
+// remove normal code LCD & SERIAL macros (will be restored later)
+#undef LCD
+#undef SERIAL
+
+
+// This file will include and build the EXRAIL script and associated helper tricks.
+// It does this by including myAutomation.h several times, each with a set of macros to 
+// extract the relevant parts.
+
+// The entire automation script is contained within a byte array RMFT2::RouteCode[]
+// made up of opcode and parameter pairs.
+// ech opcode is a 1 byte operation plus 2 byte operand. 
+// The array is normally built using the macros below as this makes it easier 
+// to manage the cases where:
+// - padding must be applied to ensure the correct alignment of the next instruction
+// - large parameters must be split up
+// - multiple parameters aligned correctly
+// - a single macro requires multiple operations
+
+// Descriptive texts for routes and animations are created in a sepaerate function which
+// can be called to emit a list of routes/automatuions in a form suitable for Withrottle. 
+ 
+// PRINT(msg), LCD(row,msg) and SCREEN(display,row,msg) are implemented in a separate pass to create 
+// a getMessageText(id) function.  
+
+// CAUTION: The macros below are multiple passed over myAutomation.h
+
+
+// helper macro for turnout descriptions, creates NULL for missing description
+#define O_DESC(id, desc) case id: return ("" desc)[0]?F("" desc):NULL;
+// helper macro for turntable descriptions, creates NULL for missing description
+#define T_DESC(tid,pid,desc) if(turntableId==tid && positionId==pid) return ("" desc)[0]?F("" desc):NULL;
+// helper macro for turnout description as HIDDEN 
+#define HIDDEN "\x01"
+
+// PLAYSOUND is alias of ANOUT to make the user experience of a Conductor beter for
+// playing sounds with IO_I2CDFPlayer
+#define PLAYSOUND ANOUT
+
+// SEG7 is a helper to create ANOUT from a 7-segment request
+#define SEG7(vpin,value,format) \
+   ANOUT(vpin,(value & 0xFFFF),TM1638::DF_##format,((uint32_t)value)>>16)
+
+// helper macro to strip leading zeros off time inputs
+// (10#mins)%100)
+#define STRIP_ZERO(value) 10##value%100
+
+// These constants help EXRAIL macros convert Track Power e.g. SET_POWER(A ON|OFF).
+//const byte TRACK_POWER_0=0, TRACK_POWER_OFF=0;    
+//const byte TRACK_POWER_1=1, TRACK_POWER_ON=1;   
+
+// NEOPIXEL RG generator for NEOPIXEL_SIGNAL 
+#define NeoRGB(red,green,blue) (((uint32_t)(red & 0xff)<<16) | ((uint32_t)(green & 0xff)<<8) | (uint32_t)(blue & 0xff))  
+
+// Pass 1 Implements aliases 
+#include "EXRAIL2MacroReset.h"
+#undef ALIAS
+#define ALIAS(name,value...) const int name= #value[0] ? value+0: -__COUNTER__ ; 
+#include "myAutomation.h"
+
+// Pass 1d Detect sequence duplicates.
+// This pass generates no runtime data or code 
+#include "EXRAIL2MacroReset.h"
+#undef AUTOMATION
+#define AUTOMATION(id, description) id,
+#undef ROUTE
+#define ROUTE(id, description) id,
+#undef SEQUENCE
+#define SEQUENCE(id) id,
+constexpr int16_t compileTimeSequenceList[]={
+   #include "myAutomation.h"
+   0
+   };
+constexpr int16_t stuffSize=sizeof(compileTimeSequenceList)/sizeof(int16_t) - 1;
+
+
+// Compile time function to check for sequence nos.
+constexpr bool hasseq(const int16_t value, const int16_t pos=0 ) {
+    return pos>=stuffSize? false :
+          compileTimeSequenceList[pos]==value 
+       || hasseq(value,pos+1); 
+}
+
+// Compile time function to check for duplicate sequence nos.
+constexpr bool hasdup(const int16_t value, const int16_t pos ) {
+    return pos>=stuffSize? false :
+          compileTimeSequenceList[pos]==value 
+       || hasseq(value,pos+1) 
+       || hasdup(compileTimeSequenceList[pos],pos+1);
+}
+
+
+static_assert(!hasdup(compileTimeSequenceList[0],1),"Duplicate SEQUENCE/ROUTE/AUTOMATION detected");
+
+//pass 1s static asserts to
+//  - check call and follows etc for existing sequence numbers
+//  - check range on LATCH/UNLATCH
+// This pass generates no runtime data or code 
+#include "EXRAIL2MacroReset.h"
+#undef ASPECT
+#define ASPECT(address,value) static_assert(address <=2044, "invalid Address"); \
+                              static_assert(address>=-3, "Invalid value");
+#undef CALL
+#define CALL(id) static_assert(hasseq(id),"Sequence not found");
+#undef FOLLOW
+#define FOLLOW(id)  static_assert(hasseq(id),"Sequence not found");
+#undef START
+#define START(id)  static_assert(hasseq(id),"Sequence not found");
+#undef SENDLOCO
+#define SENDLOCO(cab,id) static_assert(hasseq(id),"Sequence not found");
+#undef LATCH
+#define LATCH(id) static_assert(id>=0 && id<MAX_FLAGS,"Id out of valid range 0-255" );
+#undef UNLATCH
+#define UNLATCH(id) static_assert(id>=0 && id<MAX_FLAGS,"Id out of valid range 0-255" );
+#undef RESERVE
+#define RESERVE(id) static_assert(id>=0 && id<MAX_FLAGS,"Id out of valid range 0-255" );
+#undef FREE
+#define FREE(id) static_assert(id>=0 && id<MAX_FLAGS,"Id out of valid range 0-255" );
+#undef SPEED
+#define SPEED(speed) static_assert(speed>=0 && speed<128,"Speed out of valid range 0-127");
+#undef FWD
+#define FWD(speed) static_assert(speed>=0 && speed<128,"Speed out of valid range 0-127");
+#undef REV
+#define REV(speed) static_assert(speed>=0 && speed<128,"Speed out of valid range 0-127");
+
+#include "myAutomation.h"
+
+// Pass 1g Implants STEALTH_GLOBAL in correct place 
+#include "EXRAIL2MacroReset.h"
+#undef STEALTH_GLOBAL
+#define STEALTH_GLOBAL(code...) code
+#include "myAutomation.h"
+
+// Pass 1h Implements HAL macro by creating exrailHalSetup function
+// Also allows creating EXTurntable object
+#include "EXRAIL2MacroReset.h"
+#undef HAL
+#define HAL(haltype,params...)  haltype::create(params);
+#undef HAL_IGNORE_DEFAULTS
+#define HAL_IGNORE_DEFAULTS ignore_defaults=true;
+#undef JMRI_SENSOR
+#define JMRI_SENSOR(vpin,count...) Sensor::createMultiple(vpin,##count);
+#undef  CONFIGURE_SERVO
+#define CONFIGURE_SERVO(vpin,pos1,pos2,profile) IODevice::configureServo(vpin,pos1,pos2,PCA9685::profile);
+bool exrailHalSetup() {
+   bool ignore_defaults=false;
+   #include "myAutomation.h"
+   return ignore_defaults;
+}
+
+// Pass 1c detect compile time featurtes
+#include "EXRAIL2MacroReset.h"
+#undef SIGNAL
+#define SIGNAL(redpin,amberpin,greenpin) | FEATURE_SIGNAL 
+#undef SIGNALH
+#define SIGNALH(redpin,amberpin,greenpin) | FEATURE_SIGNAL 
+#undef SERVO_SIGNAL
+#define SERVO_SIGNAL(vpin,redval,amberval,greenval) | FEATURE_SIGNAL 
+#undef DCC_SIGNAL
+#define DCC_SIGNAL(id,addr,subaddr) | FEATURE_SIGNAL
+#undef DCCX_SIGNAL
+#define DCCX_SIGNAL(id,redAspect,amberAspect,greenAspect) | FEATURE_SIGNAL
+#undef NEOPIXEL_SIGNAL
+#define NEOPIXEL_SIGNAL(sigid,redcolour,ambercolour,greencolour) | FEATURE_SIGNAL
+#undef VIRTUAL_SIGNAL
+#define VIRTUAL_SIGNAL(id) | FEATURE_SIGNAL
+
+#undef LCC
+#define LCC(eventid)  | FEATURE_LCC
+#undef LCCX
+#define LCCX(senderid,eventid) | FEATURE_LCC 
+#undef ONLCC
+#define ONLCC(senderid,eventid) | FEATURE_LCC
+#undef ACON
+#define ACON(eventid) | FEATURE_LCC
+#undef ACOF
+#define ACOF(eventid) | FEATURE_LCC
+#undef ONACON
+#define ONACON(eventid) | FEATURE_LCC
+#undef ONACOF
+#define ONACOF(eventid) | FEATURE_LCC
+#undef ROUTE_ACTIVE
+#define ROUTE_ACTIVE(id) | FEATURE_ROUTESTATE
+#undef ROUTE_INACTIVE
+#define ROUTE_INACTIVE(id) | FEATURE_ROUTESTATE
+#undef ROUTE_HIDDEN
+#define ROUTE_HIDDEN(id) | FEATURE_ROUTESTATE
+#undef ROUTE_DISABLED
+#define ROUTE_DISABLED(id) | FEATURE_ROUTESTATE
+#undef ROUTE_CAPTION
+#define ROUTE_CAPTION(id,caption) | FEATURE_ROUTESTATE
+
+#undef CLEAR_STASH
+#define CLEAR_STASH(id) | FEATURE_STASH
+#undef CLEAR_ALL_STASH
+#define CLEAR_ALL_STASH | FEATURE_STASH
+#undef PICKUP_STASH
+#define PICKUP_STASH(id) | FEATURE_STASH
+#undef STASH
+#define STASH(id) | FEATURE_STASH
+#undef BLINK
+#define BLINK(vpin,onDuty,offDuty) | FEATURE_BLINK
+#undef ONBUTTON
+#define ONBUTTON(vpin) | FEATURE_SENSOR
+#undef ONSENSOR
+#define ONSENSOR(vpin) | FEATURE_SENSOR
+
+const byte RMFT2::compileFeatures = 0
+   #include "myAutomation.h"
+;
+
+// Pass 2 create throttle route list 
+#include "EXRAIL2MacroReset.h"
+#undef ROUTE
+#define ROUTE(id, description) id,
+const int16_t HIGHFLASH  RMFT2::routeIdList[]= {
+    #include "myAutomation.h"
+    INT16_MAX};
+// Pass 2a create throttle automation list 
+#include "EXRAIL2MacroReset.h"
+#undef AUTOMATION
+#define AUTOMATION(id, description) id,
+const int16_t HIGHFLASH RMFT2::automationIdList[]= {
+    #include "myAutomation.h"
+    INT16_MAX};
+
+// Pass 3 Create route descriptions:
+#undef ROUTE
+#define ROUTE(id, description) case id: return F(description);
+#undef AUTOMATION
+#define AUTOMATION(id, description) case id: return F(description);
+const FSH * RMFT2::getRouteDescription(int16_t id) {
+   switch(id) {
+    #include "myAutomation.h"
+    default: break;
+   }
+   return F("");
+}
+
+// Pass 4... Create Text sending functions
+#include "EXRAIL2MacroReset.h"
+const int StringMacroTracker1=__COUNTER__;
+#define THRUNGE(msg,mode) \
+     case (__COUNTER__ - StringMacroTracker1) : {\
+         static const char HIGHFLASH thrunge[]=msg;\
+         strfar=(uint32_t)GETFARPTR(thrunge);\
+         tmode=mode;\
+         break;\
+      } 
+#undef BROADCAST
+#define BROADCAST(msg) THRUNGE(msg,thrunge_broadcast)
+#undef PARSE
+#define PARSE(msg) THRUNGE(msg,thrunge_parse)
+#undef PRINT
+#define PRINT(msg) THRUNGE(msg,thrunge_print)
+#undef LCN
+#define LCN(msg)   THRUNGE(msg,thrunge_lcn)
+#undef MESSAGE
+#define MESSAGE(msg) THRUNGE(msg,thrunge_message)
+
+#undef ROUTE_CAPTION
+#define ROUTE_CAPTION(id,caption) \
+case (__COUNTER__ - StringMacroTracker1) : {\
+   manageRouteCaption(id,F(caption));\
+   return;\
+   }
+#undef SERIAL
+#define SERIAL(msg)   THRUNGE(msg,thrunge_serial)
+#undef SERIAL1
+#define SERIAL1(msg)  THRUNGE(msg,thrunge_serial1)
+#undef SERIAL2
+#define SERIAL2(msg)  THRUNGE(msg,thrunge_serial2)
+#undef SERIAL3
+#define SERIAL3(msg)  THRUNGE(msg,thrunge_serial3)
+#undef SERIAL4
+#define SERIAL4(msg)  THRUNGE(msg,thrunge_serial4)
+#undef SERIAL5
+#define SERIAL5(msg)  THRUNGE(msg,thrunge_serial5)
+#undef SERIAL6
+#define SERIAL6(msg)  THRUNGE(msg,thrunge_serial6)
+#undef LCD
+#define LCD(id,msg)  \
+     case (__COUNTER__ - StringMacroTracker1) : {\
+         static const char HIGHFLASH thrunge[]=msg;\
+         strfar=(uint32_t)GETFARPTR(thrunge);\
+         tmode=thrunge_lcd; \
+         lcdid=id;\
+         break;\
+      }
+#undef SCREEN
+#define SCREEN(display,id,msg)  \
+     case (__COUNTER__ - StringMacroTracker1) : {\
+         static const char HIGHFLASH thrunge[]=msg;\
+         strfar=(uint32_t)GETFARPTR(thrunge);\
+         tmode=(thrunger)(thrunge_lcd+display); \
+         lcdid=id;\
+         break;\
+      } 
+#undef STEALTH
+#define STEALTH(code...) case (__COUNTER__ - StringMacroTracker1) : {code} return; 
+#undef WITHROTTLE
+#define WITHROTTLE(msg) THRUNGE(msg,thrunge_withrottle)
+
+void  RMFT2::printMessage(uint16_t id) { 
+  thrunger tmode;
+  uint32_t strfar=0;
+  byte lcdid=0; 
+  switch(id) {
+    #include "myAutomation.h"
+    default: break ; 
+  }
+  if (strfar) thrungeString(strfar,tmode,lcdid);
+}
+
+
+// Pass 5: Turnout descriptions (optional)
+#include "EXRAIL2MacroReset.h"
+#undef TURNOUT
+#define TURNOUT(id,addr,subaddr,description...) O_DESC(id,description)
+#undef TURNOUTL
+#define TURNOUTL(id,addr,description...) O_DESC(id,description)
+#undef PIN_TURNOUT
+#define PIN_TURNOUT(id,pin,description...) O_DESC(id,description)
+#undef SERVO_TURNOUT
+#define SERVO_TURNOUT(id,pin,activeAngle,inactiveAngle,profile,description...) O_DESC(id,description)
+#undef VIRTUAL_TURNOUT
+#define VIRTUAL_TURNOUT(id,description...) O_DESC(id,description)
+
+const FSH * RMFT2::getTurnoutDescription(int16_t turnoutid) {
+     switch (turnoutid) {
+        #include "myAutomation.h"
+     default:break;
+     }
+     return NULL;
+}
+
+// Pass to get turntable descriptions (optional)
+#include "EXRAIL2MacroReset.h"
+#undef DCC_TURNTABLE
+#define DCC_TURNTABLE(id,home,description...) O_DESC(id,description)
+#undef EXTT_TURNTABLE
+#define EXTT_TURNTABLE(id,vpin,home,description...) O_DESC(id,description)
+
+const FSH * RMFT2::getTurntableDescription(int16_t turntableId) {
+   switch (turntableId) {
+      #include "myAutomation.h"
+   default:break;
+   }
+   return NULL;
+}
+
+// Pass to get turntable position descriptions (optional)
+#include "EXRAIL2MacroReset.h"
+#undef TT_ADDPOSITION
+#define TT_ADDPOSITION(turntable_id,position,value,home,description...) T_DESC(turntable_id,position,description)
+
+const FSH * RMFT2::getTurntablePositionDescription(int16_t turntableId, uint8_t positionId) {
+  (void)turntableId;
+  (void)positionId;
+   #include "myAutomation.h"
+   return NULL;
+}
+
+// Pass 6: Roster IDs (count)
+#include "EXRAIL2MacroReset.h"
+#undef ROSTER
+#define ROSTER(cabid,name,funcmap...) +(cabid <= 0 ? 0 : 1)
+const byte RMFT2::rosterNameCount=0
+   #include "myAutomation.h"
+   ;
+   
+// Pass 6: Roster IDs 
+#include "EXRAIL2MacroReset.h"
+#undef ROSTER
+#define ROSTER(cabid,name,funcmap...) cabid,
+const int16_t HIGHFLASH  RMFT2::rosterIdList[]={
+   #include "myAutomation.h"
+   INT16_MAX};
+
+// Pass 7: Roster names getter
+#include "EXRAIL2MacroReset.h"
+#undef ROSTER
+#define ROSTER(cabid,name,funcmap...) case cabid: return F(name);
+const FSH * RMFT2::getRosterName(int16_t id) {
+   switch(id) {
+      #include "myAutomation.h"
+   default: break;
+   }
+   return F("");   
+} 
+
+// Pass to get roster functions 
+#undef ROSTER
+#define ROSTER(cabid,name,funcmap...) case cabid: return F("" funcmap);
+const FSH * RMFT2::getRosterFunctions(int16_t id) {
+   switch(id) {
+      #include "myAutomation.h"
+   default: break; 
+   }   
+   return NULL;
+} 
+
+// Pass 8 Signal definitions
+#include "EXRAIL2MacroReset.h"
+#undef SIGNAL
+#define SIGNAL(redpin,amberpin,greenpin) {sigtypeSIGNAL,redpin,redpin,amberpin,greenpin}, 
+#undef SIGNALH
+#define SIGNALH(redpin,amberpin,greenpin) {sigtypeSIGNALH,redpin,redpin,amberpin,greenpin}, 
+#undef SERVO_SIGNAL
+#define SERVO_SIGNAL(vpin,redval,amberval,greenval) {sigtypeSERVO,vpin,redval,amberval,greenval}, 
+#undef DCC_SIGNAL
+#define DCC_SIGNAL(id,addr,subaddr) {sigtypeDCC,id,addr,subaddr,0},
+#undef DCCX_SIGNAL
+#define DCCX_SIGNAL(id,redAspect,amberAspect,greenAspect) {sigtypeDCCX,id,redAspect,amberAspect,greenAspect},
+#undef NEOPIXEL_SIGNAL
+#define NEOPIXEL_SIGNAL(id,redRGB,amberRGB,greenRGB) \
+        {sigtypeNEOPIXEL,id,((VPIN)((redRGB)>>8)), ((VPIN)((amberRGB)>>8)), ((VPIN)((greenRGB)>>8))},\
+        {sigtypeContinuation,id,((VPIN)((redRGB) & 0xff)), ((VPIN)((amberRGB) & 0xFF)), ((VPIN)((greenRGB) & 0xFF))},
+#undef VIRTUAL_SIGNAL
+#define VIRTUAL_SIGNAL(id) {sigtypeVIRTUAL,id,0,0,0},
+
+const  HIGHFLASH  SIGNAL_DEFINITION RMFT2::SignalDefinitions[] = {
+    #include "myAutomation.h"
+     {sigtypeNoMoreSignals,0,0,0,0}
+    };
+
+// Pass 9 ONLCC/ ONMERG counter and lookup array
+#include "EXRAIL2MacroReset.h"
+#undef ONLCC
+#define ONLCC(sender,event) +1 
+#undef ONACON
+#define ONACON(event) +1 
+#undef ONACOF
+#define ONACOF(event) +1 
+
+const int RMFT2::countLCCLookup=0
+#include "myAutomation.h"
+;
+int RMFT2::onLCCLookup[RMFT2::countLCCLookup];
+
+// Last Pass : create main routes table
+// Only undef the macros, not dummy them.  
+#define  RMFT2_UNDEF_ONLY
+#include "EXRAIL2MacroReset.h"
+// Define internal helper macros.
+// Everything we generate here has to be compile-time evaluated to 
+// a constant.  
+#define V(val) (byte)(((int16_t)(val))&0x00FF),(byte)(((int16_t)(val)>>8)&0x00FF)
+// Define macros for route code creation 
+
+#define ACTIVATE(addr,subaddr) OPCODE_DCCACTIVATE,V(addr<<3 | subaddr<<1 | 1),
+#define ACTIVATEL(addr) OPCODE_DCCACTIVATE,V((addr+3)<<1 | 1),
+#define AFTER(sensor_id,timer...) OPCODE_AT,V(sensor_id),OPCODE_AFTER,V(sensor_id),OPCODE_PAD,V(#timer[0]?timer+0:500),
+#define AFTEROVERLOAD(track_id) OPCODE_AFTEROVERLOAD,V(TRACK_NUMBER_##track_id),
+#define ALIAS(name,value...) 
+#define AMBER(signal_id) OPCODE_AMBER,V(signal_id),
+#define ANOUT(vpin,value,param1,param2) OPCODE_SERVO,V(vpin),OPCODE_PAD,V(value),OPCODE_PAD,V(param1),OPCODE_PAD,V(param2),
+#define ASPECT(address,value) OPCODE_ASPECT,V((address<<5) | (value & 0x1F)),
+#define AT(sensor_id) OPCODE_AT,V(sensor_id),
+#define ATGTE(sensor_id,value) OPCODE_ATGTE,V(sensor_id),OPCODE_PAD,V(value),  
+#define ATLT(sensor_id,value) OPCODE_ATLT,V(sensor_id),OPCODE_PAD,V(value),  
+#define ATTIMEOUT(sensor_id,timeout) OPCODE_ATTIMEOUT1,0,0,OPCODE_ATTIMEOUT2,V(sensor_id),OPCODE_PAD,V(timeout/100L),
+#define AUTOMATION(id, description)  OPCODE_AUTOMATION, V(id), 
+#define AUTOSTART OPCODE_AUTOSTART,0,0,
+#define BLINK(vpin,onDuty,offDuty) OPCODE_BLINK,V(vpin),OPCODE_PAD,V(onDuty),OPCODE_PAD,V(offDuty),
+#define BROADCAST(msg) PRINT(msg)
+#define CALL(route) OPCODE_CALL,V(route),
+#define CLEAR_STASH(id) OPCODE_CLEAR_STASH,V(id),
+#define CLEAR_ALL_STASH OPCODE_CLEAR_ALL_STASH,V(0),
+#define CLOSE(id)  OPCODE_CLOSE,V(id),
+#define CONFIGURE_SERVO(vpin,pos1,pos2,profile)
+#ifndef IO_NO_HAL
+#define DCC_TURNTABLE(id,home,description...) OPCODE_DCCTURNTABLE,V(id),OPCODE_PAD,V(home),
+#endif
+#define DEACTIVATE(addr,subaddr) OPCODE_DCCACTIVATE,V(addr<<3 | subaddr<<1),
+#define DEACTIVATEL(addr) OPCODE_DCCACTIVATE,V((addr+3)<<1),
+#define DELAY(ms) ms<30000?OPCODE_DELAYMS:OPCODE_DELAY,V(ms/(ms<30000?1L:100L)),
+#define DELAYMINS(mindelay) OPCODE_DELAYMINS,V(mindelay),
+#define DELAYRANDOM(mindelay,maxdelay) DELAY(mindelay) OPCODE_RANDWAIT,V((maxdelay-mindelay)/100L),
+#define DCC_SIGNAL(id,add,subaddr)
+#define DCCX_SIGNAL(id,redAspect,amberAspect,greenAspect)
+#define DONE OPCODE_ENDTASK,0,0,
+#define DRIVE(analogpin) OPCODE_DRIVE,V(analogpin),
+#define ELSE OPCODE_ELSE,0,0,
+#define ENDEXRAIL 
+#define ENDIF  OPCODE_ENDIF,0,0,
+#define ENDTASK OPCODE_ENDTASK,0,0,
+#define ESTOP OPCODE_SPEED,V(1), 
+#define EXRAIL
+#ifndef IO_NO_HAL
+#define EXTT_TURNTABLE(id,vpin,home,description...) OPCODE_EXTTTURNTABLE,V(id),OPCODE_PAD,V(vpin),OPCODE_PAD,V(home),
+#endif
+#define FADE(pin,value,ms) OPCODE_SERVO,V(pin),OPCODE_PAD,V(value),OPCODE_PAD,V((int16_t)PCA9685::ProfileType::UseDuration|(int16_t)PCA9685::ProfileType::NoPowerOff),OPCODE_PAD,V(ms/100L),
+#define FOFF(func) OPCODE_FOFF,V(func),
+#define FOLLOW(route) OPCODE_FOLLOW,V(route),
+#define FON(func) OPCODE_FON,V(func),
+#define FORGET OPCODE_FORGET,0,0,
+#define FREE(blockid) OPCODE_FREE,V(blockid),
+#define FTOGGLE(func) OPCODE_FTOGGLE,V(func),
+#define FWD(speed) OPCODE_FWD,V(speed),
+#define GREEN(signal_id) OPCODE_GREEN,V(signal_id),
+#define HAL(haltype,params...)
+#define HAL_IGNORE_DEFAULTS
+#define IF(sensor_id) OPCODE_IF,V(sensor_id),
+#define IFAMBER(signal_id) OPCODE_IFAMBER,V(signal_id),
+#define IFCLOSED(turnout_id) OPCODE_IFCLOSED,V(turnout_id),
+#define IFGREEN(signal_id) OPCODE_IFGREEN,V(signal_id),
+#define IFGTE(sensor_id,value) OPCODE_IFGTE,V(sensor_id),OPCODE_PAD,V(value),
+#define IFLOCO(loco_id) OPCODE_IFLOCO,V(loco_id),
+#define IFLT(sensor_id,value) OPCODE_IFLT,V(sensor_id),OPCODE_PAD,V(value),
+#define IFNOT(sensor_id) OPCODE_IFNOT,V(sensor_id),
+#define IFRANDOM(percent) OPCODE_IFRANDOM,V(percent),
+#define IFRED(signal_id) OPCODE_IFRED,V(signal_id),
+#define IFRESERVE(block) OPCODE_IFRESERVE,V(block),
+#define IFTHROWN(turnout_id) OPCODE_IFTHROWN,V(turnout_id),
+#define IFTIMEOUT OPCODE_IFTIMEOUT,0,0,
+#ifndef IO_NO_HAL
+#define IFTTPOSITION(id,position) OPCODE_IFTTPOSITION,V(id),OPCODE_PAD,V(position),
+#endif
+#define IFRE(sensor_id,value) OPCODE_IFRE,V(sensor_id),OPCODE_PAD,V(value),
+#define INVERT_DIRECTION OPCODE_INVERT_DIRECTION,0,0,
+#define JMRI_SENSOR(vpin,count...)
+#define JOIN OPCODE_JOIN,0,0,
+#define KILLALL OPCODE_KILLALL,0,0,
+#define LATCH(sensor_id) OPCODE_LATCH,V(sensor_id),
+#define LCC(eventid) OPCODE_LCC,V(eventid),
+#define LCCX(sender,event) OPCODE_LCCX,V(event),\
+        OPCODE_PAD,V((((uint64_t)sender)>>32)&0xFFFF),\
+        OPCODE_PAD,V((((uint64_t)sender)>>16)&0xFFFF),\
+        OPCODE_PAD,V((((uint64_t)sender)>>0)&0xFFFF),  
+#define ACON(eventid) OPCODE_ACON,V(((uint32_t)eventid >>16) & 0xFFFF),OPCODE_PAD,V(eventid & 0xFFFF),
+#define ACOF(eventid) OPCODE_ACOF,V(((uint32_t)eventid >>16) & 0xFFFF),OPCODE_PAD,V(eventid & 0xFFFF),
+#define ONACON(eventid) OPCODE_ONACON,V((uint32_t)(eventid) >>16),OPCODE_PAD,V(eventid & 0xFFFF),
+#define ONACOF(eventid) OPCODE_ONACOF,V((uint32_t)(eventid) >>16),OPCODE_PAD,V(eventid & 0xFFFF),
+#define LCD(id,msg) PRINT(msg)
+#define SCREEN(display,id,msg) PRINT(msg)
+#define STEALTH(code...) PRINT(dummy)
+#define STEALTH_GLOBAL(code...) 
+#define LCN(msg) PRINT(msg)
+#define MESSAGE(msg) PRINT(msg)
+#define MOVETT(id,steps,activity) OPCODE_SERVO,V(id),OPCODE_PAD,V(steps),OPCODE_PAD,V(EXTurntable::activity),OPCODE_PAD,V(0),
+#define NEOPIXEL(id,r,g,b,count...) OPCODE_NEOPIXEL,V(id),\
+        OPCODE_PAD,V(((r & 0xff)<<8) | (g & 0xff)),\
+        OPCODE_PAD,V((b & 0xff)),\
+        OPCODE_PAD,V(#count[0]?(count+0):1),
+         
+#define NEOPIXEL_SIGNAL(sigid,redcolour,ambercolour,greencolour)
+#define ONACTIVATE(addr,subaddr) OPCODE_ONACTIVATE,V(addr<<2|subaddr),
+#define ONACTIVATEL(linear) OPCODE_ONACTIVATE,V(linear+3),
+#define ONAMBER(signal_id) OPCODE_ONAMBER,V(signal_id),
+#define ONCLOSE(turnout_id) OPCODE_ONCLOSE,V(turnout_id),
+#define ONLCC(sender,event) OPCODE_ONLCC,V(event),\
+        OPCODE_PAD,V((((uint64_t)sender)>>32)&0xFFFF),\
+        OPCODE_PAD,V((((uint64_t)sender)>>16)&0xFFFF),\
+        OPCODE_PAD,V((((uint64_t)sender)>>0)&0xFFFF),        
+#define ONTIME(value) OPCODE_ONTIME,V(value),  
+#define ONCLOCKTIME(hours,mins) OPCODE_ONTIME,V((STRIP_ZERO(hours)*60)+STRIP_ZERO(mins)),
+#define ONCLOCKMINS(mins) ONCLOCKTIME(25,mins)
+#define ONOVERLOAD(track_id) OPCODE_ONOVERLOAD,V(TRACK_NUMBER_##track_id),
+#define ONRAILSYNCON OPCODE_ONRAILSYNCON,0,0,
+#define ONRAILSYNCOFF OPCODE_ONRAILSYNCOFF,0,0,
+#define ONDEACTIVATE(addr,subaddr) OPCODE_ONDEACTIVATE,V(addr<<2|subaddr),
+#define ONDEACTIVATEL(linear) OPCODE_ONDEACTIVATE,V(linear+3),
+#define ONGREEN(signal_id) OPCODE_ONGREEN,V(signal_id),
+#define ONRED(signal_id) OPCODE_ONRED,V(signal_id),
+#ifndef IO_NO_HAL
+#define ONROTATE(id) OPCODE_ONROTATE,V(id),
+#endif
+#define ONTHROW(turnout_id) OPCODE_ONTHROW,V(turnout_id),
+#define ONCHANGE(sensor_id) OPCODE_ONCHANGE,V(sensor_id),
+#define ONSENSOR(sensor_id) OPCODE_ONSENSOR,V(sensor_id),
+#define ONBUTTON(sensor_id) OPCODE_ONBUTTON,V(sensor_id),
+#define PAUSE OPCODE_PAUSE,0,0,
+#define PICKUP_STASH(id) OPCODE_PICKUP_STASH,V(id),
+#define PIN_TURNOUT(id,pin,description...) OPCODE_PINTURNOUT,V(id),OPCODE_PAD,V(pin),
+#ifndef DISABLE_PROG
+#define POM(cv,value) OPCODE_POM,V(cv),OPCODE_PAD,V(value),
+#endif
+#define POWEROFF OPCODE_POWEROFF,0,0,
+#define POWERON OPCODE_POWERON,0,0,
+#define PRINT(msg) OPCODE_PRINT,V(__COUNTER__ - StringMacroTracker2),
+#define PARSE(msg) PRINT(msg)
+#define READ_LOCO OPCODE_READ_LOCO1,0,0,OPCODE_READ_LOCO2,0,0,
+#define RED(signal_id) OPCODE_RED,V(signal_id),
+#define RESERVE(blockid) OPCODE_RESERVE,V(blockid),
+#define RESET(pin,count...) OPCODE_RESET,V(pin),OPCODE_PAD,V(#count[0] ? count+0: 1),
+#define RESUME OPCODE_RESUME,0,0,
+#define RETURN OPCODE_RETURN,0,0,
+#define REV(speed) OPCODE_REV,V(speed),
+#define ROSTER(cabid,name,funcmap...)
+#ifndef IO_NO_HAL
+#define ROTATE(id,position,activity) OPCODE_ROTATE,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(EXTurntable::activity),
+#define ROTATE_DCC(id,position) OPCODE_ROTATE,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(0),
+#endif
+#define ROUTE(id, description)  OPCODE_ROUTE, V(id), 
+#define ROUTE_ACTIVE(id)  OPCODE_ROUTE_ACTIVE,V(id),
+#define ROUTE_INACTIVE(id)  OPCODE_ROUTE_INACTIVE,V(id),
+#define ROUTE_HIDDEN(id)  OPCODE_ROUTE_HIDDEN,V(id),
+#define ROUTE_DISABLED(id)  OPCODE_ROUTE_DISABLED,V(id),
+#define ROUTE_CAPTION(id,caption) PRINT(caption)
+#define SENDLOCO(cab,route) OPCODE_SENDLOCO,V(cab),OPCODE_PAD,V(route),
+#define SEQUENCE(id)  OPCODE_SEQUENCE, V(id), 
+#define SERIAL(msg) PRINT(msg)
+#define SERIAL1(msg) PRINT(msg)
+#define SERIAL2(msg) PRINT(msg)
+#define SERIAL3(msg) PRINT(msg)
+#define SERIAL4(msg) PRINT(msg)
+#define SERIAL5(msg) PRINT(msg)
+#define SERIAL6(msg) PRINT(msg)
+#define SERVO(id,position,profile) OPCODE_SERVO,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(PCA9685::profile),OPCODE_PAD,V(0),
+#define SERVO2(id,position,ms) OPCODE_SERVO,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(PCA9685::Instant),OPCODE_PAD,V(ms/100L),
+#define SERVO_SIGNAL(vpin,redpos,amberpos,greenpos)
+#define SERVO_TURNOUT(id,pin,activeAngle,inactiveAngle,profile,description...) OPCODE_SERVOTURNOUT,V(id),OPCODE_PAD,V(pin),OPCODE_PAD,V(activeAngle),OPCODE_PAD,V(inactiveAngle),OPCODE_PAD,V(PCA9685::ProfileType::profile),
+#define SET(pin,count...) OPCODE_SET,V(pin),OPCODE_PAD,V(#count[0] ? count+0: 1),
+#define SET_TRACK(track,mode)  OPCODE_SET_TRACK,V(TRACK_MODE_##mode  <<8 | TRACK_NUMBER_##track),
+#define SET_POWER(track,onoff) OPCODE_SET_POWER,V(TRACK_POWER_##onoff),OPCODE_PAD, V(TRACK_NUMBER_##track),
+#define SETLOCO(loco) OPCODE_SETLOCO,V(loco),
+#define SETFREQ(freq) OPCODE_SETFREQ,V(freq),
+#define SIGNAL(redpin,amberpin,greenpin) 
+#define SIGNALH(redpin,amberpin,greenpin) 
+#define SPEED(speed) OPCODE_SPEED,V(speed),
+#define START(route) OPCODE_START,V(route), 
+#define STASH(id) OPCODE_STASH,V(id), 
+#define STOP OPCODE_SPEED,V(0), 
+#define THROW(id)  OPCODE_THROW,V(id),
+#define TOGGLE_TURNOUT(id)  OPCODE_TOGGLE_TURNOUT,V(id),
+#ifndef IO_NO_HAL
+#define TT_ADDPOSITION(id,position,value,angle,description...) OPCODE_TTADDPOSITION,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(value),OPCODE_PAD,V(angle),
+#endif
+#define TURNOUT(id,addr,subaddr,description...) OPCODE_TURNOUT,V(id),OPCODE_PAD,V(addr),OPCODE_PAD,V(subaddr),
+#define TURNOUTL(id,addr,description...) TURNOUT(id,(addr-1)/4+1,(addr-1)%4, description)
+#define UNJOIN OPCODE_UNJOIN,0,0,
+#define UNLATCH(sensor_id) OPCODE_UNLATCH,V(sensor_id),
+#define VIRTUAL_SIGNAL(id) 
+#define VIRTUAL_TURNOUT(id,description...) OPCODE_PINTURNOUT,V(id),OPCODE_PAD,V(0), 
+#define WITHROTTLE(msg) PRINT(msg)
+#define WAITFOR(pin) OPCODE_WAITFOR,V(pin),
+#ifndef IO_NO_HAL
+#define WAITFORTT(turntable_id) OPCODE_WAITFORTT,V(turntable_id),
+#endif
+#define XFOFF(cab,func) OPCODE_XFOFF,V(cab),OPCODE_PAD,V(func),
+#define XFON(cab,func) OPCODE_XFON,V(cab),OPCODE_PAD,V(func),
+#define XFTOGGLE(cab,func) OPCODE_XFTOGGLE,V(cab),OPCODE_PAD,V(func),
+#define XFWD(cab,speed) OPCODE_XFWD,V(cab),OPCODE_PAD,V(speed),
+#define XREV(cab,speed) OPCODE_XREV,V(cab),OPCODE_PAD,V(speed),
+
+// Build RouteCode
+const int StringMacroTracker2=__COUNTER__;
+const  HIGHFLASH3  byte RMFT2::RouteCode[] = {
+    #include "myAutomation.h"
+    OPCODE_ENDTASK,0,0,OPCODE_ENDEXRAIL,0,0 };
+
+// Restore normal code LCD & SERIAL  macro
+#undef LCD
+#define LCD   StringFormatter::lcd
+#undef SCREEN
+#define SCREEN  StringFormatter::lcd2
+#undef SERIAL
+#define SERIAL  0x0
+#endif

EXRAILSensor.cpp

@@ -0,0 +1,104 @@
+/*
+ *  © 2024 Chris Harlow
+ *  All rights reserved.
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**********************************************************************
+EXRAILSensor represents a sensor that should be monitored in order
+to call an exrail ONBUTTON or ONCHANGE handler.
+These are created at EXRAIL startup and thus need no delete or listing
+capability.
+The basic logic is similar to that found in the Sensor class
+except that on the relevant change an EXRAIL thread is started.    
+**********************************************************************/
+
+#include "EXRAILSensor.h"
+#include "EXRAIL2.h"
+
+void EXRAILSensor::checkAll() {
+  if (firstSensor == NULL) return;  // No sensors to be scanned
+  if (readingSensor == NULL) { 
+    // Not currently scanning sensor list
+    unsigned long thisTime = micros();
+    if (thisTime - lastReadCycle < cycleInterval) return;
+    // Required time has elapsed since last read cycle started,
+    // so initiate new scan through the sensor list
+    readingSensor = firstSensor;
+    lastReadCycle = thisTime;
+  }
+  
+  // Loop until either end of list is encountered or we pause for some reason
+  byte sensorCount = 0;
+
+  while (readingSensor != NULL) {
+    bool pause=readingSensor->check();
+    // Move to next sensor in list.
+    readingSensor = readingSensor->nextSensor;
+    // Currently process max of 16 sensors per entry.
+    // Performance measurements taken during development indicate that, with 128 sensors configured
+    // on 8x 16-pin MCP23017 GPIO expanders with polling (no change notification), all inputs can be read from the devices
+    // within 1.4ms (400Mhz I2C bus speed), and a full cycle of checking 128 sensors for changes takes under a millisecond.
+    if (pause || (++sensorCount)>=16) return; 
+  }
+} 
+
+bool EXRAILSensor::check() {
+  // check for debounced change in this sensor 
+  inputState = RMFT2::readSensor(pin);
+
+  // Check if changed since last time, and process changes.
+  if (inputState == active) {// no change
+    latchDelay = minReadCount; // Reset counter
+    return false;  // no change 
+  }
+
+    // Change detected ... has it stayed changed for long enough
+    if (latchDelay > 0) {
+      latchDelay--;
+      return false; 
+    } 
+    
+    // change validated, act on it.
+    active = inputState;
+    latchDelay = minReadCount;  // Reset debounce counter
+    if (onChange || active) {
+      new RMFT2(progCounter);
+      return true;  // Don't check any more sensors on this entry
+    }
+    return false; 
+}
+
+EXRAILSensor::EXRAILSensor(VPIN _pin, int _progCounter, bool _onChange) {
+  // Add to the start of the list
+  //DIAG(F("ONthing vpin=%d at %d"), _pin, _progCounter);
+  nextSensor = firstSensor;
+  firstSensor = this;
+
+  pin=_pin;
+  progCounter=_progCounter;
+  onChange=_onChange;
+
+  IODevice::configureInput(pin, true);   
+  active = IODevice::read(pin);
+  inputState = active;
+  latchDelay = minReadCount;
+}
+
+EXRAILSensor *EXRAILSensor::firstSensor=NULL;
+EXRAILSensor *EXRAILSensor::readingSensor=NULL;
+unsigned long EXRAILSensor::lastReadCycle=0;

EXRAILSensor.h

@@ -0,0 +1,50 @@
+/*
+ *  © 2024 Chris Harlow
+ *  All rights reserved.
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef EXRAILSensor_h
+#define EXRAILSensor_h 
+#include "IODevice.h"
+class EXRAILSensor {
+  static EXRAILSensor * firstSensor;
+ static EXRAILSensor * readingSensor;
+ static unsigned long lastReadCycle;
+ 
+  public:
+  static void checkAll();
+  
+  EXRAILSensor(VPIN _pin, int _progCounter, bool _onChange);
+  bool check();
+  
+  private:
+  static const unsigned int cycleInterval = 10000; // min time between consecutive reads of each sensor in microsecs.
+                                                   // should not be less than device scan cycle time.
+  static const byte minReadCount = 4; // number of additional scans before acting on change
+                                        // E.g. 1 means that a change is ignored for one scan and actioned on the next.
+                                        // Max value is 63
+  
+  EXRAILSensor* nextSensor;
+  VPIN pin; 
+  int progCounter; 
+  bool active; 
+  bool inputState;
+  bool onChange;
+  byte latchDelay;
+};
+#endif

EthernetInterface.cpp

@@ -1,5 +1,12 @@
 /*
- *  © 2020,Gregor Baues,  Chris Harlow. All rights reserved.
+ *  © 2024 Morten "Doc" Nielsen
+ *  © 2023-2024 Paul M. Antoine
+ *  © 2022 Bruno Sanches
+ *  © 2021 Fred Decker
+ *  © 2020-2022 Harald Barth
+ *  © 2020-2024 Chris Harlow
+ *  © 2020 Gregor Baues
+ *  All rights reserved.
  *  
  *  This file is part of DCC-EX/CommandStation-EX
  *
@@ -22,72 +29,141 @@
 #include "EthernetInterface.h"
 #include "DIAG.h"
 #include "CommandDistributor.h"
+#include "WiThrottle.h"
 #include "DCCTimer.h"
+#if __has_include ( "MDNS_Generic.h")
+  #include "MDNS_Generic.h"
+  #define DO_MDNS 
+  EthernetUDP udp;
+  MDNS mdns(udp);
+#endif
+
+
+//extern void looptimer(unsigned long timeout, const FSH* message);
+#define looptimer(a,b)
+
+bool EthernetInterface::connected=false;
+EthernetServer * EthernetInterface::server= nullptr;
+EthernetClient EthernetInterface::clients[MAX_SOCK_NUM];                // accept up to MAX_SOCK_NUM client connections at the same time; This depends on the chipset used on the Shield
+bool EthernetInterface::inUse[MAX_SOCK_NUM];                // accept up to MAX_SOCK_NUM client connections at the same time; This depends on the chipset used on the Shield
+uint8_t EthernetInterface::buffer[MAX_ETH_BUFFER+1];                    // buffer used by TCP for the recv
+RingStream * EthernetInterface::outboundRing = nullptr;
 
-EthernetInterface * EthernetInterface::singleton=NULL;
 /**
  * @brief Setup Ethernet Connection
  * 
  */
-void EthernetInterface::setup()
-{
-    singleton=new EthernetInterface();
-    if (!singleton->connected) singleton=NULL; 
-};
 
-
-/**
- * @brief Aquire IP Address from DHCP and start server
- * 
- * @return true 
- * @return false 
- */
-EthernetInterface::EthernetInterface()
+void EthernetInterface::setup() 
 {
+  DIAG(F("Ethernet starting"
+  #ifdef DO_MDNS
+    " (with mDNS)"
+  #endif 
+    " Please be patient, especially if no cable is connected!"
+  ));
+  
+  #ifdef STM32_ETHERNET
+    // Set a HOSTNAME for the DHCP request - a nice to have, but hard it seems on LWIP for STM32
+    // The default is "lwip", which is **always** set in STM32Ethernet/src/utility/ethernetif.cpp
+    // for some reason. One can edit it to instead read:
+    //      #if LWIP_NETIF_HOSTNAME
+    //      /* Initialize interface hostname */
+    //      if (netif->hostname == NULL)
+    //         netif->hostname = "lwip";
+    //      #endif /* LWIP_NETIF_HOSTNAME */
+    // Which seems more useful! We should propose the patch... so the following line actually works!
+    netif_set_hostname(&gnetif, WIFI_HOSTNAME);   // Should probably be passed in the contructor...
+  #endif   
+
     byte mac[6];
     DCCTimer::getSimulatedMacAddress(mac);
-    connected=false;
-   
-    #ifdef IP_ADDRESS
-    Ethernet.begin(mac, IP_ADDRESS);
-    #else
-    if (Ethernet.begin(mac) == 0)
+  
+  #ifdef IP_ADDRESS
+    static IPAddress myIP(IP_ADDRESS);
+    Ethernet.begin(mac,myIP);
+  #else
+    if (Ethernet.begin(mac)==0)
+  {
+    LCD(4,F("IP: No DHCP"));
+    return;
+  }
+  #endif
+
+  auto ip = Ethernet.localIP();    // look what IP was obtained (dynamic or static)
+  if (!ip) {
+    LCD(4,F("IP: None"));
+    return;
+  }
+  server = new EthernetServer(IP_PORT); // Ethernet Server listening on default port IP_PORT
+  server->begin();
+
+  // Arrange display of IP address and port
+  #ifdef LCD_DRIVER
+    const byte lcdData[]={LCD_DRIVER};
+    const bool wideDisplay=lcdData[1]>=24; // data[1] is cols. 
+  #else 
+    const bool wideDisplay=true;
+  #endif    
+  if (wideDisplay) {
+    // OLEDS or just usb diag is ok on one line. 
+    LCD(4,F("IP %d.%d.%d.%d:%d"), ip[0], ip[1], ip[2], ip[3], IP_PORT);    
+  } 
+  else { // LCDs generally too narrow, so take 2 lines
+    LCD(4,F("IP %d.%d.%d.%d"), ip[0], ip[1], ip[2], ip[3]);
+    LCD(5,F("Port %d"), IP_PORT);
+  }
+ 
+  outboundRing=new RingStream(OUTBOUND_RING_SIZE);
+  #ifdef DO_MDNS
+    mdns.begin(Ethernet.localIP(), WIFI_HOSTNAME); // hostname
+    mdns.addServiceRecord(WIFI_HOSTNAME "._withrottle", IP_PORT, MDNSServiceTCP);
+  // Not sure if we need to run it once, but just in case!
+    mdns.run();
+  #endif  
+  connected=true;    
+}
+
+#if defined (STM32_ETHERNET)
+void EthernetInterface::acceptClient() { // STM32 version
+  auto client=server->available();
+  if (!client) return;
+  // check for existing client
+  for (byte socket = 0; socket < MAX_SOCK_NUM; socket++)
+    if (inUse[socket] && client == clients[socket]) return;
+      
+  // new client
+  for (byte socket = 0; socket < MAX_SOCK_NUM; socket++)
+  {
+    if (!inUse[socket])
     {
-        DIAG(F("Ethernet.begin FAILED"));
-        return;
-    } 
-    #endif
-    DIAG(F("begin OK."));
-     if (Ethernet.hardwareStatus() == EthernetNoHardware) {
-      DIAG(F("Ethernet shield not found"));
+      clients[socket] = client;
+      inUse[socket]=true;
+      if (Diag::ETHERNET)
+        DIAG(F("Ethernet: New client socket %d"), socket);
       return;
     }
-  
-    unsigned long startmilli = millis();
-    while ((millis() - startmilli) < 5500) // Loop to give time to check for cable connection
-    {
-        if (Ethernet.linkStatus() == LinkON)
-            break;
-        DIAG(F("Ethernet waiting for link (1sec) "));
-        delay(1000);
-    }
+  }
+  DIAG(F("Ethernet OVERFLOW"));
+}
+#else
+void EthernetInterface::acceptClient() { // non-STM32 version
+  auto client=server->accept();
+  if (!client) return;
+  auto socket=client.getSocketNumber();
+  clients[socket]=client;
+  inUse[socket]=true;
+  if (Diag::ETHERNET)
+    DIAG(F("Ethernet: New client socket %d"), socket);
+}
+#endif
 
-    if (Ethernet.linkStatus() == LinkOFF) {
-      DIAG(F("Ethernet cable not connected"));
-      return;
-    }
-    
-    connected=true;
-    
-    IPAddress ip = Ethernet.localIP(); // reassign the obtained ip address
-
-    server = new EthernetServer(IP_PORT); // Ethernet Server listening on default port IP_PORT
-    server->begin();
-  
-    LCD(4,F("IP: %d.%d.%d.%d"), ip[0], ip[1], ip[2], ip[3]);
-    LCD(5,F("Port:%d"), IP_PORT);
-
-    outboundRing=new RingStream(OUTBOUND_RING_SIZE);     
+void EthernetInterface::dropClient(byte socket) 
+{ 
+  clients[socket].stop();
+  inUse[socket]=false;
+  CommandDistributor::forget(socket);
+	if (Diag::ETHERNET)  DIAG(F("Ethernet: Disconnect %d "), socket);  
 }
 
 /**
@@ -96,91 +172,109 @@ EthernetInterface::EthernetInterface()
  */
 void EthernetInterface::loop()
 {
-    if (!singleton) return;
+    if (!connected) return;
+    looptimer(5000, F("E.loop"));
+	      
+    static bool warnedAboutLink=false;
+    if (Ethernet.linkStatus() == LinkOFF){
+        if (warnedAboutLink) return;
+        DIAG(F("Ethernet link OFF"));
+        warnedAboutLink=true;
+        return;
+    }
+    looptimer(5000, F("E.loop warn"));
+	  
+    // link status must be ok here 
+    if (warnedAboutLink) {
+      DIAG(F("Ethernet link RESTORED"));
+      warnedAboutLink=false;
+    } 
     
-    switch (Ethernet.maintain())
-    {
+  #ifdef DO_MDNS
+    // Always do this because we don't want traffic to intefere with being found!
+    mdns.run();
+    looptimer(5000, F("E.mdns"));
+	  
+  #endif
+
+    //
+    switch (Ethernet.maintain()) {
     case 1:
         //renewed fail
         DIAG(F("Ethernet Error: renewed fail"));
-        singleton=NULL;
+        connected=false;
         return;
-
     case 3:
         //rebind fail
         DIAG(F("Ethernet Error: rebind fail"));
-        singleton=NULL;
+        connected=false;
         return;
-
     default:
         //nothing happened
+        //DIAG(F("maintained"));
         break;
     }
-
-   singleton->loop2();
-
-}
-
- void EthernetInterface::loop2()
-{
+    looptimer(5000, F("E.maintain"));
+	  
     // get client from the server
-    EthernetClient client = server->accept();
-
-    // check for new client
-    if (client)
+    acceptClient();
+    
+    // handle disconnected sockets because STM32 library doesnt
+    // do the read==0 response.
+    for (byte socket = 0; socket < MAX_SOCK_NUM; socket++)
     {
-        if (Diag::ETHERNET) DIAG(F("Ethernet: New client "));
-        byte socket;
-        for (socket = 0; socket < MAX_SOCK_NUM; socket++)
-        {
-            if (!clients[socket])
-            {
-                // On accept() the EthernetServer doesn't track the client anymore
-                // so we store it in our client array
-                if (Diag::ETHERNET) DIAG(F("Socket %d"),socket);
-                clients[socket] = client;
-                break;
-            }
-        }
-        if (socket==MAX_SOCK_NUM) DIAG(F("new Ethernet OVERFLOW")); 
-    }
+      if (inUse[socket] && !clients[socket].connected()) dropClient(socket);
+    }  
 
     // check for incoming data from all possible clients
     for (byte socket = 0; socket < MAX_SOCK_NUM; socket++)
     {
-        if (clients[socket]) {
-        
-        int available=clients[socket].available();
-        if (available > 0) {
-            if (Diag::ETHERNET)  DIAG(F("Ethernet: available socket=%d,avail=%d"), socket, available);
-            // read bytes from a client
-            int count = clients[socket].read(buffer, MAX_ETH_BUFFER);
-            buffer[count] = '\0'; // terminate the string properly
-            if (Diag::ETHERNET) DIAG(F(",count=%d:%e"), socket,buffer);
-            // execute with data going directly back
-            outboundRing->mark(socket); 
-            CommandDistributor::parse(socket,buffer,outboundRing);
-            outboundRing->commit();
-            return; // limit the amount of processing that takes place within 1 loop() cycle. 
-          }
-        }
+      if (!inUse[socket]) continue; // socket is not in use
+	
+	    // read any bytes from this client
+	    auto count = clients[socket].read(buffer, MAX_ETH_BUFFER);
+      
+      if (count<0) continue;  // -1 indicates nothing to read
+	    
+      if (count > 0) {  // we have incoming data 
+	      buffer[count] = '\0'; // terminate the string properly
+	      if (Diag::ETHERNET) DIAG(F("Ethernet s=%d, c=%d b=:%e"), socket, count, buffer);
+	      // execute with data going directly back
+	      CommandDistributor::parse(socket,buffer,outboundRing);
+	      //looptimer(5000, F("Ethloop2 parse"));
+	      return; // limit the amount of processing that takes place within 1 loop() cycle. 
+	    }
+	    
+      // count=0 The client has disconnected
+	    dropClient(socket);
     }
+	
+    WiThrottle::loop(outboundRing);
 
-    // stop any clients which disconnect
-   for (int socket = 0; socket<MAX_SOCK_NUM; socket++) {
-     if (clients[socket] && !clients[socket].connected()) {
-      clients[socket].stop();
-      if (Diag::ETHERNET)  DIAG(F("Ethernet: disconnect %d "), socket);             
-     }
+    // handle at most 1 outbound transmission 
+    auto socketOut=outboundRing->read();
+    if (socketOut<0) return;  // no outbound pending
+
+    if (socketOut >= MAX_SOCK_NUM) {
+      // This is a catastrophic code failure and unrecoverable.  
+      DIAG(F("Ethernet outboundRing s=%d error"), socketOut);
+      connected=false;
+      return;
+    } 
+
+    auto count=outboundRing->count();
+    {
+	    char tmpbuf[count+1]; // one extra for '\0'
+	    for(int i=0;i<count;i++) {
+	      tmpbuf[i] = outboundRing->read();
+	    }
+	    tmpbuf[count]=0;
+      if (inUse[socketOut]) {
+  	    if (Diag::ETHERNET) DIAG(F("Ethernet reply s=%d, c=%d, b:%e"),
+                              socketOut,count,tmpbuf);
+	      clients[socketOut].write(tmpbuf,count);
+      }
     }
     
-    // handle at most 1 outbound transmission 
-    int socketOut=outboundRing->read();
-    if (socketOut>=0) {
-      int count=outboundRing->count();
-      if (Diag::ETHERNET) DIAG(F("Ethernet reply socket=%d, count=:%d"), socketOut,count);
-      for(;count>0;count--)  clients[socketOut].write(outboundRing->read());
-      clients[socketOut].flush(); //maybe 
-    }
 }
 #endif

EthernetInterface.h

@@ -1,5 +1,12 @@
 /*
- *  © 2020,Gregor Baues,  Chris Harlow. All rights reserved.
+ *  © 2023-2024 Paul M. Antoine
+ *  © 2021 Neil McKechnie
+ *  © 2021 Mike S
+ *  © 2021 Fred Decker
+ *  © 2020-2022 Harald Barth
+ *  © 2020-2024 Chris Harlow
+ *  © 2020 Gregor Baues
+ *  All rights reserved.
  *  
  *  This file is part of DCC-EX/CommandStation-EX
  *
@@ -23,13 +30,22 @@
 #ifndef EthernetInterface_h
 #define EthernetInterface_h
 
-#include "defines.h")
+#include "defines.h"
 #include "DCCEXParser.h"
 #include <Arduino.h>
-#include <avr/pgmspace.h>
+//#include <avr/pgmspace.h>
 #if defined (ARDUINO_TEENSY41)
  #include <NativeEthernet.h>         //TEENSY Ethernet Treiber
  #include <NativeEthernetUdp.h>   
+ #define MAX_SOCK_NUM 4
+#elif defined (ARDUINO_NUCLEO_F429ZI) || defined (ARDUINO_NUCLEO_F439ZI) || defined (ARDUINO_NUCLEO_F4X9ZI)
+ #include <LwIP.h>
+//  #include "STM32lwipopts.h"
+ #include <STM32Ethernet.h>
+ #include <lwip/netif.h>
+ extern "C" struct netif gnetif;
+ #define STM32_ETHERNET
+ #define MAX_SOCK_NUM 8
 #else
  #include "Ethernet.h"
 #endif
@@ -40,7 +56,7 @@
  * 
  */
 
-#define MAX_ETH_BUFFER 512
+#define MAX_ETH_BUFFER 128
 #define OUTBOUND_RING_SIZE 2048
 
 class EthernetInterface {
@@ -51,15 +67,15 @@ class EthernetInterface {
      static void loop();
    
  private:
-     static EthernetInterface * singleton;
-     bool connected;
-     EthernetInterface();
-     void loop2();
-    EthernetServer * server;
-    EthernetClient clients[MAX_SOCK_NUM];                // accept up to MAX_SOCK_NUM client connections at the same time; This depends on the chipset used on the Shield
-    uint8_t buffer[MAX_ETH_BUFFER+1];                    // buffer used by TCP for the recv
-    RingStream * outboundRing;
-  
+    static bool connected;
+    static EthernetServer * server;
+    static EthernetClient clients[MAX_SOCK_NUM];                // accept up to MAX_SOCK_NUM client connections at the same time; This depends on the chipset used on the Shield
+    static bool inUse[MAX_SOCK_NUM];                // accept up to MAX_SOCK_NUM client connections at the same time; This depends on the chipset used on the Shield
+    static uint8_t buffer[MAX_ETH_BUFFER+1];                    // buffer used by TCP for the recv
+    static RingStream * outboundRing;
+    static void acceptClient();
+    static void dropClient(byte socketnum);
+    
 };
 
 #endif

FSH.h

@@ -1,5 +1,9 @@
 /*
- *  (c) 2021 Fred Decker.  All rights reserved.
+ *  © 2022 Paul M. Antoine
+ *  © 2021 Neil McKechnie
+ *  © 2021 Harald Barth
+ *  © 2021 Fred Decker
+ *  All rights reserved.
  *  
  *  This file is part of CommandStation-EX
  *
@@ -30,24 +34,71 @@
  *  PROGMEM                 use FLASH instead
  *  pgm_read_byte_near      use GETFLASH instead.
  *  pgm_read_word_near      use GETFLASHW instead.
+ * 
+ *  Also:
+ *    HIGHFLASH    -  PROGMEM forced to end of link so needs far pointers.
+ *    GETHIGHFLASH,GETHIGHFLASHW to access them
  *  
  */
 #include <Arduino.h>
-#if defined(ARDUINO_ARCH_MEGAAVR)
+#ifdef ARDUINO_ARCH_AVR
+// AVR devices have flash memory mapped differently
+// progmem can be accessed by _near functions or _far
+typedef __FlashStringHelper FSH;
+#define FLASH PROGMEM
+#define GETFLASH(addr) pgm_read_byte_near(addr)
+#define STRCPY_P strcpy_P
+#define STRCMP_P strcmp_P
+#define STRNCPY_P strncpy_P
+#define STRNCMP_P strncmp_P
+#define STRLEN_P strlen_P
+#define STRCHR_P strchr_P 
+
+#if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)
+// AVR_MEGA memory deliberately placed at end of link may need _far functions
+#define HIGHFLASH __attribute__((section(".fini2")))
+#define HIGHFLASH3 __attribute__((section(".fini3")))
+#define GETFARPTR(data) pgm_get_far_address(data)
+#define GETHIGHFLASH(data,offset) pgm_read_byte_far(GETFARPTR(data)+offset)
+#define GETHIGHFLASHW(data,offset) pgm_read_word_far(GETFARPTR(data)+offset)
+#define COPYHIGHFLASH(target,base,offset,length) \
+  memcpy_PF(target,GETFARPTR(base) + offset,length)  
+#else
+// AVR_UNO/NANO runtime does not support _far functions so just use _near equivalent
+// as there is no progmem above 32kb anyway.
+#define HIGHFLASH PROGMEM
+#define HIGHFLASH3 PROGMEM
+#define GETFARPTR(data) ((uint32_t)(data))
+#define GETHIGHFLASH(data,offset) pgm_read_byte_near(GETFARPTR(data)+(offset))
+#define GETHIGHFLASHW(data,offset) pgm_read_word_near(GETFARPTR(data)+(offset))
+#define COPYHIGHFLASH(target,base,offset,length) \
+  memcpy_P(target,(byte *)base + offset,length)  
+#endif
+
+#else 
+// Non-AVR Flat-memory devices have no need of this support so can be remapped to normal memory access
 #ifdef F
   #undef F
 #endif
+#ifdef FLASH
+  #undef FLASH
+#endif
 #define F(str) (str)
 typedef char FSH; 
-#define GETFLASH(addr) (*(const unsigned char *)(addr))
-#define GETFLASHW(addr) (*(const unsigned short *)(addr))
 #define FLASH
-#define strlen_P strlen
-#define strcpy_P strcpy
-#else 
-typedef __FlashStringHelper FSH;
-#define GETFLASH(addr) pgm_read_byte_near(addr)
-#define GETFLASHW(addr) pgm_read_word_near(addr)
-#define FLASH PROGMEM
+#define HIGHFLASH
+#define HIGHFLASH3
+#define GETFARPTR(data) ((uint32_t)(data))
+#define GETFLASH(addr) (*(const byte *)(addr))
+#define GETHIGHFLASH(data,offset)  (*(const byte *)(GETFARPTR(data)+offset))
+#define GETHIGHFLASHW(data,offset) (*(const uint16_t *)(GETFARPTR(data)+offset))
+#define COPYHIGHFLASH(target,base,offset,length) \
+  memcpy(target,(byte *)&base + offset,length)  
+#define STRCPY_P strcpy
+#define STRCMP_P strcmp
+#define STRNCPY_P strncpy
+#define STRNCMP_P strncmp
+#define STRLEN_P strlen
+#define STRCHR_P strchr
 #endif
 #endif

GITHUB_SHA.h

@@ -1 +1 @@
-#define GITHUB_SHA "37904b5"
+#define GITHUB_SHA "devel-202504182148Z"

I2CManager.cpp

@@ -1,5 +1,7 @@
 /*
- *  © 2021, Neil McKechnie. All rights reserved.
+ *  © 2023, Neil McKechnie
+ *  © 2022 Paul M Antoine
+ *  All rights reserved.
  *
  *  This file is part of CommandStation-EX
  *
@@ -30,28 +32,140 @@
 #elif defined(ARDUINO_ARCH_MEGAAVR) 
 #include "I2CManager_NonBlocking.h"
 #include "I2CManager_Mega4809.h"  // NanoEvery/UnoWifi
+#elif defined(ARDUINO_ARCH_SAMD)
+#include "I2CManager_NonBlocking.h"
+#include "I2CManager_SAMD.h"      // SAMD21 for now... SAMD51 as well later
+#elif defined(ARDUINO_ARCH_STM32)
+#include "I2CManager_NonBlocking.h"
+#include "I2CManager_STM32.h"      // STM32F411RE for now... more later
 #else
 #define I2C_USE_WIRE
 #include "I2CManager_Wire.h"      // Other platforms
 #endif
 
 
+// Helper function for listing device types
+static const FSH * guessI2CDeviceType(uint8_t address) {
+  if (address == 0x1A)
+    // 0x09-0x18 selectable, but for now handle the default
+    return F("Piicodev 865/915MHz Transceiver");
+  if (address == 0x1C)
+    return F("QMC6310 Magnetometer");
+  if (address >= 0x20 && address <= 0x26)
+    return F("GPIO Expander");
+  if (address == 0x27)
+    return F("GPIO Expander or LCD Display");
+  if (address == 0x29)
+    return F("Time-of-flight sensor");
+  if (address == 0x34)
+    return F("TCA8418 keypad scanner");
+  if (address >= 0x3c && address <= 0x3d)
+    // 0x3c can also be an HMC883L magnetometer
+    return F("OLED Display or HMC583L Magnetometer");
+  if (address >= 0x48 && address <= 0x57) // SC16IS752x UART detection
+    return F("SC16IS75x UART");
+  if (address >= 0x48 && address <= 0x4f)
+    return F("Analogue Inputs or PWM");
+  if (address >= 0x40 && address <= 0x4f)
+    return F("PWM");
+  if (address >= 0x50 && address <= 0x5f) 
+    return F("EEPROM"); 
+  if (address >= 0x60 && address <= 0x68) 
+    return F("Adafruit NeoPixel Driver"); 
+  if (address == 0x68) 
+    return F("Real-time clock"); 
+  if (address >= 0x70 && address <= 0x77)
+    return F("I2C Mux");
+  // Unknown type
+    return F("?");
+}
+
 // If not already initialised, initialise I2C
 void I2CManagerClass::begin(void) {
-  //setTimeout(25000); // 25 millisecond timeout
   if (!_beginCompleted) {
     _beginCompleted = true;
+
+    // Check for short-circuit or floating lines (no pull-up) on I2C before enabling I2C
+    const FSH *message = F("WARNING: Check I2C %S line for short/pullup");
+    pinMode(SDA, INPUT);
+    if (!digitalRead(SDA))
+      DIAG(message, F("SDA"));
+    pinMode(SCL, INPUT);
+    if (!digitalRead(SCL))
+      DIAG(message, F("SCL"));
+
+    // Now initialise I2C
     _initialise();
 
-    // Probe and list devices.
+    #if defined(I2C_USE_WIRE)
+    DIAG(F("I2CManager: Using Wire library"));
+    #endif
+
+    // Probe and list devices.  Use standard mode 
+    //  (clock speed 100kHz) for best device compatibility.
+    _setClock(100000);
+    uint32_t originalTimeout = _timeout;
+    setTimeout(1000);       // use 1ms timeout for probes
+
+  #if defined(I2C_EXTENDED_ADDRESS)
+    // First count the multiplexers and switch off all subbuses
+    _muxCount = 0;
+    for (uint8_t muxNo=I2CMux_0; muxNo <= I2CMux_7; muxNo++) {
+      if (I2CManager.muxSelectSubBus({(I2CMux)muxNo, SubBus_None})==I2C_STATUS_OK)
+        _muxCount++;
+    }
+  #endif
+
+    // Enumerate devices that are visible
     bool found = false;
-    for (byte addr=1; addr<127; addr++) {
+    for (uint8_t addr=0x08; addr<0x78; addr++) {
       if (exists(addr)) {
         found = true; 
-        DIAG(F("I2C Device found at x%x"), addr);
+        DIAG(F("I2C Device found at 0x%x, %S?"), addr, guessI2CDeviceType(addr));
       }
     }
+
+#if defined(I2C_EXTENDED_ADDRESS)
+    // Enumerate all I2C devices that are connected via multiplexer, 
+    // i.e. that respond when only one multiplexer has one subBus enabled
+    // and the device doesn't respond when the mux subBus is disabled.
+    // If any probes time out, then assume that the subbus is dead and
+    // don't do any more on that subbus.
+    for (uint8_t muxNo=I2CMux_0; muxNo <= I2CMux_7; muxNo++) {
+      uint8_t muxAddr = I2C_MUX_BASE_ADDRESS + muxNo;
+      if (exists(muxAddr)) {
+        // Select Mux Subbus
+        for (uint8_t subBus=0; subBus<=SubBus_No; subBus++) {
+          muxSelectSubBus({(I2CMux)muxNo, (I2CSubBus)subBus});
+          for (uint8_t addr=0x08; addr<0x78; addr++) {
+            uint8_t status = checkAddress(addr);
+            if (status == I2C_STATUS_OK) {
+              // De-select subbus
+              muxSelectSubBus({(I2CMux)muxNo, SubBus_None});
+              if (!exists(addr)) {
+                // Device responds when subbus selected but not when
+                // subbus disabled - ergo it must be on subbus!
+                found = true; 
+                DIAG(F("I2C Device found at {I2CMux_%d,SubBus_%d,0x%x}, %S?"), 
+                  muxNo, subBus, addr, guessI2CDeviceType(addr));
+              }
+              // Re-select subbus
+              muxSelectSubBus({(I2CMux)muxNo, (I2CSubBus)subBus});
+            } else if (status == I2C_STATUS_TIMEOUT) {
+              // Bus stuck, skip to next one.
+              break;
+            }
+          }
+        }
+        // Deselect all subBuses for this mux.  Otherwise its devices will continue to
+        // respond when other muxes are being probed.
+        I2CManager.muxSelectSubBus({(I2CMux)muxNo, SubBus_None});  // Deselect Mux
+      } 
+    }
+#endif
     if (!found) DIAG(F("No I2C Devices found"));
+    _setClock(_clockSpeed);
+    setTimeout(originalTimeout);      // set timeout back to original
   }
 }
 
@@ -60,31 +174,35 @@ void I2CManagerClass::begin(void) {
 void I2CManagerClass::setClock(uint32_t speed) {
   if (speed < _clockSpeed && !_clockSpeedFixed) {
     _clockSpeed = speed;
+    DIAG(F("I2C clock speed set to %l Hz"), _clockSpeed);
   }
   _setClock(_clockSpeed);
 }
 
-// Force clock speed to that specified.  It can then only 
-// be overridden by calling Wire.setClock directly.
+// Force clock speed to that specified.
 void I2CManagerClass::forceClock(uint32_t speed) {
-  if (!_clockSpeedFixed) {
-    _clockSpeed = speed;
-    _clockSpeedFixed = true;
-    _setClock(_clockSpeed);
-  }
+  _clockSpeed = speed;
+  _clockSpeedFixed = true;
+  _setClock(_clockSpeed);
+  DIAG(F("I2C clock speed forced to %l Hz"), _clockSpeed);
 }
 
 // Check if specified I2C address is responding (blocking operation)
 // Returns I2C_STATUS_OK (0) if OK, or error code.
-uint8_t I2CManagerClass::checkAddress(uint8_t address) {
-  return write(address, NULL, 0);
+// Suppress retries.  If it doesn't respond first time it's out of the running.
+uint8_t I2CManagerClass::checkAddress(I2CAddress address) {
+  I2CRB rb;
+  rb.setWriteParams(address, NULL, 0);
+  rb.suppressRetries(true);
+  queueRequest(&rb);
+  return rb.wait();
 }
 
 
 /***************************************************************************
  *  Write a transmission to I2C using a list of data (blocking operation)
  ***************************************************************************/
-uint8_t I2CManagerClass::write(uint8_t address, uint8_t nBytes, ...) {
+uint8_t I2CManagerClass::write(I2CAddress address, uint8_t nBytes, ...) {
   uint8_t buffer[nBytes];
   va_list args;
   va_start(args, nBytes);
@@ -97,7 +215,7 @@ uint8_t I2CManagerClass::write(uint8_t address, uint8_t nBytes, ...) {
 /***************************************************************************
  *  Initiate a write to an I2C device (blocking operation)
  ***************************************************************************/
-uint8_t I2CManagerClass::write(uint8_t i2cAddress, const uint8_t writeBuffer[], uint8_t writeLen) {
+uint8_t I2CManagerClass::write(I2CAddress i2cAddress, const uint8_t writeBuffer[], uint8_t writeLen) {
   I2CRB req;
   uint8_t status = write(i2cAddress, writeBuffer, writeLen, &req);
   return finishRB(&req, status);
@@ -106,7 +224,7 @@ uint8_t I2CManagerClass::write(uint8_t i2cAddress, const uint8_t writeBuffer[],
 /***************************************************************************
  *  Initiate a write from PROGMEM (flash) to an I2C device (blocking operation)
  ***************************************************************************/
-uint8_t I2CManagerClass::write_P(uint8_t i2cAddress, const uint8_t * data, uint8_t dataLen) {
+uint8_t I2CManagerClass::write_P(I2CAddress i2cAddress, const uint8_t * data, uint8_t dataLen) {
   I2CRB req;
   uint8_t status = write_P(i2cAddress, data, dataLen, &req);
   return finishRB(&req, status);
@@ -115,7 +233,7 @@ uint8_t I2CManagerClass::write_P(uint8_t i2cAddress, const uint8_t * data, uint8
 /***************************************************************************
  *  Initiate a write (optional) followed by a read from the I2C device (blocking operation)
  ***************************************************************************/
-uint8_t I2CManagerClass::read(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t readLen, 
+uint8_t I2CManagerClass::read(I2CAddress i2cAddress, uint8_t *readBuffer, uint8_t readLen, 
     const uint8_t *writeBuffer, uint8_t writeLen)
 {
   I2CRB req;
@@ -126,7 +244,7 @@ uint8_t I2CManagerClass::read(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t r
 /***************************************************************************
  *  Overload of read() to allow command to be specified as a series of bytes (blocking operation)
  ***************************************************************************/
-uint8_t I2CManagerClass::read(uint8_t address, uint8_t readBuffer[], uint8_t readSize, 
+uint8_t I2CManagerClass::read(I2CAddress address, uint8_t readBuffer[], uint8_t readSize, 
                                   uint8_t writeSize, ...) {
   va_list args;
   // Copy the series of bytes into an array.
@@ -157,7 +275,7 @@ const FSH *I2CManagerClass::getErrorMessage(uint8_t status) {
     case I2C_STATUS_NEGATIVE_ACKNOWLEDGE: return F("No response from device (address NAK)");
     case I2C_STATUS_TRANSMIT_ERROR: return F("Transmit error (data NAK)");
     case I2C_STATUS_OTHER_TWI_ERROR: return F("Other Wire/TWI error");
-    case I2C_STATUS_TIMEOUT: return F("Timeout");
+    case I2C_STATUS_TIMEOUT: return F("I2C bus timeout");
     case I2C_STATUS_ARBITRATION_LOST: return F("Arbitration lost");
     case I2C_STATUS_BUS_ERROR: return F("I2C bus error");
     case I2C_STATUS_UNEXPECTED_ERROR: return F("Unexpected error");
@@ -171,46 +289,40 @@ const FSH *I2CManagerClass::getErrorMessage(uint8_t status) {
  ***************************************************************************/
 I2CManagerClass I2CManager = I2CManagerClass();
 
+// Buffer for conversion of I2CAddress to char*.
+/* static */ char I2CAddress::addressBuffer[30];
 
 /////////////////////////////////////////////////////////////////////////////
 // Helper functions associated with I2C Request Block
 /////////////////////////////////////////////////////////////////////////////
 
 /***************************************************************************
- *  Block waiting for request block to complete, and return completion status.
- *  Since such a loop could potentially last for ever if the RB status doesn't
- *  change, we set a high limit (1sec, 1000ms) on the wait time and, if it
- *  hasn't changed by that time we assume it's not going to, and just return
- *  a timeout status.  This means that CS will not lock up.
+ *  Block waiting for request to complete, and return completion status.
+ *  Timeout monitoring is performed in the I2CManager.loop() function.
  ***************************************************************************/
 uint8_t I2CRB::wait() {
-  unsigned long waitStart = millis();
-  do {
+  while (status==I2C_STATUS_PENDING) {
     I2CManager.loop();
-    // Rather than looping indefinitely, let's set a very high timeout (1s).
-    if ((millis() - waitStart) > 1000UL) { 
-      DIAG(F("I2C TIMEOUT I2C:x%x I2CRB:x%x"), i2cAddress, this);
-      status = I2C_STATUS_TIMEOUT;
-      // Note that, although the timeout is posted, the request may yet complete.
-      // TODO: Ideally we would like to cancel the request.
-      return status;
-    }
-  } while (status==I2C_STATUS_PENDING);
+  };
   return status;
 }
 
 /***************************************************************************
  *  Check whether request is still in progress.
+ *  Timeout monitoring is performed in the I2CManager.loop() function.
  ***************************************************************************/
 bool I2CRB::isBusy() {
-  I2CManager.loop();
-  return (status==I2C_STATUS_PENDING);
+  if (status==I2C_STATUS_PENDING) {
+    I2CManager.loop();
+    return true;
+  } else
+    return false;
 }
 
 /***************************************************************************
  *  Helper functions to fill the I2CRequest structure with parameters.
  ***************************************************************************/
-void I2CRB::setReadParams(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t readLen) {
+void I2CRB::setReadParams(I2CAddress i2cAddress, uint8_t *readBuffer, uint8_t readLen) {
   this->i2cAddress = i2cAddress;
   this->writeLen = 0;
   this->readBuffer = readBuffer;
@@ -219,7 +331,7 @@ void I2CRB::setReadParams(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t readL
   this->status = I2C_STATUS_OK;
 }
 
-void I2CRB::setRequestParams(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t readLen, 
+void I2CRB::setRequestParams(I2CAddress i2cAddress, uint8_t *readBuffer, uint8_t readLen, 
     const uint8_t *writeBuffer, uint8_t writeLen) {
   this->i2cAddress = i2cAddress;
   this->writeBuffer = writeBuffer;
@@ -230,7 +342,7 @@ void I2CRB::setRequestParams(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t re
   this->status = I2C_STATUS_OK;
 }
 
-void I2CRB::setWriteParams(uint8_t i2cAddress, const uint8_t *writeBuffer, uint8_t writeLen) {
+void I2CRB::setWriteParams(I2CAddress i2cAddress, const uint8_t *writeBuffer, uint8_t writeLen) {
   this->i2cAddress = i2cAddress;
   this->writeBuffer = writeBuffer;
   this->writeLen = writeLen;
@@ -239,3 +351,28 @@ void I2CRB::setWriteParams(uint8_t i2cAddress, const uint8_t *writeBuffer, uint8
   this->status = I2C_STATUS_OK;
 }
 
+void I2CRB::suppressRetries(bool suppress) {
+  if (suppress)
+    this->operation |= OPERATION_NORETRY;
+  else
+    this->operation &= ~OPERATION_NORETRY;
+}
+
+
+// Helper function for converting a uint8_t to four characters (e.g. 0x23).
+void I2CAddress::toHex(const uint8_t value, char *buffer) {
+  char *ptr = buffer;
+  // Just display hex value, two digits.
+  *ptr++ = '0';
+  *ptr++ = 'x';
+  uint8_t bits = (value >> 4) & 0xf;
+  *ptr++ = bits > 9 ? bits-10+'a' : bits+'0';
+  bits = value & 0xf;
+  *ptr++ = bits > 9 ? bits-10+'a' : bits+'0';
+}
+
+#if !defined(I2C_EXTENDED_ADDRESS) 
+
+/* static */ bool I2CAddress::_addressWarningDone = false;
+
+#endif

I2CManager.h

@@ -1,5 +1,6 @@
 /*
- *  © 2021, Neil McKechnie. All rights reserved.
+ *  © 2023, Neil McKechnie. All rights reserved.
+ *  © 2022 Paul M Antoine
  *
  *  This file is part of CommandStation-EX
  *
@@ -22,13 +23,15 @@
 
 #include <inttypes.h>
 #include "FSH.h"
+#include "defines.h"
+#include "DIAG.h"
 
 /* 
  * Manager for I2C communications.  For portability, it allows use 
  * of the Wire class, but also has a native implementation for AVR
  * which supports non-blocking queued I/O requests.
  * 
- * Helps to avoid calling Wire.begin() multiple times (which is not)
+ * Helps to avoid calling Wire.begin() multiple times (which is not
  * entirely benign as it reinitialises).
  * 
  * Also helps to avoid the Wire clock from being set, by another device
@@ -75,12 +78,12 @@
  * Timeout monitoring is possible, but requires that the following call is made
  * reasonably frequently in the program's loop() function:
  *  I2CManager.loop();
+ * So that the application doesn't need to do this explicitly, this call is performed
+ * from the I2CRB::isBusy() or I2CRB::wait() functions.
  * 
  */
 
 /* 
- * Future enhancement possibility:
- *
  *  I2C Multiplexer (e.g. TCA9547, TCA9548)
  * 
  *  A multiplexer offers a way of extending the address range of I2C devices.  For example, GPIO extenders use address range 0x20-0x27
@@ -93,29 +96,263 @@
  *  Thirdly, the multiplexer offers the ability to use mixed-speed devices more effectively, by allowing high-speed devices to be
  *  put on a different bus to low-speed devices, enabling the software to switch the I2C speed on-the-fly between I2C transactions.
  * 
- *  Changes required:  Increase the size of the I2CAddress field in the IODevice class from uint8_t to uint16_t.
- *  The most significant byte would contain a '1' bit flag, the multiplexer number (0-7) and bus number (0-7).  Then, when performing
- *  an I2C operation, the I2CManager would check this byte and, if zero, do what it currently does.  If the byte is non-zero, then
- *  that means the device is connected via a multiplexer so the I2C transaction should be preceded by a select command issued to the
- *  relevant multiplexer.
  * 
  *  Non-interrupting I2C:
  * 
- *  I2C may be operated without interrupts (undefine I2C_USE_INTERRUPTS).  Instead, the I2C state
+ *  Non-blocking I2C may be operated without interrupts (undefine I2C_USE_INTERRUPTS).  Instead, the I2C state
  *  machine handler, currently invoked from the interrupt service routine, is invoked from the loop() function.
  *  The speed at which I2C operations can be performed then becomes highly dependent on the frequency that 
  *  the loop() function is called, and may be adequate under some circumstances.  
  *  The advantage of NOT using interrupts is that the impact of I2C upon the DCC waveform (when accurate timing mode isn't in use)
  *  becomes almost zero.
- *  This mechanism is under evaluation and should not be relied upon as yet.
  * 
  */
 
+// Maximum number of retries on an I2C operation.
+// A value of zero will disable retries.
+// Maximum value is 254 (unsigned byte counter)
+// Note that timeout failures are not retried, but any timeout
+// configured applies to each try separately.
+#define MAX_I2C_RETRIES 2
+
+// Add following line to config.h to enable Wire library instead of native I2C drivers
 //#define I2C_USE_WIRE
+
+// Add following line to config.h to disable the use of interrupts by the native I2C drivers.
+//#define I2C_NO_INTERRUPTS
+
+// Default to use interrupts within the native I2C drivers.
 #ifndef I2C_NO_INTERRUPTS
 #define I2C_USE_INTERRUPTS
 #endif
 
+// I2C Extended Address support I2C Multiplexers and allows various properties to be 
+// associated with an I2C address such as the MUX and SubBus.  In the future, this
+// may be extended to include multiple buses, and other features. 
+// Uncomment to enable extended address.
+//
+
+//#define I2C_EXTENDED_ADDRESS
+
+/////////////////////////////////////////////////////////////////////////////////////
+// Extended I2C Address type to facilitate extended I2C addresses including
+// I2C multiplexer support.
+/////////////////////////////////////////////////////////////////////////////////////
+
+// Currently only one bus supported, and one instance of I2CManager to handle it.
+enum I2CBus : uint8_t {
+    I2CBus_0 = 0,
+};
+
+// Currently I2CAddress supports one I2C bus, with up to eight
+// multipexers (MUX) attached.  Each MUX can have up to eight sub-buses.
+enum I2CMux : uint8_t {
+  I2CMux_0 = 0,
+  I2CMux_1 = 1,
+  I2CMux_2 = 2,
+  I2CMux_3 = 3,
+  I2CMux_4 = 4,
+  I2CMux_5 = 5,
+  I2CMux_6 = 6,
+  I2CMux_7 = 7,
+  I2CMux_None = 255,   // Address doesn't need mux switching
+};
+  
+enum I2CSubBus : uint8_t {
+  SubBus_0 = 0,        // Enable individual sub-buses...
+  SubBus_1 = 1,
+#if !defined(I2CMUX_PCA9542)
+  SubBus_2 = 2,
+  SubBus_3 = 3,
+#if !defined(I2CMUX_PCA9544)
+  SubBus_4 = 4,
+  SubBus_5 = 5,
+  SubBus_6 = 6,
+  SubBus_7 = 7,
+#endif
+#endif
+  SubBus_No,           // Number of subbuses (highest + 1)
+  SubBus_None = 254,   // Disable all sub-buses on selected mux
+  SubBus_All = 255,    // Enable all sub-buses (not supported by some multiplexers)
+};
+
+// Type to hold I2C address
+#if defined(I2C_EXTENDED_ADDRESS)
+
+// First MUX address (they range between 0x70-0x77).
+#define I2C_MUX_BASE_ADDRESS 0x70
+
+// Currently I2C address supports one I2C bus, with up to eight
+// multiplexers (MUX) attached.  Each MUX can have up to eight sub-buses.
+// This structure could be extended in the future (if there is a need) 
+// to support 10-bit I2C addresses, different I2C clock speed for each
+// sub-bus, multiple I2C buses, and other features not yet thought of.
+struct I2CAddress {
+private:
+  // Fields
+  I2CBus _busNumber;
+  I2CMux _muxNumber;
+  I2CSubBus _subBus;
+  uint8_t _deviceAddress;
+  static char addressBuffer[];
+public:
+  // Constructors
+  // For I2CAddress "{I2CBus_0, Mux_0, SubBus_0, 0x23}" syntax.
+  I2CAddress(const I2CBus busNumber, const I2CMux muxNumber, const I2CSubBus subBus, const uint8_t deviceAddress) {
+    _busNumber = busNumber;
+    _muxNumber = muxNumber;
+    _subBus = subBus;
+    _deviceAddress = deviceAddress;
+  }
+
+  // Basic constructor
+  I2CAddress() : I2CAddress(I2CMux_None, SubBus_None, 0) {}
+
+  // For I2CAddress "{Mux_0, SubBus_0, 0x23}" syntax.
+  I2CAddress(const I2CMux muxNumber, const I2CSubBus subBus, const uint8_t deviceAddress) :
+    I2CAddress(I2CBus_0, muxNumber, subBus, deviceAddress) {}
+
+  // For I2CAddress in form "{SubBus_0, 0x23}" - assume Mux0 (0x70)
+  I2CAddress(I2CSubBus subBus, uint8_t deviceAddress) : 
+    I2CAddress(I2CMux_0, subBus, deviceAddress) {}
+
+  // Conversion from uint8_t to I2CAddress
+  // For I2CAddress in form "0x23"
+  // (device assumed to be on the main I2C bus).
+  I2CAddress(const uint8_t deviceAddress) : 
+    I2CAddress(I2CMux_None, SubBus_None, deviceAddress) {}
+    
+  // Conversion from uint8_t to I2CAddress
+  // For I2CAddress in form "{I2CBus_1, 0x23}"
+  // (device not connected via multiplexer).
+  I2CAddress(const I2CBus bus, const uint8_t deviceAddress) : 
+    I2CAddress(bus, I2CMux_None, SubBus_None, deviceAddress) {}
+
+  // For I2CAddress in form "{I2CMux_0, SubBus_0}" (mux selector)
+  I2CAddress(const I2CMux muxNumber, const I2CSubBus subBus) :
+    I2CAddress(muxNumber, subBus, 0x00) {}
+
+  // For I2CAddress in form "{i2cAddress, deviceAddress}"
+  // where deviceAddress is to be on the same subbus as i2cAddress.
+  I2CAddress(I2CAddress firstAddress, uint8_t newDeviceAddress) :
+    I2CAddress(firstAddress._muxNumber, firstAddress._subBus, newDeviceAddress) {}
+
+  // Conversion operator from I2CAddress to uint8_t
+  // For "uint8_t address = i2cAddress;" syntax
+  // (device assumed to be on the main I2C bus or on a currently selected subbus.
+  operator uint8_t () const { return _deviceAddress; }
+
+  // Conversion from I2CAddress to char* (uses static storage so only 
+  // one conversion can be done at a time).  So don't call it twice in a
+  // single DIAG statement for example.
+  const char* toString() { 
+    char *ptr = addressBuffer;
+    if (_muxNumber != I2CMux_None) {
+      strcpy_P(ptr, (const char*)F("{I2CMux_"));
+      ptr += 8;
+      *ptr++ = '0' + _muxNumber;
+      strcpy_P(ptr, (const char*)F(",Subbus_"));
+      ptr += 8;
+      if (_subBus == SubBus_None) {
+        strcpy_P(ptr, (const char*)F("None"));
+        ptr += 4;
+      } else if (_subBus == SubBus_All) {
+        strcpy_P(ptr, (const char*)F("All"));
+        ptr += 3;
+      } else 
+        *ptr++ = '0' + _subBus;
+      *ptr++ = ',';
+    }
+    toHex(_deviceAddress, ptr);
+    ptr += 4;
+    if (_muxNumber != I2CMux_None)
+      *ptr++ = '}';
+    *ptr = 0; // terminate string
+    return addressBuffer;
+  }
+
+  // Comparison operator
+  int operator == (I2CAddress &a) const {
+    if (_deviceAddress != a._deviceAddress) 
+      return false; // Different device address so no match
+    if (_muxNumber == I2CMux_None || a._muxNumber == I2CMux_None)
+      return true;  // Same device address, one or other on main bus
+    if (_subBus == SubBus_None || a._subBus == SubBus_None) 
+      return true;  // Same device address, one or other on main bus
+    if (_muxNumber != a._muxNumber) 
+      return false; // Connected to a subbus on a different mux
+    if (_subBus != a._subBus)
+      return false;  // different subbus
+    return true;  // Same address on same mux and same subbus
+  }
+  // Field accessors
+  I2CMux muxNumber() { return _muxNumber; }
+  I2CSubBus subBus() { return _subBus; }
+  uint8_t deviceAddress() { return _deviceAddress; }
+
+private:
+  // Helper function for converting byte to four-character hex string (e.g. 0x23).
+  void toHex(const uint8_t value, char *buffer);
+};
+
+#else
+struct I2CAddress {
+private:
+  uint8_t _deviceAddress;
+  static char addressBuffer[];
+public:
+  // Constructors
+  I2CAddress(const uint8_t deviceAddress) {
+    _deviceAddress = deviceAddress;
+  }
+  I2CAddress(I2CMux, I2CSubBus, const uint8_t deviceAddress) {
+    addressWarning();
+    _deviceAddress = deviceAddress;
+  }
+  I2CAddress(I2CSubBus, const uint8_t deviceAddress) {
+    addressWarning();
+    _deviceAddress = deviceAddress;
+  }
+
+  // Basic constructor
+  I2CAddress() : I2CAddress(0) {}
+
+  // Conversion operator from I2CAddress to uint8_t
+  // For "uint8_t address = i2cAddress;" syntax
+  operator uint8_t () const { return _deviceAddress; }
+
+  // Conversion from I2CAddress to char* (uses static storage so only 
+  // one conversion can be done at a time).  So don't call it twice in a
+  // single DIAG statement for example.
+  const char* toString () { 
+    char *ptr = addressBuffer;
+    // Just display hex value, two digits.
+    toHex(_deviceAddress, ptr);
+    ptr += 4;
+    *ptr = 0; // terminate string
+    return addressBuffer;
+  }
+
+  // Comparison operator
+  int operator == (I2CAddress &a) const {
+    if (_deviceAddress != a._deviceAddress) 
+      return false; // Different device address so no match
+    return true;  // Same address on same mux and same subbus
+  }
+private:
+  // Helper function for converting byte to four-character hex string (e.g. 0x23).
+  void toHex(const uint8_t value, char *buffer);
+  void addressWarning() {
+    if (!_addressWarningDone) {
+      DIAG(F("WARNIING: Extended I2C address used but not supported in this configuration"));
+      _addressWarningDone = true;
+    }
+  }    
+  static bool _addressWarningDone;
+};
+#endif // I2C_EXTENDED_ADDRESS
+
+
 // Status codes for I2CRB structures.
 enum : uint8_t {
   // Codes used by Wire and by native drivers
@@ -138,6 +375,7 @@ enum : uint8_t {
   I2C_STATE_ACTIVE=253,
   I2C_STATE_FREE=254,
   I2C_STATE_CLOSING=255,
+  I2C_STATE_COMPLETED=252,
 };
 
 typedef enum : uint8_t
@@ -146,6 +384,8 @@ typedef enum : uint8_t
   OPERATION_REQUEST = 2,
   OPERATION_SEND = 3,
   OPERATION_SEND_P = 4,
+  OPERATION_NORETRY = 0x80,  // OR with operation to suppress retries.
+  OPERATION_MASK = 0x7f,  // mask for extracting the operation code
 } OperationEnum;
 
 
@@ -164,18 +404,19 @@ public:
   uint8_t wait();
   bool isBusy();
 
-  void setReadParams(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t readLen);
-  void setRequestParams(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t readLen, const uint8_t *writeBuffer, uint8_t writeLen);
-  void setWriteParams(uint8_t i2cAddress, const uint8_t *writeBuffer, uint8_t writeLen);
+  void setReadParams(I2CAddress i2cAddress, uint8_t *readBuffer, uint8_t readLen);
+  void setRequestParams(I2CAddress i2cAddress, uint8_t *readBuffer, uint8_t readLen, const uint8_t *writeBuffer, uint8_t writeLen);
+  void setWriteParams(I2CAddress i2cAddress, const uint8_t *writeBuffer, uint8_t writeLen);
+  void suppressRetries(bool suppress);
 
   uint8_t writeLen;
   uint8_t readLen;
   uint8_t operation;
-  uint8_t i2cAddress;
+  I2CAddress i2cAddress;
   uint8_t *readBuffer;
   const uint8_t *writeBuffer;
 #if !defined(I2C_USE_WIRE)
-  I2CRB *nextRequest;
+  I2CRB *nextRequest;  // Used by non-blocking devices for I2CRB queue management.
 #endif
 };
 
@@ -189,26 +430,33 @@ public:
   void setClock(uint32_t speed);
   // Force clock speed 
   void forceClock(uint32_t speed);
+  // setTimeout sets the timout value for I2C transactions (milliseconds).
+  void setTimeout(unsigned long);
   // Check if specified I2C address is responding.
-  uint8_t checkAddress(uint8_t address);
-  inline bool exists(uint8_t address) {
+  uint8_t checkAddress(I2CAddress address);
+  inline bool exists(I2CAddress address) {
     return checkAddress(address)==I2C_STATUS_OK;
   }
+  // Select/deselect Mux Sub-Bus (if using legacy addresses, just checks address)
+  // E.g. muxSelectSubBus({I2CMux_0, SubBus_3});
+  uint8_t muxSelectSubBus(I2CAddress address) {
+    return checkAddress(address);
+  }
   // Write a complete transmission to I2C from an array in RAM
-  uint8_t write(uint8_t address, const uint8_t buffer[], uint8_t size);
-  uint8_t write(uint8_t address, const uint8_t buffer[], uint8_t size, I2CRB *rb);
+  uint8_t write(I2CAddress address, const uint8_t buffer[], uint8_t size);
+  uint8_t write(I2CAddress address, const uint8_t buffer[], uint8_t size, I2CRB *rb);
   // Write a complete transmission to I2C from an array in Flash
-  uint8_t write_P(uint8_t address, const uint8_t buffer[], uint8_t size);
-  uint8_t write_P(uint8_t address, const uint8_t buffer[], uint8_t size, I2CRB *rb);
+  uint8_t write_P(I2CAddress address, const uint8_t buffer[], uint8_t size);
+  uint8_t write_P(I2CAddress address, const uint8_t buffer[], uint8_t size, I2CRB *rb);
   // Write a transmission to I2C from a list of bytes.
-  uint8_t write(uint8_t address, uint8_t nBytes, ...);
+  uint8_t write(I2CAddress address, uint8_t nBytes, ...);
   // Write a command from an array in RAM and read response
-  uint8_t read(uint8_t address, uint8_t readBuffer[], uint8_t readSize, 
+  uint8_t read(I2CAddress address, uint8_t readBuffer[], uint8_t readSize, 
     const uint8_t writeBuffer[]=NULL, uint8_t writeSize=0);
-  uint8_t read(uint8_t address, uint8_t readBuffer[], uint8_t readSize, 
+  uint8_t read(I2CAddress address, uint8_t readBuffer[], uint8_t readSize, 
     const uint8_t writeBuffer[], uint8_t writeSize, I2CRB *rb);
   // Write a command from an arbitrary list of bytes and read response
-  uint8_t read(uint8_t address, uint8_t readBuffer[], uint8_t readSize, 
+  uint8_t read(I2CAddress address, uint8_t readBuffer[], uint8_t readSize, 
     uint8_t writeSize, ...);
   void queueRequest(I2CRB *req);
 
@@ -225,14 +473,37 @@ public:
 private:
   bool _beginCompleted = false;
   bool _clockSpeedFixed = false;
-  uint32_t _clockSpeed = 400000L;  // 400kHz max on Arduino.
-
+  uint8_t retryCounter;  // Count of retries
+  // Clock speed must be no higher than 400kHz on AVR. Higher is possible on 4809, SAMD
+  // and STM32 but most popular I2C devices are 400kHz so in practice the higher speeds
+  // will not be useful.  The speed can be overridden by I2CManager::forceClock().
+  uint32_t _clockSpeed = I2C_FREQ;  
+  // Default timeout 100ms on I2C request block completion.
+  // A full 32-byte transmission takes about 8ms at 100kHz,
+  // so this value allows lots of headroom.  
+  // It can be modified by calling I2CManager.setTimeout() function.
+  // When retries are enabled, the timeout applies to each
+  // try, and failure from timeout does not get retried.
+  // A value of 0 means disable timeout monitoring.
+  uint32_t _timeout = 100000UL;
+    
   // Finish off request block by waiting for completion and posting status.
   uint8_t finishRB(I2CRB *rb, uint8_t status);
 
   void _initialise();
   void _setClock(unsigned long);
 
+#if defined(I2C_EXTENDED_ADDRESS)
+// Count of I2C multiplexers found when initialising.  If there is only one
+// MUX then the subbus does not need de-selecting after use; however, if there
+// are two or more, then the subbus must be deselected to avoid multiple
+// sub-bus legs on different multiplexers being accessible simultaneously.
+private:
+  uint8_t _muxCount = 0;
+public:
+  uint8_t getMuxCount() { return _muxCount; }
+#endif
+
 #if !defined(I2C_USE_WIRE)
     // I2CRB structs are queued on the following two links.
     // If there are no requests, both are NULL.
@@ -242,42 +513,58 @@ private:
     // Within the queue, each request's nextRequest field points to the 
     // next request, or NULL.
     // Mark volatile as they are updated by IRC and read/written elsewhere.
-    static I2CRB * volatile queueHead;
-    static I2CRB * volatile queueTail;
-    static volatile uint8_t state;
+private:
+    I2CRB * volatile queueHead = NULL;
+    I2CRB * volatile queueTail = NULL;
 
-    static I2CRB * volatile currentRequest;
-    static volatile uint8_t txCount;
-    static volatile uint8_t rxCount;
-    static volatile uint8_t bytesToSend;
-    static volatile uint8_t bytesToReceive;
-    static volatile uint8_t operation;
-    static volatile unsigned long startTime;
+    // State is set to I2C_STATE_FREE when the interrupt handler has finished
+    // the current request and is ready to complete.
+    uint8_t state = I2C_STATE_FREE;
+
+    // CompletionStatus may be set by the interrupt handler at any time but is
+    // not written to the I2CRB until the state is I2C_STATE_FREE.
+    uint8_t completionStatus = I2C_STATUS_OK;
+    uint8_t overallStatus = I2C_STATUS_OK;
+
+    I2CRB * currentRequest = NULL;
+    uint8_t txCount = 0;
+    uint8_t rxCount = 0;
+    uint8_t bytesToSend = 0;
+    uint8_t bytesToReceive = 0;
+    uint8_t operation = 0;
+    uint32_t startTime = 0;
+    uint8_t muxPhase = 0;
+    uint8_t muxAddress = 0;
+    uint8_t muxData[1];
+    uint8_t deviceAddress;
+    const uint8_t *sendBuffer;
+    uint8_t *receiveBuffer;
+    uint8_t transactionState = 0;
+  
+    volatile uint32_t pendingClockSpeed = 0;
 
-    static unsigned long timeout; // Transaction timeout in microseconds.  0=disabled.
-    
     void startTransaction();
     
     // Low-level hardware manipulation functions.
-    static void I2C_init();
-    static void I2C_setClock(unsigned long i2cClockSpeed);
-    static void I2C_handleInterrupt();
-    static void I2C_sendStart();
-    static void I2C_sendStop();
-    static void I2C_close();
+    void I2C_init();
+    void I2C_setClock(unsigned long i2cClockSpeed);
+    void I2C_handleInterrupt();
+    void I2C_sendStart();
+    void I2C_sendStop();
+    void I2C_close();
     
   public:
-    // setTimeout sets the timout value for I2C transactions.
-    // TODO: Get I2C timeout working before uncommenting the code below.
-    void setTimeout(unsigned long value) { (void)value; /* timeout = value; */ };
-
     // handleInterrupt needs to be public to be called from the ISR function!
-    static void handleInterrupt();
+    void handleInterrupt();
 #endif
 
 
 };
 
+// Pointer to class instance (Note: if there is more than one bus, each will have
+// its own instance of I2CManager, selected by the queueRequest function from
+// the I2CBus field within the request block's I2CAddress).
 extern I2CManagerClass I2CManager;
 
+
 #endif

I2CManager_AVR.h

@@ -1,5 +1,5 @@
 /*
- *  © 2021, Neil McKechnie. All rights reserved.
+ *  © 2023, Neil McKechnie. All rights reserved.
  *
  *  This file is part of CommandStation-EX
  *
@@ -22,6 +22,7 @@
 
 #include <Arduino.h>
 #include "I2CManager.h"
+#include "I2CManager_NonBlocking.h"   // to satisfy intellisense
 
 #include <avr/io.h>
 #include <avr/interrupt.h>
@@ -94,12 +95,13 @@ void I2CManagerClass::I2C_init()
  *  Initiate a start bit for transmission.
  ***************************************************************************/
 void I2CManagerClass::I2C_sendStart() {
-  bytesToSend = currentRequest->writeLen;
-  bytesToReceive = currentRequest->readLen;
-  // We may have initiated a stop bit before this without waiting for it.
-  // Wait for stop bit to be sent before sending start.
-  while (TWCR & (1<<TWSTO)) {}
-  TWCR = (1<<TWEN)|ENABLE_TWI_INTERRUPT|(1<<TWINT)|(1<<TWEA)|(1<<TWSTA);  // Send Start
+  rxCount = 0;
+  txCount = 0;
+  // We may have already triggered a stop bit in the same run as this.  To avoid
+  // clearing that bit before the stop bit has been sent, we can either wait for
+  // it to complete or we can OR the bit onto the existing bits.
+  TWCR |= (1<<TWEN)|ENABLE_TWI_INTERRUPT|(1<<TWINT)|(1<<TWEA)|(1<<TWSTA);  // Send Start
+
 }
 
 /***************************************************************************
@@ -107,7 +109,7 @@ void I2CManagerClass::I2C_sendStart() {
  ***************************************************************************/
 void I2CManagerClass::I2C_sendStop() {
   TWDR = 0xff;  // Default condition = SDA released
-  TWCR = (1<<TWEN)|(1<<TWINT)|(1<<TWEA)|(1<<TWSTO);  // Send Stop
+  TWCR = (1<<TWEN)|(1<<TWINT)|(1<<TWSTO);  // Send Stop
 }
 
 /***************************************************************************
@@ -115,9 +117,8 @@ void I2CManagerClass::I2C_sendStop() {
  ***************************************************************************/
 void I2CManagerClass::I2C_close() {
   // disable TWI
-  I2C_sendStop();
-  while (TWCR & (1<<TWSTO)) {}
   TWCR = (1<<TWINT);                 // clear any interrupt and stop twi.
+  delayMicroseconds(10);  // Wait for things to stabilise (hopefully)
 }
 
 /***************************************************************************
@@ -125,37 +126,51 @@ void I2CManagerClass::I2C_close() {
  *  if I2C_USE_INTERRUPTS isn't defined, from the I2CManagerClass::loop() function
  *  (and therefore, indirectly, from I2CRB::wait() and I2CRB::isBusy()).
  ***************************************************************************/
+
 void I2CManagerClass::I2C_handleInterrupt() {
   if (!(TWCR & (1<<TWINT))) return;  // Nothing to do.
 
   uint8_t twsr = TWSR & 0xF8;
 
+
+  // Main I2C interrupt handler, used for the device communications.
+  // The following variables are used:
+  //    bytesToSend, bytesToReceive (R/W)
+  //    txCount, rxCount (W)
+  //    deviceAddress (R)
+  //    sendBuffer, receiveBuffer (R)
+  //    operation (R)
+  //    state, completionStatus (W)
+  // 
   // Cases are ordered so that the most frequently used ones are tested first.
   switch (twsr) {
     case TWI_MTX_DATA_ACK:      // Data byte has been transmitted and ACK received
     case TWI_MTX_ADR_ACK:       // SLA+W has been transmitted and ACK received
       if (bytesToSend) {  // Send first.
         if (operation == OPERATION_SEND_P)
-          TWDR = GETFLASH(currentRequest->writeBuffer + (txCount++));
+          TWDR = GETFLASH(sendBuffer + (txCount++));
         else
-          TWDR = currentRequest->writeBuffer[txCount++];
+          TWDR = sendBuffer[txCount++];
         bytesToSend--;
-        TWCR = (1<<TWEN)|ENABLE_TWI_INTERRUPT|(1<<TWINT)|(1<<TWEA);
+        TWCR = (1<<TWEN)|ENABLE_TWI_INTERRUPT|(1<<TWINT);
       } else if (bytesToReceive) {  // All sent, anything to receive?
-        while (TWCR & (1<<TWSTO)) {}    // Wait for stop to be sent
-        TWCR = (1<<TWEN)|ENABLE_TWI_INTERRUPT|(1<<TWINT)|(1<<TWEA)|(1<<TWSTA);  // Send Start
-      } else {  // Nothing left to send or receive
-        TWDR = 0xff;  // Default condition = SDA released
+        // Don't need to wait for stop, as the interface won't send the start until
+        // any in-progress stop condition from previous interrupts has been sent.
+        TWCR = (1<<TWEN)|ENABLE_TWI_INTERRUPT|(1<<TWINT)|(1<<TWSTA);  // Send Start
+      } else {  
+         // Nothing left to send or receive
         TWCR = (1<<TWEN)|(1<<TWINT)|(1<<TWEA)|(1<<TWSTO);  // Send Stop
-        state = I2C_STATUS_OK;
+        state = I2C_STATE_COMPLETED;
       }
       break;
+
     case TWI_MRX_DATA_ACK:      // Data byte has been received and ACK transmitted
       if (bytesToReceive > 0) {
-        currentRequest->readBuffer[rxCount++] = TWDR;
+        receiveBuffer[rxCount++] = TWDR;
         bytesToReceive--;
       }
       /* fallthrough */
+
     case TWI_MRX_ADR_ACK:      // SLA+R has been sent and ACK received
       if (bytesToReceive <= 1) {
         TWCR = (1<<TWEN)|ENABLE_TWI_INTERRUPT|(1<<TWINT); // Send NACK after next reception
@@ -164,45 +179,51 @@ void I2CManagerClass::I2C_handleInterrupt() {
         TWCR = (1<<TWEN)|ENABLE_TWI_INTERRUPT|(1<<TWINT)|(1<<TWEA);
       }
       break;
+
     case TWI_MRX_DATA_NACK:     // Data byte has been received and NACK transmitted
       if (bytesToReceive > 0) {
-        currentRequest->readBuffer[rxCount++] = TWDR;
+        receiveBuffer[rxCount++] = TWDR;
         bytesToReceive--;
       }
       TWCR = (1<<TWEN)|(1<<TWINT)|(1<<TWEA)|(1<<TWSTO);  // Send Stop
-      state = I2C_STATUS_OK;
+      state = I2C_STATE_COMPLETED;
       break;
+
     case TWI_START:             // START has been transmitted  
     case TWI_REP_START:         // Repeated START has been transmitted
       // Set up address and R/W
       if (operation == OPERATION_READ || (operation==OPERATION_REQUEST && !bytesToSend))
-        TWDR = (currentRequest->i2cAddress << 1) | 1; // SLA+R
+        TWDR = (deviceAddress << 1) | 1; // SLA+R
       else
-        TWDR = (currentRequest->i2cAddress << 1) | 0; // SLA+W
+        TWDR = (deviceAddress << 1) | 0; // SLA+W
       TWCR = (1<<TWEN)|ENABLE_TWI_INTERRUPT|(1<<TWINT)|(1<<TWEA);
       break;
+
     case TWI_MTX_ADR_NACK:      // SLA+W has been transmitted and NACK received
     case TWI_MRX_ADR_NACK:      // SLA+R has been transmitted and NACK received
     case TWI_MTX_DATA_NACK:     // Data byte has been transmitted and NACK received
-      TWDR = 0xff;  // Default condition = SDA released
       TWCR = (1<<TWEN)|(1<<TWINT)|(1<<TWEA)|(1<<TWSTO);  // Send Stop
-      state = I2C_STATUS_NEGATIVE_ACKNOWLEDGE;
+      completionStatus = I2C_STATUS_NEGATIVE_ACKNOWLEDGE;
+      state = I2C_STATE_COMPLETED;
       break;
+
     case TWI_ARB_LOST:          // Arbitration lost
       // Restart transaction from start.
       I2C_sendStart();
       break;
+
     case TWI_BUS_ERROR:         // Bus error due to an illegal START or STOP condition
     default:
       TWDR = 0xff;  // Default condition = SDA released
       TWCR = (1<<TWEN)|(1<<TWINT)|(1<<TWEA)|(1<<TWSTO);  // Send Stop
-      state = I2C_STATUS_TRANSMIT_ERROR;
+      completionStatus = I2C_STATUS_TRANSMIT_ERROR;
+      state = I2C_STATE_COMPLETED;
   }
 }
 
 #if defined(I2C_USE_INTERRUPTS)
 ISR(TWI_vect) {
-  I2CManagerClass::handleInterrupt();
+  I2CManager.handleInterrupt();
 }
 #endif
 

I2CManager_Mega4809.h

@@ -1,5 +1,5 @@
 /*
- *  © 2021, Neil McKechnie. All rights reserved.
+ *  © 2023, Neil McKechnie. All rights reserved.
  *
  *  This file is part of CommandStation-EX
  *
@@ -28,21 +28,21 @@
  ***************************************************************************/
 void I2CManagerClass::I2C_setClock(unsigned long i2cClockSpeed) {
   uint16_t t_rise;
-  if (i2cClockSpeed < 200000) {
-    i2cClockSpeed = 100000;
+  if (i2cClockSpeed < 200000)
     t_rise = 1000;
-  } else if (i2cClockSpeed < 800000) {
-    i2cClockSpeed = 400000;
+  else if (i2cClockSpeed < 800000)
     t_rise = 300;
-  } else if (i2cClockSpeed < 1200000) {
-    i2cClockSpeed = 1000000;
+  else
     t_rise = 120;
-  } else {
-    i2cClockSpeed = 100000;
-    t_rise = 1000;
-  }
+
+  if (t_rise == 120)
+    TWI0.CTRLA |= TWI_FMPEN_bm;
+  else
+    TWI0.CTRLA &= ~TWI_FMPEN_bm;
+  
   uint32_t baud = (F_CPU_CORRECTED / i2cClockSpeed - F_CPU_CORRECTED / 1000 / 1000
     * t_rise / 1000 - 10) / 2;
+  if (baud > 255) baud = 255;  // ~30kHz
   TWI0.MBAUD = (uint8_t)baud;
 }
 
@@ -54,13 +54,13 @@ void I2CManagerClass::I2C_init()
   pinMode(PIN_WIRE_SDA, INPUT_PULLUP);
   pinMode(PIN_WIRE_SCL, INPUT_PULLUP);
   PORTMUX.TWISPIROUTEA |= TWI_MUX;
+  I2C_setClock(I2C_FREQ);
 
 #if defined(I2C_USE_INTERRUPTS)
   TWI0.MCTRLA = TWI_RIEN_bm | TWI_WIEN_bm | TWI_ENABLE_bm;
 #else
   TWI0.MCTRLA = TWI_ENABLE_bm;
 #endif
-  I2C_setClock(I2C_FREQ);
   TWI0.MSTATUS = TWI_BUSSTATE_IDLE_gc;
 }
 
@@ -68,11 +68,11 @@ void I2CManagerClass::I2C_init()
  *  Initiate a start bit for transmission, followed by address and R/W
  ***************************************************************************/
 void I2CManagerClass::I2C_sendStart() {
-  bytesToSend = currentRequest->writeLen;
-  bytesToReceive = currentRequest->readLen;
+  txCount = 0;
+  rxCount = 0;
 
   // If anything to send, initiate write.  Otherwise initiate read.
-  if (operation == OPERATION_READ || (operation == OPERATION_REQUEST & !bytesToSend))
+  if (operation == OPERATION_READ || ((operation == OPERATION_REQUEST) && !bytesToSend))
     TWI0.MADDR = (currentRequest->i2cAddress << 1) | 1;
   else
     TWI0.MADDR = (currentRequest->i2cAddress << 1) | 0;
@@ -89,7 +89,10 @@ void I2CManagerClass::I2C_sendStop() {
  *  Close I2C down
  ***************************************************************************/
 void I2CManagerClass::I2C_close() {
-  I2C_sendStop();
+
+  TWI0.MCTRLA &= ~(TWI_RIEN_bm | TWI_WIEN_bm | TWI_ENABLE_bm);        // Switch off I2C
+  TWI0.MSTATUS = TWI_BUSSTATE_UNKNOWN_gc;
+  delayMicroseconds(10);  // Wait for things to stabilise (hopefully)
 }
 
 /***************************************************************************
@@ -105,46 +108,42 @@ void I2CManagerClass::I2C_handleInterrupt() {
     I2C_sendStart();   // Reinitiate request
   } else if (currentStatus & TWI_BUSERR_bm) {
     // Bus error
-    state = I2C_STATUS_BUS_ERROR;
+    completionStatus = I2C_STATUS_BUS_ERROR;
+    state = I2C_STATE_COMPLETED;
     TWI0.MSTATUS = currentStatus; // clear all flags
   } else if (currentStatus & TWI_WIF_bm) {
     // Master write completed
     if (currentStatus & TWI_RXACK_bm) {
       // Nacked, send stop.
       TWI0.MCTRLB = TWI_MCMD_STOP_gc;
-      state = I2C_STATUS_NEGATIVE_ACKNOWLEDGE;
+      completionStatus = I2C_STATUS_NEGATIVE_ACKNOWLEDGE;
+      state = I2C_STATE_COMPLETED;
+
     } else if (bytesToSend) {
-      // Acked, so send next byte
-      if (currentRequest->operation == OPERATION_SEND_P)
-        TWI0.MDATA = GETFLASH(currentRequest->writeBuffer + (txCount++));
-      else
-        TWI0.MDATA = currentRequest->writeBuffer[txCount++];
+      // Acked, so send next byte (don't need to use GETFLASH)
+      TWI0.MDATA = sendBuffer[txCount++];
       bytesToSend--;
     } else if (bytesToReceive) {
-        // Last sent byte acked and no more to send.  Send repeated start, address and read bit.
-        TWI0.MADDR = (currentRequest->i2cAddress << 1) | 1;
+      // Last sent byte acked and no more to send.  Send repeated start, address and read bit.
+      TWI0.MADDR = (deviceAddress << 1) | 1;
     } else {
       // No more data to send/receive. Initiate a STOP condition.
       TWI0.MCTRLB = TWI_MCMD_STOP_gc;
-      state = I2C_STATUS_OK;  // Done
+      state = I2C_STATE_COMPLETED;
     }
   } else if (currentStatus & TWI_RIF_bm) {
     // Master read completed without errors
     if (bytesToReceive) {
-      currentRequest->readBuffer[rxCount++] = TWI0.MDATA;  // Store received byte
+      receiveBuffer[rxCount++] = TWI0.MDATA;  // Store received byte
       bytesToReceive--;
-    } else { 
-      // Buffer full, issue nack/stop
-      TWI0.MCTRLB = TWI_ACKACT_bm | TWI_MCMD_STOP_gc;
-      state = I2C_STATUS_OK;
-    }
+    } 
     if (bytesToReceive) {
       // More bytes to receive, issue ack and start another read
       TWI0.MCTRLB = TWI_MCMD_RECVTRANS_gc;
     } else {
       // Transaction finished, issue NACK and STOP.
       TWI0.MCTRLB = TWI_ACKACT_bm | TWI_MCMD_STOP_gc;
-      state = I2C_STATUS_OK;
+      state = I2C_STATE_COMPLETED;
     }
   }
 }
@@ -154,7 +153,7 @@ void I2CManagerClass::I2C_handleInterrupt() {
  *  Interrupt handler.
  ***************************************************************************/
 ISR(TWI0_TWIM_vect) {
-  I2CManagerClass::handleInterrupt();
+  I2CManager.handleInterrupt();
 }
 
-#endif
+#endif

I2CManager_NonBlocking.h

@@ -1,5 +1,7 @@
 /*
- *  © 2021, Neil McKechnie. All rights reserved.
+ *  © 2023, Neil McKechnie
+ *  © 2022 Paul M Antoine
+ *  All rights reserved.
  *
  *  This file is part of CommandStation-EX
  *
@@ -22,19 +24,62 @@
 
 #include <Arduino.h>
 #include "I2CManager.h"
-#if defined(I2C_USE_INTERRUPTS)
-#include <util/atomic.h>
+
+// Support for atomic isolation (i.e. a block with interrupts disabled).
+// E.g. 
+//       ATOMIC_BLOCK() {
+//         doSomethingWithInterruptsDisabled();
+//       }
+// This has the advantage over simple noInterrupts/Interrupts that the
+// original interrupt state is restored when the block finishes.
+//
+// (This should really be defined in an include file somewhere more global, so 
+// it can replace use of noInterrupts/interrupts in other parts of DCC-EX.
+//
+static inline uint8_t _deferInterrupts(void) {
+  noInterrupts();
+  return 1;
+}
+static inline void _conditionalEnableInterrupts(bool *wasEnabled) {
+  if (*wasEnabled) interrupts();
+}
+#define ATOMIC_BLOCK(x) \
+for (bool _int_saved __attribute__((__cleanup__(_conditionalEnableInterrupts))) \
+            =_getInterruptState(),_ToDo=_deferInterrupts(); _ToDo; _ToDo=0)
+
+#if defined(__AVR__) // Nano, Uno, Mega2580, NanoEvery, etc.
+  static inline bool _getInterruptState(void) {
+    return bitRead(SREG, SREG_I);  // true if enabled, false if disabled
+  }
+#elif defined(__arm__)  // STM32, SAMD, Teensy
+  static inline bool _getInterruptState( void ) {
+    uint32_t reg;
+    __asm__ __volatile__ ("MRS %0, primask" : "=r" (reg) );
+    return !(reg & 1);  // true if interrupts enabled, false otherwise
+  }
 #else
-#define ATOMIC_BLOCK(x) 
-#define ATOMIC_RESTORESTATE
+  #warning "ATOMIC_BLOCK() not defined for this target type, I2C interrupts disabled"
+  #define ATOMIC_BLOCK(x) // expand to nothing.
+  #ifdef I2C_USE_INTERRUPTS
+    #undef I2C_USE_INTERRUPTS
+  #endif
 #endif
 
+
 // This module is only compiled if I2C_USE_WIRE is not defined, so undefine it here
 // to get intellisense to work correctly.
 #if defined(I2C_USE_WIRE)
 #undef I2C_USE_WIRE
 #endif
 
+enum MuxPhase: uint8_t {
+  MuxPhase_OFF = 0,
+  MuxPhase_PROLOG,
+  MuxPhase_PAYLOAD,
+  MuxPhase_EPILOG,
+} ;
+
+
 /***************************************************************************
  * Initialise the I2CManagerAsync class.
  ***************************************************************************/
@@ -43,31 +88,82 @@ void I2CManagerClass::_initialise()
   queueHead = queueTail = NULL;
   state = I2C_STATE_FREE;
   I2C_init();
+  _setClock(_clockSpeed);
 }
 
 /***************************************************************************
  *  Set I2C clock speed.  Normally 100000 (Standard) or 400000 (Fast)
  *   on Arduino.  Mega4809 supports 1000000 (Fast+) too.
+ *   This function saves the desired clock speed and the startTransaction
+ *   function acts on it before a new transaction, to avoid speed changes
+ *   during an I2C transaction.
  ***************************************************************************/
 void I2CManagerClass::_setClock(unsigned long i2cClockSpeed) {
-  I2C_setClock(i2cClockSpeed);
+  pendingClockSpeed = i2cClockSpeed;
 }
 
 /***************************************************************************
- * Helper function to start operations, if the I2C interface is free and
+ * Start an I2C transaction, if the I2C interface is free and
  * there is a queued request to be processed.
+ * If there's an I2C clock speed change pending, then implement it before 
+ * starting the operation.
  ***************************************************************************/
-void I2CManagerClass::startTransaction() { 
-  ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
+void I2CManagerClass::startTransaction() {
+  ATOMIC_BLOCK() {
     if ((state == I2C_STATE_FREE) && (queueHead != NULL)) {
       state = I2C_STATE_ACTIVE;
+      completionStatus = I2C_STATUS_OK;
+      // Check for pending clock speed change
+      if (pendingClockSpeed) {
+        // We're about to start a new I2C transaction, so set clock now.
+        I2C_setClock(pendingClockSpeed);
+        pendingClockSpeed = 0;
+      }
+      startTime = micros();
       currentRequest = queueHead;
       rxCount = txCount = 0;
-      // Copy key fields to static data for speed.
-      operation = currentRequest->operation;
+
       // Start the I2C process going.
+#if defined(I2C_EXTENDED_ADDRESS)
+      I2CMux muxNumber = currentRequest->i2cAddress.muxNumber();
+      if (muxNumber != I2CMux_None) {
+        muxPhase = MuxPhase_PROLOG;
+        uint8_t subBus = currentRequest->i2cAddress.subBus();
+        muxData[0] = (subBus == SubBus_All) ? 0xff :
+                     (subBus == SubBus_None) ? 0x00 :
+#if defined(I2CMUX_PCA9547)
+                      0x08 | subBus;
+#elif defined(I2CMUX_PCA9542) || defined(I2CMUX_PCA9544)
+                      0x04 | subBus;   // NB Only 2 or 4 subbuses respectively
+#else
+                      // Default behaviour for most MUXs is to use a mask
+                      // with a bit set for the subBus to be enabled
+                      1 << subBus;
+#endif
+        deviceAddress = I2C_MUX_BASE_ADDRESS + muxNumber;
+        sendBuffer = &muxData[0];
+        bytesToSend = 1;
+        bytesToReceive = 0;
+        operation = OPERATION_SEND;
+      } else {
+        // Send/receive payload for device only.
+        muxPhase = MuxPhase_OFF;
+        deviceAddress = currentRequest->i2cAddress;
+        sendBuffer = currentRequest->writeBuffer;
+        bytesToSend = currentRequest->writeLen;
+        receiveBuffer = currentRequest->readBuffer;
+        bytesToReceive = currentRequest->readLen;
+        operation = currentRequest->operation & OPERATION_MASK;
+      } 
+#else
+      deviceAddress = currentRequest->i2cAddress;
+      sendBuffer = currentRequest->writeBuffer;
+      bytesToSend = currentRequest->writeLen;
+      receiveBuffer = currentRequest->readBuffer;
+      bytesToReceive = currentRequest->readLen;
+      operation = currentRequest->operation & OPERATION_MASK;
+#endif
       I2C_sendStart();
-      startTime = micros();
     }
   }
 }
@@ -76,10 +172,13 @@ void I2CManagerClass::startTransaction() {
  *  Function to queue a request block and initiate operations.
  ***************************************************************************/
 void I2CManagerClass::queueRequest(I2CRB *req) {
+
+  if (((req->operation & OPERATION_MASK) == OPERATION_READ) && req->readLen == 0)
+    return;  // Ignore null read
+
   req->status = I2C_STATUS_PENDING;
   req->nextRequest = NULL;
-
-  ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
+  ATOMIC_BLOCK() {
     if (!queueTail) 
       queueHead = queueTail = req;  // Only item on queue
     else
@@ -89,10 +188,11 @@ void I2CManagerClass::queueRequest(I2CRB *req) {
 
 }
 
+
 /***************************************************************************
  *  Initiate a write to an I2C device (non-blocking operation)
  ***************************************************************************/
-uint8_t I2CManagerClass::write(uint8_t i2cAddress, const uint8_t *writeBuffer, uint8_t writeLen, I2CRB *req) {
+uint8_t I2CManagerClass::write(I2CAddress i2cAddress, const uint8_t *writeBuffer, uint8_t writeLen, I2CRB *req) {
   // Make sure previous request has completed.
   req->wait();
   req->setWriteParams(i2cAddress, writeBuffer, writeLen);
@@ -103,7 +203,7 @@ uint8_t I2CManagerClass::write(uint8_t i2cAddress, const uint8_t *writeBuffer, u
 /***************************************************************************
  *  Initiate a write from PROGMEM (flash) to an I2C device (non-blocking operation)
  ***************************************************************************/
-uint8_t I2CManagerClass::write_P(uint8_t i2cAddress, const uint8_t * writeBuffer, uint8_t writeLen, I2CRB *req) {
+uint8_t I2CManagerClass::write_P(I2CAddress i2cAddress, const uint8_t * writeBuffer, uint8_t writeLen, I2CRB *req) {
   // Make sure previous request has completed.
   req->wait();
   req->setWriteParams(i2cAddress, writeBuffer, writeLen);
@@ -116,7 +216,7 @@ uint8_t I2CManagerClass::write_P(uint8_t i2cAddress, const uint8_t * writeBuffer
  *  Initiate a read from the I2C device, optionally preceded by a write 
  *   (non-blocking operation)
  ***************************************************************************/
-uint8_t I2CManagerClass::read(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t readLen, 
+uint8_t I2CManagerClass::read(I2CAddress i2cAddress, uint8_t *readBuffer, uint8_t readLen, 
     const uint8_t *writeBuffer, uint8_t writeLen, I2CRB *req)
 {
   // Make sure previous request has completed.
@@ -126,27 +226,54 @@ uint8_t I2CManagerClass::read(uint8_t i2cAddress, uint8_t *readBuffer, uint8_t r
   return I2C_STATUS_OK;
 }
 
+/***************************************************************************
+ *  Set I2C timeout value in microseconds.  The timeout applies to the entire
+ *   I2CRB request, e.g. where a write+read is performed, the timer is not
+ *   reset before the read.
+ ***************************************************************************/
+void I2CManagerClass::setTimeout(unsigned long value) { 
+  _timeout = value; 
+};
+
 /***************************************************************************
  * checkForTimeout() function, called from isBusy() and wait() to cancel
- * requests that are taking too long to complete.
+ * requests that are taking too long to complete.  Such faults
+ * may be caused by an I2C wire short for example.
  ***************************************************************************/
 void I2CManagerClass::checkForTimeout() {
-  unsigned long currentMicros = micros();
-  ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
+  ATOMIC_BLOCK() {
     I2CRB *t = queueHead;
-    if (state==I2C_STATE_ACTIVE && t!=0 && t==currentRequest && timeout > 0) {
+    if (state==I2C_STATE_ACTIVE && t!=0 && t==currentRequest && _timeout > 0) {
       // Check for timeout
-      if (currentMicros - startTime > timeout) { 
+      int32_t elapsed = micros() - startTime;
+      if (elapsed > (int32_t)_timeout) { 
+#ifdef DIAG_IO
+        //DIAG(F("I2CManager Timeout on %s"), t->i2cAddress.toString());
+#endif
         // Excessive time. Dequeue request
         queueHead = t->nextRequest;
         if (!queueHead) queueTail = NULL;
         currentRequest = NULL;
+        bytesToReceive = bytesToSend = 0;
         // Post request as timed out.
         t->status = I2C_STATUS_TIMEOUT;
         // Reset TWI interface so it is able to continue
         // Try close and init, not entirely satisfactory but sort of works...
         I2C_close();  // Shutdown and restart twi interface
+
+        // If SDA is stuck low, issue up to 9 clock pulses to attempt to free it.
+        pinMode(SCL, INPUT_PULLUP);
+        pinMode(SDA, INPUT_PULLUP);
+        for (int i=0; !digitalRead(SDA) && i<9; i++) {
+          digitalWrite(SCL, 0); 
+          pinMode(SCL, OUTPUT);         // Force clock low
+          delayMicroseconds(10);        // ... for 5us
+          pinMode(SCL, INPUT_PULLUP);   // ... then high
+          delayMicroseconds(10);        // ... for 5us (100kHz Clock)
+        }
+        // Whether that's succeeded or not, now try reinitialising.
         I2C_init();
+        _setClock(_clockSpeed);
         state = I2C_STATE_FREE;
         
         // Initiate next queued request if any.
@@ -163,6 +290,7 @@ void I2CManagerClass::loop() {
 #if !defined(I2C_USE_INTERRUPTS)
   handleInterrupt();
 #endif
+  // Call function to monitor for stuck I2C operations.
   checkForTimeout();
 }
 
@@ -177,38 +305,83 @@ void I2CManagerClass::handleInterrupt() {
 
   // Check if current request has completed.  If there's a current request
   // and state isn't active then state contains the completion status of the request.
-  if (state != I2C_STATE_ACTIVE && currentRequest != NULL) {
-    // Remove completed request from head of queue
-    ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
+  if (state == I2C_STATE_COMPLETED && currentRequest != NULL && currentRequest == queueHead) {
+    // Operation has completed.
+    if (completionStatus == I2C_STATUS_OK || ++retryCounter > MAX_I2C_RETRIES
+      || currentRequest->operation & OPERATION_NORETRY) 
+    {
+      // Status is OK, or has failed and retry count exceeded, or failed and retries disabled.
+#if defined(I2C_EXTENDED_ADDRESS)
+      if (muxPhase == MuxPhase_PROLOG ) {
+        overallStatus = completionStatus;
+        uint8_t rbAddress = currentRequest->i2cAddress.deviceAddress();
+        if (completionStatus == I2C_STATUS_OK && rbAddress != 0) {
+          // Mux request OK, start handling application request.
+          muxPhase = MuxPhase_PAYLOAD;
+          deviceAddress = rbAddress;
+          sendBuffer = currentRequest->writeBuffer;
+          bytesToSend = currentRequest->writeLen;
+          receiveBuffer = currentRequest->readBuffer;
+          bytesToReceive = currentRequest->readLen;
+          operation = currentRequest->operation & OPERATION_MASK;
+          state = I2C_STATE_ACTIVE;
+          I2C_sendStart();
+          return;
+        } 
+      } else if (muxPhase == MuxPhase_PAYLOAD) {
+        // Application request completed, now send epilogue to mux
+        overallStatus = completionStatus;
+        currentRequest->nBytes = rxCount;  // Save number of bytes read into rb
+        if (_muxCount == 1) {
+          // Only one MUX, don't need to deselect subbus
+          muxPhase = MuxPhase_OFF;
+        } else {
+          muxPhase = MuxPhase_EPILOG;
+          deviceAddress = I2C_MUX_BASE_ADDRESS + currentRequest->i2cAddress.muxNumber();
+          muxData[0] = 0x00;
+          sendBuffer = &muxData[0];
+          bytesToSend = 1;
+          bytesToReceive = 0;
+          operation = OPERATION_SEND;
+          state = I2C_STATE_ACTIVE;
+          I2C_sendStart();
+          return;
+        }
+      } else if (muxPhase == MuxPhase_EPILOG) {
+        // Epilog finished, ignore completionStatus
+        muxPhase = MuxPhase_OFF;
+      } else
+        overallStatus = completionStatus;
+#else
+      overallStatus = completionStatus;
+      currentRequest->nBytes = rxCount;
+#endif
+          
+      // Remove completed request from head of queue
       I2CRB * t = queueHead;
-      if (t == queueHead) {
+      if (t == currentRequest) {
         queueHead = t->nextRequest;
         if (!queueHead) queueTail = queueHead;
-        t->nBytes = rxCount;
-        t->status = state;
+        t->status = overallStatus;
         
         // I2C state machine is now free for next request
         currentRequest = NULL;
         state = I2C_STATE_FREE;
-
-        // Start next request (if any)
-        I2CManager.startTransaction();
       }
+      retryCounter = 0;
+    } else {
+      // Status is failed and retry permitted.
+      // Retry previous request.
+      state = I2C_STATE_FREE;  
     }
   }
+
+  if (state == I2C_STATE_FREE && queueHead != NULL) {
+    // Allow any pending interrupts before starting the next request.
+    //interrupts();
+    // Start next request
+    I2CManager.startTransaction();
+  }
 }
 
-// Fields in I2CManager class specific to Non-blocking implementation.
-I2CRB * volatile I2CManagerClass::queueHead = NULL;
-I2CRB * volatile I2CManagerClass::queueTail = NULL;
-I2CRB * volatile I2CManagerClass::currentRequest = NULL;
-volatile uint8_t I2CManagerClass::state = I2C_STATE_FREE;
-volatile uint8_t I2CManagerClass::txCount;
-volatile uint8_t I2CManagerClass::rxCount;
-volatile uint8_t I2CManagerClass::operation;
-volatile uint8_t I2CManagerClass::bytesToSend;
-volatile uint8_t I2CManagerClass::bytesToReceive;
-volatile unsigned long I2CManagerClass::startTime;
-unsigned long I2CManagerClass::timeout = 0;
-
-#endif
+#endif

I2CManager_SAMD.h

@@ -0,0 +1,247 @@
+/*
+ *  © 2022 Paul M Antoine
+ *  © 2023, Neil McKechnie
+ *  All rights reserved.
+ *
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef I2CMANAGER_SAMD_H
+#define I2CMANAGER_SAMD_H
+
+#include <Arduino.h>
+#include "I2CManager.h"
+
+//#include <avr/io.h>
+//#include <avr/interrupt.h>
+#include <wiring_private.h>
+
+/***************************************************************************
+ *  Interrupt handler.
+ *  IRQ handler for SERCOM3 which is the default I2C definition for Arduino Zero
+ *  compatible variants such as the Sparkfun SAMD21 Dev Breakout etc.
+ *  Later we may wish to allow use of an alternate I2C bus, or more than one I2C
+ *  bus on the SAMD architecture 
+ ***************************************************************************/
+#if defined(I2C_USE_INTERRUPTS) && defined(ARDUINO_SAMD_ZERO)
+void SERCOM3_Handler() {
+  I2CManager.handleInterrupt();
+}
+#endif
+
+// Assume SERCOM3 for now - default I2C bus on Arduino Zero and variants of same
+Sercom *s = SERCOM3;
+
+/***************************************************************************
+ *  Set I2C clock speed register.  This should only be called outside of
+ *  a transmission.  The I2CManagerClass::_setClock() function ensures 
+ *  that it is only called at the beginning of an I2C transaction.
+ ***************************************************************************/
+void I2CManagerClass::I2C_setClock(uint32_t i2cClockSpeed) {
+
+  // Calculate a rise time appropriate to the requested bus speed
+  int t_rise;
+  if (i2cClockSpeed < 200000L) {
+    i2cClockSpeed = 100000L;    // NB: this overrides a "force clock" of lower than 100KHz!
+    t_rise = 1000;
+  } else if (i2cClockSpeed < 800000L) {
+    i2cClockSpeed = 400000L;
+    t_rise = 300;
+  } else if (i2cClockSpeed < 1200000L) {
+    i2cClockSpeed = 1000000L;
+    t_rise = 120;
+  } else {
+    i2cClockSpeed = 100000L;
+    t_rise = 1000;
+  }
+
+  // Wait while the bus is busy
+  while (s->I2CM.STATUS.bit.BUSSTATE != 0x1);
+
+  // Disable the I2C master mode and wait for sync
+  s->I2CM.CTRLA.bit.ENABLE = 0 ;
+  while (s->I2CM.SYNCBUSY.bit.ENABLE != 0);
+
+  // Calculate baudrate - using a rise time appropriate for the speed
+  s->I2CM.BAUD.bit.BAUD = SystemCoreClock / (2 * i2cClockSpeed) - 5 - (((SystemCoreClock / 1000000) * t_rise) / (2 * 1000));
+
+  // Enable the I2C master mode and wait for sync
+  s->I2CM.CTRLA.bit.ENABLE = 1 ;
+  while (s->I2CM.SYNCBUSY.bit.ENABLE != 0);
+
+  // Setting bus idle mode and wait for sync
+  s->I2CM.STATUS.bit.BUSSTATE = 1 ;
+  while (s->I2CM.SYNCBUSY.bit.SYSOP != 0);
+}
+
+/***************************************************************************
+ *  Initialise I2C registers.
+ ***************************************************************************/
+void I2CManagerClass::I2C_init()
+{
+  //Setting clock
+  GCLK->CLKCTRL.reg = GCLK_CLKCTRL_ID(GCM_SERCOM3_CORE) | // Generic Clock 0 (SERCOM3)
+                      GCLK_CLKCTRL_GEN_GCLK0 | // Generic Clock Generator 0 is source
+                      GCLK_CLKCTRL_CLKEN ;
+
+  /* Wait for peripheral clock synchronization */
+  while ( GCLK->STATUS.reg & GCLK_STATUS_SYNCBUSY );
+
+  // Software reset the SERCOM
+  s->I2CM.CTRLA.bit.SWRST = 1;
+
+  //Wait both bits Software Reset from CTRLA and SYNCBUSY are equal to 0
+  while(s->I2CM.CTRLA.bit.SWRST || s->I2CM.SYNCBUSY.bit.SWRST);
+
+  // Set master mode and enable SCL Clock Stretch mode (stretch after ACK bit)
+  s->I2CM.CTRLA.reg =  SERCOM_I2CM_CTRLA_MODE( I2C_MASTER_OPERATION )/* |
+                            SERCOM_I2CM_CTRLA_SCLSM*/ ;
+
+  // Enable Smart mode (but not Quick Command)
+  s->I2CM.CTRLB.reg =  SERCOM_I2CM_CTRLB_SMEN;
+
+#if defined(I2C_USE_INTERRUPTS)
+  // Setting NVIC
+  NVIC_EnableIRQ(SERCOM3_IRQn);
+  NVIC_SetPriority (SERCOM3_IRQn, SERCOM_NVIC_PRIORITY);  // Match default SERCOM priorities
+//  NVIC_SetPriority (SERCOM3_IRQn, 0);  // Set highest priority
+
+  // Enable all interrupts
+  s->I2CM.INTENSET.reg = SERCOM_I2CM_INTENSET_MB | SERCOM_I2CM_INTENSET_SB | SERCOM_I2CM_INTENSET_ERROR;
+#endif
+
+  // Calculate baudrate and set default rate for now
+  s->I2CM.BAUD.bit.BAUD = SystemCoreClock / ( 2 * I2C_FREQ) - 7 / (2 * 1000);
+
+  // Enable the I2C master mode and wait for sync
+  s->I2CM.CTRLA.bit.ENABLE = 1 ;
+  while (s->I2CM.SYNCBUSY.bit.ENABLE != 0);
+
+  // Setting bus idle mode and wait for sync
+  s->I2CM.STATUS.bit.BUSSTATE = 1 ;
+  while (s->I2CM.SYNCBUSY.bit.SYSOP != 0);
+
+  // Set SDA/SCL pins as outputs and enable pullups, at present we assume these are
+  // the default ones for SERCOM3 (see assumption above)
+  pinPeripheral(PIN_WIRE_SDA, g_APinDescription[PIN_WIRE_SDA].ulPinType);
+  pinPeripheral(PIN_WIRE_SCL, g_APinDescription[PIN_WIRE_SCL].ulPinType);
+
+  // Enable the SCL and SDA pins on the sercom: includes increased driver strength,
+  // pull-up resistors and pin multiplexer
+	PORT->Group[g_APinDescription[PIN_WIRE_SCL].ulPort].PINCFG[g_APinDescription[PIN_WIRE_SCL].ulPin].reg =  
+		PORT_PINCFG_DRVSTR | PORT_PINCFG_PULLEN | PORT_PINCFG_PMUXEN;  
+  PORT->Group[g_APinDescription[PIN_WIRE_SDA].ulPort].PINCFG[g_APinDescription[PIN_WIRE_SDA].ulPin].reg = 
+	  PORT_PINCFG_DRVSTR | PORT_PINCFG_PULLEN | PORT_PINCFG_PMUXEN;
+}
+
+/***************************************************************************
+ *  Initiate a start bit for transmission.
+ ***************************************************************************/
+void I2CManagerClass::I2C_sendStart() {
+
+  // Set counters here in case this is a retry.
+  txCount = 0;
+  rxCount = 0;
+
+  // On a single-master I2C bus, the start bit won't be sent until the bus 
+  // state goes to IDLE so we can request it without waiting.  On a 
+  // multi-master bus, the bus may be BUSY under control of another master, 
+  // in which case we can avoid some arbitration failures by waiting until
+  // the bus state is IDLE.  We don't do that here.
+
+  // If anything to send, initiate write.  Otherwise initiate read.
+  if (operation == OPERATION_READ || ((operation == OPERATION_REQUEST) && !bytesToSend))
+  {
+    // Send start and address with read flag (1) or'd in
+    s->I2CM.ADDR.bit.ADDR = (deviceAddress << 1) | 1;
+  }
+  else {
+    // Send start and address with write flag (0) or'd in
+    s->I2CM.ADDR.bit.ADDR = (deviceAddress << 1ul) | 0;
+  }
+}
+
+/***************************************************************************
+ *  Initiate a stop bit for transmission (does not interrupt)
+ ***************************************************************************/
+void I2CManagerClass::I2C_sendStop() {
+  s->I2CM.CTRLB.bit.CMD = 3; // Stop condition
+}
+
+/***************************************************************************
+ *  Close I2C down
+ ***************************************************************************/
+void I2CManagerClass::I2C_close() {
+  I2C_sendStop();
+  // Disable the I2C master mode and wait for sync
+  s->I2CM.CTRLA.bit.ENABLE = 0 ;
+  // Wait for up to 500us only.
+  unsigned long startTime = micros();
+  while (s->I2CM.SYNCBUSY.bit.ENABLE != 0) {
+    if (micros() - startTime >= 500UL) break;
+  }
+}
+
+/***************************************************************************
+ *  Main state machine for I2C, called from interrupt handler or,
+ *  if I2C_USE_INTERRUPTS isn't defined, from the I2CManagerClass::loop() function
+ *  (and therefore, indirectly, from I2CRB::wait() and I2CRB::isBusy()).
+ ***************************************************************************/
+void I2CManagerClass::I2C_handleInterrupt() {
+
+  if (s->I2CM.STATUS.bit.ARBLOST) {
+    // Arbitration lost, restart
+    I2C_sendStart();   // Reinitiate request
+  } else if (s->I2CM.STATUS.bit.BUSERR) {
+    // Bus error
+    completionStatus = I2C_STATUS_BUS_ERROR;
+    state = I2C_STATE_COMPLETED;  // Completed with error
+  } else if (s->I2CM.INTFLAG.bit.MB) {
+    // Master write completed
+    if (s->I2CM.STATUS.bit.RXNACK) {
+      // Nacked, send stop.
+      I2C_sendStop();
+      completionStatus = I2C_STATUS_NEGATIVE_ACKNOWLEDGE;
+      state = I2C_STATE_COMPLETED;  // Completed with error
+    } else if (bytesToSend) {
+      // Acked, so send next byte
+      s->I2CM.DATA.bit.DATA = sendBuffer[txCount++];
+      bytesToSend--;
+    } else if (bytesToReceive) {
+      // Last sent byte acked and no more to send.  Send repeated start, address and read bit.
+      s->I2CM.ADDR.bit.ADDR = (deviceAddress << 1) | 1;
+    } else {
+      // No more data to send/receive. Initiate a STOP condition
+      I2C_sendStop();
+      state = I2C_STATE_COMPLETED;  // Completed OK
+    }
+  } else if (s->I2CM.INTFLAG.bit.SB) {
+    // Master read completed without errors
+    if (bytesToReceive == 1) {
+      s->I2CM.CTRLB.bit.ACKACT = 1;  // NAK final byte
+      I2C_sendStop();  // send stop
+      receiveBuffer[rxCount++] = s->I2CM.DATA.bit.DATA;  // Store received byte
+      bytesToReceive = 0;
+      state = I2C_STATE_COMPLETED;  // Completed OK
+    } else if (bytesToReceive) {
+      s->I2CM.CTRLB.bit.ACKACT = 0;  // ACK all but final byte
+      receiveBuffer[rxCount++] = s->I2CM.DATA.bit.DATA;  // Store received byte
+      bytesToReceive--;
+    }
+  }
+}
+
+#endif /* I2CMANAGER_SAMD_H */

I2CManager_STM32.h

@@ -0,0 +1,520 @@
+/*
+ *  © 2022-24 Paul M Antoine
+ *  © 2023, Neil McKechnie
+ *  All rights reserved.
+ *
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef I2CMANAGER_STM32_H
+#define I2CMANAGER_STM32_H
+
+#include <Arduino.h>
+#include "I2CManager.h"
+#include "I2CManager_NonBlocking.h"   // to satisfy intellisense
+
+#include <wiring_private.h>
+#include "stm32f4xx_hal_rcc.h"
+
+/*****************************************************************************
+ *  STM32F4xx I2C native driver support
+ * 
+ *  Nucleo-64 and Nucleo-144 boards all use I2C1 as the default I2C peripheral
+ *  Later we may wish to support other STM32 boards, allow use of an alternate
+ *  I2C bus, or more than one I2C bus on the STM32 architecture 
+ *****************************************************************************/
+#if defined(I2C_USE_INTERRUPTS) && defined(ARDUINO_ARCH_STM32)
+#if defined(ARDUINO_NUCLEO_F401RE) || defined(ARDUINO_NUCLEO_F411RE) || defined(ARDUINO_NUCLEO_F446RE) \
+    || defined(ARDUINO_NUCLEO_F412ZG) || defined(ARDUINO_NUCLEO_F413ZH) || defined(ARDUINO_NUCLEO_F446ZE) \
+    || defined(ARDUINO_NUCLEO_F429ZI) || defined(ARDUINO_NUCLEO_F439ZI) || defined(ARDUINO_NUCLEO_F4X9ZI)
+
+// Assume I2C1 for now - default I2C bus on Nucleo-F411RE and likely all Nucleo-64
+// and Nucleo-144 variants
+I2C_TypeDef *s = I2C1;
+
+// In init we will ask the STM32 HAL layer for the configured APB1 clock frequency in Hz
+uint32_t APB1clk1; // Peripheral Input Clock speed in Hz.
+uint32_t i2c_MHz;  // Peripheral Input Clock speed in MHz.
+
+// IRQ handler for I2C1, replacing the weak definition in the STM32 HAL 
+extern "C" void I2C1_EV_IRQHandler(void) {
+  I2CManager.handleInterrupt();
+}
+extern "C" void I2C1_ER_IRQHandler(void) {
+  I2CManager.handleInterrupt();
+}
+#else
+#warning STM32 board selected is not yet supported - so I2C1 peripheral is not defined
+#endif
+#endif
+
+// Peripheral Input Clock speed in MHz.
+// For STM32F446RE, the speed is 45MHz.  Ideally, this should be determined
+// at run-time from the APB1 clock, as it can vary from STM32 family to family.
+// #define I2C_PERIPH_CLK 45
+
+// I2C SR1 Status Register #1 bit definitions for convenience
+// #define I2C_SR1_SMBALERT  (1<<15)   // SMBus alert
+// #define I2C_SR1_TIMEOUT   (1<<14)   // Timeout of Tlow error
+// #define I2C_SR1_PECERR    (1<<12)   // PEC error in reception
+// #define I2C_SR1_OVR       (1<<11)   // Overrun/Underrun error
+// #define I2C_SR1_AF        (1<<10)   // Acknowledge failure
+// #define I2C_SR1_ARLO      (1<<9)    // Arbitration lost (master mode)
+// #define I2C_SR1_BERR      (1<<8)    // Bus error (misplaced start or stop condition)
+// #define I2C_SR1_TxE       (1<<7)    // Data register empty on transmit
+// #define I2C_SR1_RxNE      (1<<6)    // Data register not empty on receive
+// #define I2C_SR1_STOPF     (1<<4)    // Stop detection (slave mode)
+// #define I2C_SR1_ADD10     (1<<3)    // 10 bit header sent
+// #define I2C_SR1_BTF       (1<<2)    // Byte transfer finished - data transfer done
+// #define I2C_SR1_ADDR      (1<<1)    // Address sent (master) or matched (slave)
+// #define I2C_SR1_SB        (1<<0)    // Start bit (master mode) 1=start condition generated
+
+// I2C CR1 Control Register #1 bit definitions for convenience
+// #define I2C_CR1_SWRST     (1<<15)   // Software reset - places peripheral under reset
+// #define I2C_CR1_ALERT     (1<<13)   // SMBus alert assertion
+// #define I2C_CR1_PEC       (1<<12)   // Packet Error Checking transfer in progress
+// #define I2C_CR1_POS       (1<<11)   // Acknowledge/PEC Postion (for data reception in PEC mode)
+// #define I2C_CR1_ACK       (1<<10)   // Acknowledge enable - ACK returned after byte is received (address or data)
+// #define I2C_CR1_STOP      (1<<9)    // STOP generated
+// #define I2C_CR1_START     (1<<8)    // START generated
+// #define I2C_CR1_NOSTRETCH (1<<7)    // Clock stretching disable (slave mode)
+// #define I2C_CR1_ENGC      (1<<6)    // General call (broadcast) enable (address 00h is ACKed)
+// #define I2C_CR1_ENPEC     (1<<5)    // PEC Enable
+// #define I2C_CR1_ENARP     (1<<4)    // ARP enable (SMBus)
+// #define I2C_CR1_SMBTYPE   (1<<3)    // SMBus type, 1=host, 0=device
+// #define I2C_CR1_SMBUS     (1<<1)    // SMBus mode, 1=SMBus, 0=I2C
+// #define I2C_CR1_PE        (1<<0)    // I2C Peripheral enable
+
+// States of the STM32 I2C driver state machine
+enum {TS_IDLE,TS_START,TS_W_ADDR,TS_W_DATA,TS_W_STOP,TS_R_ADDR,TS_R_DATA,TS_R_STOP};
+
+
+/***************************************************************************
+ *  Set I2C clock speed register.  This should only be called outside of
+ *  a transmission.  The I2CManagerClass::_setClock() function ensures 
+ *  that it is only called at the beginning of an I2C transaction.
+ ***************************************************************************/
+void I2CManagerClass::I2C_setClock(uint32_t i2cClockSpeed) {
+  // Calculate a rise time appropriate to the requested bus speed
+  // Use 10x the rise time spec to enable integer divide of 50ns clock period
+  uint16_t t_rise;
+
+  while (s->CR1 & I2C_CR1_STOP);  // Prevents lockup by guarding further
+                                  // writes to CR1 while STOP is being executed!
+
+  // Disable the I2C device, as TRISE can only be programmed whilst disabled
+  s->CR1 &= ~(I2C_CR1_PE);  // Disable I2C
+  s->CR1 |= I2C_CR1_SWRST;  // reset the I2C
+  asm("nop");    // wait a bit... suggestion from online!
+  s->CR1 &= ~(I2C_CR1_SWRST); // Normal operation
+
+  if (i2cClockSpeed > 100000UL)
+  {
+    // if (i2cClockSpeed > 400000L)
+    //   i2cClockSpeed = 400000L;
+
+    t_rise = 300;  // nanoseconds
+  }
+  else
+  {
+    // i2cClockSpeed = 100000L;
+    t_rise = 1000;  // nanoseconds
+  }
+  // Configure the rise time register - max allowed tRISE is 1000ns,
+  // so value = 1000ns * I2C_PERIPH_CLK MHz / 1000 + 1.
+  s->TRISE = (t_rise * i2c_MHz / 1000) + 1;
+
+  // Bit 15: I2C Master mode, 0=standard, 1=Fast Mode
+  // Bit 14: Duty, fast mode duty cycle (use 2:1)
+  // Bit 11-0: FREQR
+  // if (i2cClockSpeed > 400000UL) {
+  //   // In fast mode plus, I2C period is 3 * CCR * TPCLK1.
+  //   // s->CCR &= ~(0x3000); // Clear all bits except 12 and 13 which must remain per reset value
+  //   s->CCR = APB1clk1 / 3 / i2cClockSpeed; // Set I2C clockspeed to start!
+  //   s->CCR |= 0xC000; // We need Fast Mode AND DUTY bits set
+  // } else {
+    // In standard and fast mode, I2C period is 2 * CCR * TPCLK1
+    s->CCR &= ~(0x3000); // Clear all bits except 12 and 13 which must remain per reset value
+    s->CCR |= (APB1clk1 / 2 / i2cClockSpeed); // Set I2C clockspeed to start!
+    // s->CCR |= (i2c_MHz * 500 / (i2cClockSpeed / 1000)); // Set I2C clockspeed to start!
+    // if (i2cClockSpeed > 100000UL)
+    //     s->CCR |= 0xC000; // We need Fast Mode bits set as well
+  // }
+
+  // DIAG(F("I2C_init() peripheral clock is now: %d, full reg is %x"), (s->CR2 & 0xFF), s->CR2);
+  // DIAG(F("I2C_init() peripheral CCR is now: %d"), s->CCR);
+  // DIAG(F("I2C_init() peripheral TRISE is now: %d"), s->TRISE);
+
+  // Enable the I2C master mode
+  s->CR1 |= I2C_CR1_PE;  // Enable I2C
+}
+
+/***************************************************************************
+ *  Initialise I2C registers.
+ ***************************************************************************/
+void I2CManagerClass::I2C_init()
+{
+  // Query the clockspeed from the STM32 HAL layer
+  APB1clk1 = HAL_RCC_GetPCLK1Freq();
+  i2c_MHz = APB1clk1 / 1000000UL;
+  // DIAG(F("I2C_init() peripheral clock speed is: %d"), i2c_MHz);
+  // Enable clocks
+  RCC->APB1ENR |= RCC_APB1ENR_I2C1EN;//(1 << 21); // Enable I2C CLOCK
+  // Reset the I2C1 peripheral to initial state
+  RCC->APB1RSTR |=  RCC_APB1RSTR_I2C1RST;
+	RCC->APB1RSTR &= ~RCC_APB1RSTR_I2C1RST;
+  // Standard I2C pins are SCL on PB8 and SDA on PB9
+  RCC->AHB1ENR |= (1<<1);   // Enable GPIOB CLOCK for PB8/PB9
+  // Bits (17:16)= 1:0 --> Alternate Function for Pin PB8;
+  // Bits (19:18)= 1:0 --> Alternate Function for Pin PB9
+  GPIOB->MODER &= ~((3<<(8*2)) | (3<<(9*2)));    // Clear all MODER bits for PB8 and PB9
+  GPIOB->MODER |= (2<<(8*2)) | (2<<(9*2));    // PB8 and PB9 set to ALT function
+  GPIOB->OTYPER |= (1<<8) | (1<<9);           // PB8 and PB9 set to open drain output capability
+  GPIOB->OSPEEDR |= (3<<(8*2)) | (3<<(9*2));  // PB8 and PB9 set to High Speed mode
+  GPIOB->PUPDR &= ~((3<<(8*2)) | (3<<(9*2))); // Clear all PUPDR bits for PB8 and PB9
+  // GPIOB->PUPDR |= (1<<(8*2)) | (1<<(9*2));    // PB8 and PB9 set to pull-up capability
+  // Alt Function High register routing pins PB8 and PB9 for I2C1:
+  // Bits (3:2:1:0) = 0:1:0:0 --> AF4 for pin PB8
+  // Bits (7:6:5:4) = 0:1:0:0 --> AF4 for pin PB9
+  GPIOB->AFR[1] &= ~((15<<0) | (15<<4));      // Clear all AFR bits for PB8 on low nibble, PB9 on next nibble up
+  GPIOB->AFR[1] |= (4<<0) | (4<<4);           // PB8 on low nibble, PB9 on next nibble up
+
+  // Software reset the I2C peripheral
+  I2C1->CR1 &= ~I2C_CR1_PE; // Disable I2C1 peripheral
+  s->CR1 |= I2C_CR1_SWRST;  // reset the I2C
+  asm("nop");    // wait a bit... suggestion from online!
+  s->CR1 &= ~(I2C_CR1_SWRST); // Normal operation
+
+  // Clear all bits in I2C CR2 register except reserved bits
+  s->CR2 &= 0xE000;
+
+  // Set I2C peripheral clock frequency
+  // s->CR2 |= I2C_PERIPH_CLK;
+  s->CR2 |= i2c_MHz;
+  // DIAG(F("I2C_init() peripheral clock is now: %d"), s->CR2);
+
+  // set own address to 00 - not used in master mode
+  I2C1->OAR1 = (1 << 14); // bit 14 should be kept at 1 according to the datasheet
+
+#if defined(I2C_USE_INTERRUPTS)
+  // Setting NVIC
+  NVIC_SetPriority(I2C1_EV_IRQn, 1);  // Match default priorities
+  NVIC_EnableIRQ(I2C1_EV_IRQn);
+  NVIC_SetPriority(I2C1_ER_IRQn, 1);  // Match default priorities
+  NVIC_EnableIRQ(I2C1_ER_IRQn);
+
+  // CR2 Interrupt Settings
+  // Bit 15-13: reserved
+  // Bit 12: LAST - DMA last transfer
+  // Bit 11: DMAEN - DMA enable
+  // Bit 10: ITBUFEN - Buffer interrupt enable
+  // Bit 9: ITEVTEN - Event interrupt enable
+  // Bit 8: ITERREN - Error interrupt enable
+  // Bit 7-6: reserved
+  // Bit 5-0: FREQ - Peripheral clock frequency (max 50MHz)
+  s->CR2 |= (I2C_CR2_ITBUFEN | I2C_CR2_ITEVTEN | I2C_CR2_ITERREN);   // Enable Buffer, Event and Error interrupts
+#endif
+
+  // DIAG(F("I2C_init() setting initial I2C clock to 100KHz"));
+  // Calculate baudrate and set default rate for now
+  // Configure the Clock Control Register for 100KHz SCL frequency
+  // Bit 15: I2C Master mode, 0=standard, 1=Fast Mode
+  // Bit 14: Duty, fast mode duty cycle
+  // Bit 11-0: so CCR divisor would be clk / 2 / 100000 (where clk is in Hz)
+  // s->CCR = I2C_PERIPH_CLK * 5;
+  s->CCR &= ~(0x3000); // Clear all bits except 12 and 13 which must remain per reset value
+  s->CCR |= (APB1clk1 / 2 / 100000UL); // Set a default of 100KHz I2C clockspeed to start!
+
+  // Configure the rise time register - max allowed is 1000ns, so value = 1000ns * I2C_PERIPH_CLK MHz / 1000 + 1.
+  s->TRISE = (1000 * i2c_MHz / 1000) + 1;
+
+  // DIAG(F("I2C_init() peripheral clock is now: %d, full reg is %x"), (s->CR2 & 0xFF), s->CR2);
+  // DIAG(F("I2C_init() peripheral CCR is now: %d"), s->CCR);
+  // DIAG(F("I2C_init() peripheral TRISE is now: %d"), s->TRISE);
+
+  // Enable the I2C master mode
+  s->CR1 |= I2C_CR1_PE;  // Enable I2C
+}
+
+/***************************************************************************
+ *  Initiate a start bit for transmission.
+ ***************************************************************************/
+void I2CManagerClass::I2C_sendStart() {
+
+  // Set counters here in case this is a retry.
+  rxCount = txCount = 0;
+
+  // On a single-master I2C bus, the start bit won't be sent until the bus
+  // state goes to IDLE so we can request it without waiting.  On a
+  // multi-master bus, the bus may be BUSY under control of another master,
+  // in which case we can avoid some arbitration failures by waiting until
+  // the bus state is IDLE.  We don't do that here.
+  //while (s->SR2 & I2C_SR2_BUSY) {}
+
+  // Check there's no STOP still in progress.  If we OR the START bit into CR1
+  // and the STOP bit is already set, we could output multiple STOP conditions.
+  while (s->CR1 & I2C_CR1_STOP) {}  // Wait for STOP bit to reset
+
+  s->CR2 |= (I2C_CR2_ITEVTEN | I2C_CR2_ITERREN);  // Enable interrupts
+  s->CR2 &= ~I2C_CR2_ITBUFEN;     // Don't enable buffer interupts yet.
+  s->CR1 &= ~I2C_CR1_POS;   // Clear the POS bit
+  s->CR1 |= (I2C_CR1_ACK | I2C_CR1_START);   // Enable the ACK and generate START
+  transactionState = TS_START;
+}
+
+/***************************************************************************
+ *  Initiate a stop bit for transmission (does not interrupt)
+ ***************************************************************************/
+void I2CManagerClass::I2C_sendStop() {
+  s->CR1 |= I2C_CR1_STOP; // Stop I2C
+}
+
+/***************************************************************************
+ *  Close I2C down
+ ***************************************************************************/
+void I2CManagerClass::I2C_close() {
+  I2C_sendStop();
+  // Disable the I2C master mode and wait for sync
+  s->CR1 &= ~I2C_CR1_PE;  // Disable I2C peripheral
+  // Should never happen, but wait for up to 500us only.
+  unsigned long startTime = micros();
+  while ((s->CR1 & I2C_CR1_PE) != 0) {
+    if ((int32_t)(micros() - startTime) >= 500) break;
+  }
+  NVIC_DisableIRQ(I2C1_EV_IRQn);
+  NVIC_DisableIRQ(I2C1_ER_IRQn);
+}
+
+/***************************************************************************
+ *  Main state machine for I2C, called from interrupt handler or,
+ *  if I2C_USE_INTERRUPTS isn't defined, from the I2CManagerClass::loop() function
+ *  (and therefore, indirectly, from I2CRB::wait() and I2CRB::isBusy()).
+ ***************************************************************************/
+void I2CManagerClass::I2C_handleInterrupt() {
+  volatile uint16_t temp_sr1, temp_sr2;
+
+  temp_sr1 = s->SR1;
+
+  // Check for errors first
+  if (temp_sr1 & (I2C_SR1_AF | I2C_SR1_ARLO | I2C_SR1_BERR)) {
+    // Check which error flag is set
+    if (temp_sr1 & I2C_SR1_AF)
+    {
+      s->SR1 &= ~(I2C_SR1_AF); // Clear AF
+      I2C_sendStop(); // Clear the bus
+      transactionState = TS_IDLE;
+      completionStatus = I2C_STATUS_NEGATIVE_ACKNOWLEDGE;
+      state = I2C_STATE_COMPLETED;
+    }
+    else if (temp_sr1 & I2C_SR1_ARLO)
+    {
+      // Arbitration lost, restart
+      s->SR1 &= ~(I2C_SR1_ARLO); // Clear ARLO
+      I2C_sendStart(); // Reinitiate request
+      transactionState = TS_START;
+    }
+    else if (temp_sr1 & I2C_SR1_BERR)
+    {
+      // Bus error
+      s->SR1 &= ~(I2C_SR1_BERR); // Clear BERR
+      I2C_sendStop(); // Clear the bus
+      transactionState = TS_IDLE;
+      completionStatus = I2C_STATUS_BUS_ERROR;
+      state = I2C_STATE_COMPLETED;
+    }
+  } 
+  else {
+    // No error flags, so process event according to current state.
+    switch (transactionState) {
+      case TS_START:
+        if (temp_sr1 & I2C_SR1_SB) {
+          // Event EV5
+          // Start bit has been sent successfully and we have the bus.
+          // If anything to send, initiate write.  Otherwise initiate read.
+          if (operation == OPERATION_READ || ((operation == OPERATION_REQUEST) && !bytesToSend)) {
+            // Send address with read flag (1) or'd in
+            s->DR = (deviceAddress << 1) | 1;  //  send the address
+            transactionState = TS_R_ADDR;
+          } else {
+            // Send address with write flag (0) or'd in
+            s->DR = (deviceAddress << 1) | 0;  //  send the address
+            transactionState = TS_W_ADDR;
+          }
+        }
+        // SB bit is cleared by writing to DR (already done).
+        break;
+
+      case TS_W_ADDR:
+        if (temp_sr1 & I2C_SR1_ADDR) {
+          temp_sr2 = s->SR2; // read SR2 to complete clearing the ADDR bit
+          // Event EV6
+          // Address sent successfully, device has ack'd in response.
+          if (!bytesToSend) {
+            I2C_sendStop();
+            transactionState = TS_IDLE;
+            completionStatus = I2C_STATUS_OK;
+            state = I2C_STATE_COMPLETED;
+          } else {
+            // Put one byte into DR to load shift register.
+            s->DR = sendBuffer[txCount++];
+            bytesToSend--;
+            if (bytesToSend) {
+              // Put another byte to load DR
+              s->DR = sendBuffer[txCount++];
+              bytesToSend--;
+            }
+            if (!bytesToSend) {
+              // No more bytes to send.
+              // The TXE interrupt occurs when the DR is empty, and the BTF interrupt 
+              // occurs when the shift register is also empty (one character later).
+              // To avoid repeated TXE interrupts during this time, we disable TXE interrupt.
+              s->CR2 &= ~I2C_CR2_ITBUFEN;  // Wait for BTF interrupt, disable TXE interrupt
+              transactionState = TS_W_STOP;
+            } else {
+              // More data remaining to send after this interrupt, enable TXE interrupt.
+              s->CR2 |= I2C_CR2_ITBUFEN;
+              transactionState = TS_W_DATA;
+            }
+          }
+        }
+        break;
+
+      case TS_W_DATA:
+        if (temp_sr1 & I2C_SR1_TXE) {
+          // Event EV8_1/EV8
+          // Transmitter empty, write a byte to it.
+          if (bytesToSend) {
+            s->DR = sendBuffer[txCount++];
+            bytesToSend--;
+            if (!bytesToSend) {
+              s->CR2 &= ~I2C_CR2_ITBUFEN;  // Disable TXE interrupt
+              transactionState = TS_W_STOP;
+            }
+          }
+        } 
+        break;
+
+      case TS_W_STOP:
+        if (temp_sr1 & I2C_SR1_BTF) {
+          // Event EV8_2
+          // Done, last character sent. Anything to receive?
+          if (bytesToReceive) {
+            I2C_sendStart();
+            // NOTE: Three redundant BTF interrupts take place between the
+            // first BTF interrupt and the START interrupt.  I've tried all sorts
+            // of ways to eliminate them, and the only thing that worked for
+            // me was to loop until the BTF bit becomes reset.  Either way,
+            // it's a waste of processor time.  Anyone got a solution?
+            //while (s->SR1 && I2C_SR1_BTF) {}
+            transactionState = TS_START;
+          } else {
+            I2C_sendStop();
+            transactionState = TS_IDLE;
+            completionStatus = I2C_STATUS_OK;
+            state = I2C_STATE_COMPLETED;
+          }
+          s->SR1 &= I2C_SR1_BTF;  // Clear BTF interrupt
+        }
+        break;
+
+      case TS_R_ADDR:
+        if (temp_sr1 & I2C_SR1_ADDR) {
+          // Event EV6
+          // Address sent for receive.
+          // The next bit is different depending on whether there are 
+          // 1 byte, 2 bytes or >2 bytes to be received, in accordance with the
+          // Programmers Reference RM0390.
+          if (bytesToReceive == 1) {
+            // Receive 1 byte
+            s->CR1 &= ~I2C_CR1_ACK;  // Disable ack
+            temp_sr2 = s->SR2; // read SR2 to complete clearing the ADDR bit
+            // Next step will occur after a RXNE interrupt, so enable it
+            s->CR2 |= I2C_CR2_ITBUFEN;
+            transactionState = TS_R_STOP;
+          } else if (bytesToReceive == 2) {
+            // Receive 2 bytes
+            s->CR1 &= ~I2C_CR1_ACK;  // Disable ACK for final byte
+            s->CR1 |= I2C_CR1_POS;  // set POS flag to delay effect of ACK flag
+            // Next step will occur after a BTF interrupt, so disable RXNE interrupt
+            s->CR2 &= ~I2C_CR2_ITBUFEN;
+            temp_sr2 = s->SR2; // read SR2 to complete clearing the ADDR bit
+            transactionState = TS_R_STOP;
+          } else {
+            // >2 bytes, just wait for bytes to come in and ack them for the time being
+            // (ack flag has already been set).
+            // Next step will occur after a BTF interrupt, so disable RXNE interrupt
+            s->CR2 &= ~I2C_CR2_ITBUFEN;
+            temp_sr2 = s->SR2; // read SR2 to complete clearing the ADDR bit
+            transactionState = TS_R_DATA;
+          }
+        }
+        break;
+      
+      case TS_R_DATA:
+        // Event EV7/EV7_1
+        if (temp_sr1 & I2C_SR1_BTF) {
+          // Byte received in receiver - read next byte
+          if (bytesToReceive == 3) {
+            // Getting close to the last byte, so a specific sequence is recommended.
+            s->CR1 &= ~I2C_CR1_ACK;  // Reset ack for next byte received.
+            transactionState = TS_R_STOP;
+          }
+          receiveBuffer[rxCount++] = s->DR;  // Store received byte
+          bytesToReceive--;
+        } 
+        break;
+        
+      case TS_R_STOP:
+        if (temp_sr1 & I2C_SR1_BTF) {
+          // Event EV7 (last one)
+          // When we've got here, the receiver has got the last two bytes
+          // (or one byte, if only one byte is being received),
+          // and NAK has already been sent, so we need to read from the receiver.
+          if (bytesToReceive) {
+            if (bytesToReceive > 1) 
+              I2C_sendStop();
+            while(bytesToReceive) {
+              receiveBuffer[rxCount++] = s->DR;  // Store received byte(s)
+              bytesToReceive--;
+            }
+            // Finish.
+            transactionState = TS_IDLE;
+            completionStatus = I2C_STATUS_OK;
+            state = I2C_STATE_COMPLETED;
+          }
+        } else if (temp_sr1 & I2C_SR1_RXNE) {
+          if (bytesToReceive == 1) {
+            // One byte on a single-byte transfer.  Ack has already been set.
+            I2C_sendStop();
+            receiveBuffer[rxCount++] = s->DR; // Store received byte
+            bytesToReceive--;
+            // Finish.
+            transactionState = TS_IDLE;
+            completionStatus = I2C_STATUS_OK;
+            state = I2C_STATE_COMPLETED;
+          } else
+            s->SR1 &= I2C_SR1_RXNE;  // Acknowledge interrupt
+        }
+        break;
+    }
+    // If we've received an interrupt at any other time, we're not interested so clear it
+    // to prevent it recurring ad infinitum.
+    s->SR1 = 0;
+  }
+  
+}
+
+#endif /* I2CMANAGER_STM32_H */

I2CManager_Wire.h

@@ -1,5 +1,5 @@
 /*
- *  © 2021, Neil McKechnie. All rights reserved.
+ *  © 2023, Neil McKechnie. All rights reserved.
  *
  *  This file is part of CommandStation-EX
  *
@@ -30,11 +30,19 @@
 #define I2C_USE_WIRE
 #endif
 
+// Older versions of Wire don't have setWireTimeout function.  AVR does.
+#ifdef ARDUINO_ARCH_AVR
+#define WIRE_HAS_TIMEOUT
+#endif
+
 /***************************************************************************
  *  Initialise I2C interface software
  ***************************************************************************/
 void I2CManagerClass::_initialise() {
   Wire.begin();
+#if defined(WIRE_HAS_TIMEOUT) 
+  Wire.setWireTimeout(_timeout, true);
+#endif
 }
 
 /***************************************************************************
@@ -45,20 +53,85 @@ void I2CManagerClass::_setClock(unsigned long i2cClockSpeed) {
   Wire.setClock(i2cClockSpeed);
 }
 
+/***************************************************************************
+ *  Set I2C timeout value in microseconds.  The timeout applies to each
+ *   Wire call separately, i.e. in a write+read, the timer is reset before the
+ *   read is started.
+ ***************************************************************************/
+void I2CManagerClass::setTimeout(unsigned long value) {
+  _timeout = value;
+#if defined(WIRE_HAS_TIMEOUT) 
+  Wire.setWireTimeout(value, true);
+#endif
+}
+
+/********************************************************
+ * Helper function for I2C Multiplexer operations
+ ********************************************************/
+#ifdef I2C_EXTENDED_ADDRESS
+static uint8_t muxSelect(I2CAddress address) {
+  // Select MUX sub bus.
+  I2CMux muxNo = address.muxNumber();
+  I2CSubBus subBus = address.subBus();
+  if (muxNo != I2CMux_None) {
+    Wire.beginTransmission(I2C_MUX_BASE_ADDRESS+muxNo); 
+    uint8_t data =  (subBus == SubBus_All) ? 0xff :
+                    (subBus == SubBus_None) ? 0x00 :
+#if defined(I2CMUX_PCA9547)
+                    0x08 | subBus;
+#elif defined(I2CMUX_PCA9542) || defined(I2CMUX_PCA9544)
+                    0x04 | subBus;   // NB Only 2 or 4 subbuses respectively
+#else
+                    // Default behaviour for most MUXs is to use a mask
+                    // with a bit set for the subBus to be enabled
+                    1 << subBus;
+#endif
+    Wire.write(&data, 1);
+    return Wire.endTransmission(true);  // have to release I2C bus for it to work
+  }
+  return I2C_STATUS_OK;
+}
+#endif
+
+
 /***************************************************************************
  *  Initiate a write to an I2C device (blocking operation on Wire)
  ***************************************************************************/
-uint8_t I2CManagerClass::write(uint8_t address, const uint8_t buffer[], uint8_t size, I2CRB *rb) {
-  Wire.beginTransmission(address);
-  if (size > 0) Wire.write(buffer, size);
-  rb->status = Wire.endTransmission();
+uint8_t I2CManagerClass::write(I2CAddress address, const uint8_t buffer[], uint8_t size, I2CRB *rb) {
+  uint8_t status, muxStatus;
+  uint8_t retryCount = 0;
+  // If request fails, retry up to the defined limit, unless the NORETRY flag is set
+  // in the request block.
+  do {
+    status = muxStatus = I2C_STATUS_OK;
+#ifdef I2C_EXTENDED_ADDRESS
+    if (address.muxNumber() != I2CMux_None)
+      muxStatus = muxSelect(address);
+#endif
+    // Only send new transaction if address is non-zero.
+    if (muxStatus == I2C_STATUS_OK && address != 0) {
+      Wire.beginTransmission(address);
+      if (size > 0) Wire.write(buffer, size);
+      status = Wire.endTransmission();
+    }
+#ifdef I2C_EXTENDED_ADDRESS
+    // Deselect MUX if there's more than one MUX present, to avoid having multiple ones selected
+    if (_muxCount > 1 && muxStatus == I2C_STATUS_OK 
+          && address.deviceAddress() != 0 && address.muxNumber() != I2CMux_None) {
+      muxSelect({address.muxNumber(), SubBus_None});
+    }
+    if (muxStatus != I2C_STATUS_OK) status = muxStatus;
+#endif
+  } while (!(status == I2C_STATUS_OK
+    || ++retryCount > MAX_I2C_RETRIES || rb->operation & OPERATION_NORETRY));
+  rb->status = status;
   return I2C_STATUS_OK;
 }
 
 /***************************************************************************
  *  Initiate a write from PROGMEM (flash) to an I2C device (blocking operation on Wire)
  ***************************************************************************/
-uint8_t I2CManagerClass::write_P(uint8_t address, const uint8_t buffer[], uint8_t size, I2CRB *rb) {
+uint8_t I2CManagerClass::write_P(I2CAddress address, const uint8_t buffer[], uint8_t size, I2CRB *rb) {
   uint8_t ramBuffer[size];
   const uint8_t *p1 = buffer;
   for (uint8_t i=0; i<size; i++)
@@ -70,50 +143,87 @@ uint8_t I2CManagerClass::write_P(uint8_t address, const uint8_t buffer[], uint8_
  *  Initiate a write (optional) followed by a read from the I2C device (blocking operation on Wire)
  *  If fewer than the number of requested bytes are received, status is I2C_STATUS_TRUNCATED.
  ***************************************************************************/
-uint8_t I2CManagerClass::read(uint8_t address, uint8_t readBuffer[], uint8_t readSize,
+uint8_t I2CManagerClass::read(I2CAddress address, uint8_t readBuffer[], uint8_t readSize,
                               const uint8_t writeBuffer[], uint8_t writeSize, I2CRB *rb)
 {
-  uint8_t status = I2C_STATUS_OK;
+  uint8_t status, muxStatus;
   uint8_t nBytes = 0;
-  if (writeSize > 0) {
-    Wire.beginTransmission(address);
-    Wire.write(writeBuffer, writeSize);
-    status = Wire.endTransmission(false); // Don't free bus yet
-  }
-  if (status == I2C_STATUS_OK) {
-    Wire.requestFrom(address, (size_t)readSize);
-    while (Wire.available() && nBytes < readSize) 
-      readBuffer[nBytes++] = Wire.read();
-    if (nBytes < readSize) status = I2C_STATUS_TRUNCATED;
-  }
+  uint8_t retryCount = 0;
+  // If request fails, retry up to the defined limit, unless the NORETRY flag is set
+  // in the request block.
+  do {
+    status = muxStatus = I2C_STATUS_OK;
+#ifdef I2C_EXTENDED_ADDRESS
+    if (address.muxNumber() != I2CMux_None) {
+      muxStatus = muxSelect(address);
+    }
+#endif
+    // Only start new transaction if address is non-zero.
+    if (muxStatus == I2C_STATUS_OK && address != 0) {
+      if (writeSize > 0) {
+        Wire.beginTransmission(address);
+        Wire.write(writeBuffer, writeSize);
+        status = Wire.endTransmission(false); // Don't free bus yet
+      }
+      if (status == I2C_STATUS_OK) {
+#ifdef WIRE_HAS_TIMEOUT
+        Wire.clearWireTimeoutFlag();
+        Wire.requestFrom(address, (size_t)readSize);
+        if (!Wire.getWireTimeoutFlag()) {
+          while (Wire.available() && nBytes < readSize) 
+            readBuffer[nBytes++] = Wire.read();
+          if (nBytes < readSize) status = I2C_STATUS_TRUNCATED;
+        } else {
+          status = I2C_STATUS_TIMEOUT;
+        }
+#else
+        Wire.requestFrom(address, (size_t)readSize);
+          while (Wire.available() && nBytes < readSize) 
+            readBuffer[nBytes++] = Wire.read();
+          if (nBytes < readSize) status = I2C_STATUS_TRUNCATED;
+#endif
+      }
+    }
+#ifdef I2C_EXTENDED_ADDRESS
+    // Deselect MUX if there's more than one MUX present, to avoid having multiple ones selected
+    if (_muxCount > 1 && muxStatus == I2C_STATUS_OK && address != 0 && address.muxNumber() != I2CMux_None) {
+      muxSelect({address.muxNumber(), SubBus_None});
+    }
+    if (muxStatus != I2C_STATUS_OK) status = muxStatus;
+#endif
+
+  } while (!((status == I2C_STATUS_OK) 
+    || ++retryCount > MAX_I2C_RETRIES || rb->operation & OPERATION_NORETRY));
+
   rb->nBytes = nBytes;
   rb->status = status;
   return I2C_STATUS_OK;
 }
 
+
 /***************************************************************************
  *  Function to queue a request block and initiate operations.
  * 
- * For the Wire version, this executes synchronously, but the status is
- * returned in the I2CRB as for the asynchronous version.
+ * For the Wire version, this executes synchronously.
+ * The read/write/write_P functions return I2C_STATUS_OK always, and the 
+ * completion status of the operation is in the request block, as for
+ * the non-blocking version.
  ***************************************************************************/
 void I2CManagerClass::queueRequest(I2CRB *req) {
-  uint8_t status;
-  switch (req->operation) {
+  switch (req->operation & OPERATION_MASK) {
     case OPERATION_READ:
-      status = read(req->i2cAddress, req->readBuffer, req->readLen, NULL, 0, req);
+      read(req->i2cAddress, req->readBuffer, req->readLen, NULL, 0, req);
       break;
     case OPERATION_SEND:
-      status = write(req->i2cAddress, req->writeBuffer, req->writeLen, req);
+      write(req->i2cAddress, req->writeBuffer, req->writeLen, req);
       break;
     case OPERATION_SEND_P:
-      status = write_P(req->i2cAddress, req->writeBuffer, req->writeLen, req);
+      write_P(req->i2cAddress, req->writeBuffer, req->writeLen, req);
       break;
     case OPERATION_REQUEST:
-      status = read(req->i2cAddress, req->readBuffer, req->readLen, req->writeBuffer, req->writeLen, req);
+      read(req->i2cAddress, req->readBuffer, req->readLen, req->writeBuffer, req->writeLen, req);
       break;
   }
-  req->status = status;
 }
 
 /***************************************************************************
@@ -121,8 +231,4 @@ void I2CManagerClass::queueRequest(I2CRB *req) {
  ***************************************************************************/
 void I2CManagerClass::loop() {}
 
-// Loop function
-void I2CManagerClass::checkForTimeout() {}
-
-
-#endif
+#endif

IODevice.cpp

@@ -1,5 +1,7 @@
 /*
- *  © 2021, Neil McKechnie. All rights reserved.
+ *  © 2021 Neil McKechnie
+ *  © 2021 Harald Barth
+ *  All rights reserved.
  *  
  *  This file is part of DCC++EX API
  *
@@ -23,11 +25,16 @@
 #include "DIAG.h" 
 #include "FSH.h"
 #include "IO_MCP23017.h"
+#include "DCCTimer.h"
 
 #if defined(ARDUINO_ARCH_AVR) || defined(ARDUINO_ARCH_MEGAAVR)
 #define USE_FAST_IO
 #endif
 
+// Link to halSetup function.  If not defined, the function reference will be NULL.
+extern __attribute__((weak)) void halSetup();
+extern __attribute__((weak)) bool exrailHalSetup();
+
 //==================================================================================================================
 // Static methods
 //------------------------------------------------------------------------------------------------------------------
@@ -41,22 +48,55 @@
 // Create any standard device instances that may be required, such as the Arduino pins 
 // and PCA9685.
 void IODevice::begin() {
-  // Initialise the IO subsystem
+  // Initialise the IO subsystem defaults
   ArduinoPins::create(2, NUM_DIGITAL_PINS-2);  // Reserve pins for direct access
-  // Predefine two PCA9685 modules 0x40-0x41
-  // Allocates 32 pins 100-131
-  PCA9685::create(100, 16, 0x40);
-  PCA9685::create(116, 16, 0x41);
-  // Predefine two MCP23017 module 0x20/0x21
-  // Allocates 32 pins 164-195
-  MCP23017::create(164, 16, 0x20);
-  MCP23017::create(180, 16, 0x21);
 
-  // Call the begin() methods of each configured device in turn
-  for (IODevice *dev=_firstDevice; dev!=NULL; dev = dev->_nextDevice) {
+  // Call user's halSetup() function (if defined in the build in myHal.cpp).
+  //  The contents will depend on the user's system hardware configuration.
+  //  The myHal.cpp file is a standard C++ module so has access to all of the DCC++EX APIs.
+  // This is done early so that the subsequent defaults will detect an overlap and not
+  // create something that conflicts with the user's vpin definitions. 
+  if (halSetup)
+    halSetup();
+
+  // include any HAL devices defined in exrail. 
+  bool ignoreDefaults=false;
+  if (exrailHalSetup)
+    ignoreDefaults=exrailHalSetup();
+  if (ignoreDefaults) return;
+  
+  // Predefine two PCA9685 modules 0x40-0x41 if no conflicts
+  // Allocates 32 pins 100-131
+  const bool silent=true; // no message if these conflict
+  if (checkNoOverlap(100, 16, 0x40, silent)) {
+    PCA9685::create(100, 16, 0x40);
+  } 
+
+  if (checkNoOverlap(116, 16, 0x41, silent)) {
+    PCA9685::create(116, 16, 0x41);
+  } 
+  
+  // Predefine two MCP23017 module 0x20/0x21 if no conflicts
+  // Allocates 32 pins 164-195
+  if (checkNoOverlap(164, 16, 0x20, silent)) {
+    MCP23017::create(164, 16, 0x20);
+  } 
+
+  if (checkNoOverlap(180, 16, 0x21, silent)) {
+    MCP23017::create(180, 16, 0x21);
+  } 
+}
+
+// reset() function to reinitialise all devices
+void IODevice::reset() {
+  unsigned long currentMicros = micros();
+  for (IODevice *dev = _firstDevice; dev != NULL; dev = dev->_nextDevice) {
+    dev->_deviceState = DEVSTATE_DORMANT;
+    // First ensure that _loop isn't delaying 
+    dev->delayUntil(currentMicros);
+    // Then invoke _begin to restart driver
     dev->_begin();
   }
-  _initPhase = false;
 }
 
 // Overarching static loop() method for the IODevice subsystem.  Works through the
@@ -88,18 +128,19 @@ void IODevice::loop() {
   
   // Report loop time if diags enabled
 #if defined(DIAG_LOOPTIMES)
+  unsigned long diagMicros = micros();
   static unsigned long lastMicros = 0;
-  // Measure time since loop() method started.
-  unsigned long halElapsed = micros() - currentMicros;
-  // Measure time between loop() method entries.
-  unsigned long elapsed = currentMicros - lastMicros;
+  // Measure time since HAL's loop() method started.
+  unsigned long halElapsed = diagMicros - currentMicros;
+  // Measure time between loop() method entries (excluding this diagnostic).
+  unsigned long elapsed = diagMicros - lastMicros;
   static unsigned long maxElapsed = 0, maxHalElapsed = 0;
   static unsigned long lastOutputTime = 0;
   static unsigned long halTotal = 0, total = 0;
   static unsigned long count = 0;
   const unsigned long interval = (unsigned long)5 * 1000 * 1000; // 5 seconds in microsec
 
-  // Ignore long loop counts while message is still outputting
+  // Ignore long loop counts while message is still outputting (~3 milliseconds)
   if (currentMicros - lastOutputTime > 3000UL) {
     if (elapsed > maxElapsed) maxElapsed = elapsed;
     if (halElapsed > maxHalElapsed) maxHalElapsed = halElapsed;
@@ -107,14 +148,16 @@ void IODevice::loop() {
     total += elapsed;
     count++;
   }
-  if (currentMicros - lastOutputTime > interval) {
+  if (diagMicros - lastOutputTime > interval) {
     if (lastOutputTime > 0) 
       DIAG(F("Loop Total:%lus (%lus max) HAL:%lus (%lus max)"), 
         total/count, maxElapsed, halTotal/count, maxHalElapsed);
     maxElapsed = maxHalElapsed = total = halTotal = count = 0;
-    lastOutputTime = currentMicros;
+    lastOutputTime = diagMicros;
   }
-  lastMicros = currentMicros;
+  // Read microsecond count after calculations, so they aren't
+  // included in the overall timings.
+  lastMicros = micros();
 #endif
 }
 
@@ -130,6 +173,13 @@ bool IODevice::exists(VPIN vpin) {
   return findDevice(vpin) != NULL;
 }
 
+// Return the status of the device att vpin.
+uint8_t IODevice::getStatus(VPIN vpin) {
+  IODevice *dev = findDevice(vpin);
+  if (!dev) return false;
+  return dev->_deviceState;
+}
+
 // check whether the pin supports notification.  If so, then regular _read calls are not required.
 bool IODevice::hasCallback(VPIN vpin) {
   IODevice *dev = findDevice(vpin);
@@ -139,7 +189,7 @@ bool IODevice::hasCallback(VPIN vpin) {
 
 // Display (to diagnostics) details of the device.
 void IODevice::_display() {
-  DIAG(F("Unknown device Vpins:%d-%d %S"), 
+  DIAG(F("Unknown device Vpins:%u-%u %S"), 
     (int)_firstVpin, (int)_firstVpin+_nPins-1, _deviceState==DEVSTATE_FAILED ? F("OFFLINE") : F(""));
 }
 
@@ -148,9 +198,46 @@ void IODevice::_display() {
 bool IODevice::configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) {
   IODevice *dev = findDevice(vpin);
   if (dev) return dev->_configure(vpin, configType, paramCount, params);
+#ifdef DIAG_IO
+  DIAG(F("IODevice::configure(): VPIN %u not found!"), (int)vpin);
+#endif
   return false;
 }
 
+// Read value from virtual pin.
+int IODevice::read(VPIN vpin) {
+  for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) {
+    if (dev->owns(vpin)) 
+      return dev->_read(vpin);
+  }
+#ifdef DIAG_IO
+  DIAG(F("IODevice::read(): VPIN %u not found!"), (int)vpin);
+#endif
+  return false;
+}
+
+// Read analogue value from virtual pin.
+int IODevice::readAnalogue(VPIN vpin) {
+  for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) {
+    if (dev->owns(vpin)) 
+      return dev->_readAnalogue(vpin);
+  }
+#ifdef DIAG_IO
+  DIAG(F("IODevice::readAnalogue(): VPIN %u not found!"), (int)vpin);
+#endif
+  return -1023;
+}
+int IODevice::configureAnalogIn(VPIN vpin) {
+  for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) {
+    if (dev->owns(vpin)) 
+      return dev->_configureAnalogIn(vpin);
+  }
+#ifdef DIAG_IO
+  DIAG(F("IODevice::configureAnalogIn(): VPIN %u not found!"), (int)vpin);
+#endif
+  return -1023;
+}
+
 // Write value to virtual pin(s).  If multiple devices are allocated the same pin
 //  then only the first one found will be used.
 void IODevice::write(VPIN vpin, int value) {
@@ -160,10 +247,30 @@ void IODevice::write(VPIN vpin, int value) {
     return;
   }
 #ifdef DIAG_IO
-  DIAG(F("IODevice::write(): Vpin ID %d not found!"), (int)vpin);
+  DIAG(F("IODevice::write(): VPIN %u not found!"), (int)vpin);
 #endif
 }
 
+// Write value to count virtual pin(s).
+// these may be within one driver or separated over several drivers 
+void IODevice::writeRange(VPIN vpin, int value, int count) {  
+  
+  while(count) {  
+    auto dev = findDevice(vpin);
+    if (dev) {
+      auto vpinBefore=vpin; 
+      // write to driver, driver will return next vpin it cant handle
+      vpin=dev->_writeRange(vpin, value,count);
+      count-= vpin-vpinBefore;  // decrement by number of vpins changed
+    }
+    else {
+      // skip a vpin if no device handler
+      vpin++;
+      count--;
+    }
+  }
+}
+
 // Write analogue value to virtual pin(s).  If multiple devices are allocated
 // the same pin then only the first one found will be used.
 //
@@ -179,10 +286,28 @@ void IODevice::writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t para
     return;
   }
 #ifdef DIAG_IO
-  DIAG(F("IODevice::writeAnalogue(): Vpin ID %d not found!"), (int)vpin);
+  DIAG(F("IODevice::writeAnalogue(): VPIN %u not found!"), (int)vpin);
 #endif
 }
 
+//
+void IODevice::writeAnalogueRange(VPIN vpin, int value, uint8_t param1, uint16_t param2,int count) {
+  while(count) {  
+    auto dev = findDevice(vpin);
+    if (dev) {
+      auto vpinBefore=vpin; 
+      // write to driver, driver will return next vpin it cant handle
+      vpin=dev->_writeAnalogueRange(vpin, value, param1, param2,count);
+      count-= vpin-vpinBefore;  // decrement by number of vpins changed
+    }
+    else {
+      // skip a vpin if no device handler
+      vpin++;
+      count--;
+    }
+  }
+}
+
 // isBusy, when called for a device pin is always a digital output or analogue output,
 //  returns input feedback state of the pin, i.e. whether the pin is busy performing
 //  an animation or fade over a period of time.
@@ -200,25 +325,27 @@ void IODevice::setGPIOInterruptPin(int16_t pinNumber) {
   _gpioInterruptPin = pinNumber;
 }
 
-// Private helper function to add a device to the chain of devices.
-void IODevice::addDevice(IODevice *newDevice) {
-  // Link new object to the end of the chain.  Thereby, the first devices to be declared/created
-  // will be located faster by findDevice than those which are created later.
-  // Ideally declare/create the digital IO pins first, then servos, then more esoteric devices.
-  IODevice *lastDevice;
-  if (_firstDevice == 0)
+// Helper function to add a new device to the device chain.  If 
+// slaveDevice is NULL then the device is added to the end of the chain.
+// Otherwise, the chain is searched for slaveDevice and the new device linked
+// in front of it (to support filter devices that share the same VPIN range
+// as the devices they control).  If slaveDevice isn't found, then the
+// device is linked to the end of the chain.
+void IODevice::addDevice(IODevice *newDevice, IODevice *slaveDevice /* = NULL */) {
+  if (slaveDevice == _firstDevice) {
+    newDevice->_nextDevice = _firstDevice;
     _firstDevice = newDevice;
-  else {
-    for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice)
-      lastDevice = dev;
-    lastDevice->_nextDevice = newDevice;
+  } else {
+    for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) {
+      if (dev->_nextDevice == slaveDevice || dev->_nextDevice == NULL) {
+          // Link new device between dev and slaveDevice (or at end of chain)
+        newDevice->_nextDevice = dev->_nextDevice;
+        dev->_nextDevice = newDevice;
+        break;
+      }
+    }
   }
-  newDevice->_nextDevice = 0;
-
-  // If the IODevice::begin() method has already been called, initialise device here.  If not,
-  // the device's _begin() method will be called by IODevice::begin().
-  if (!_initPhase)
-    newDevice->_begin();
+  newDevice->_begin();
 }
 
 // Private helper function to locate a device by VPIN.  Returns NULL if not found.
@@ -231,7 +358,53 @@ IODevice *IODevice::findDevice(VPIN vpin) {
   }
   return NULL;
 }
+
+// Instance helper function for filter devices (layered over others).  Looks for 
+//  a device that is further down the chain than the current device.
+IODevice *IODevice::findDeviceFollowing(VPIN vpin) {
+  for (IODevice *dev = _nextDevice; dev != 0; dev = dev->_nextDevice) {
+    VPIN firstVpin = dev->_firstVpin;
+    if (vpin >= firstVpin && vpin < firstVpin+dev->_nPins)
+      return dev;
+  }
+  return NULL;
+}
+
+// Private helper function to check for vpin overlap. Run during setup only.
+// returns true if pins DONT overlap with existing device
+// TODO: Move the I2C address reservation and checks into the I2CManager code.
+// That will enable non-HAL devices to reserve I2C addresses too.
+// Silent is used by the default setup so that there is no message if the default 
+// device has already been handled by the user setup.
+bool IODevice::checkNoOverlap(VPIN firstPin, uint8_t nPins, 
+      I2CAddress i2cAddress, bool silent) {
+#ifdef DIAG_IO
+  DIAG(F("Check no overlap %u %u %s"), firstPin,nPins,i2cAddress.toString());
+#endif
+  VPIN lastPin=firstPin+nPins-1;
+  for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) {
+    
+    if (nPins > 0 && dev->_nPins > 0) {
+      // check for pin range overlaps (verbose but compiler will fix that)  
+      VPIN firstDevPin=dev->_firstVpin;
+      VPIN lastDevPin=firstDevPin+dev->_nPins-1;
+      bool noOverlap= firstPin>lastDevPin || lastPin<firstDevPin;
+      if (!noOverlap) {
+          if (!silent) DIAG(F("WARNING HAL Overlap, redefinition of Vpins %u to %u ignored."),
+              firstPin, lastPin);
+          return false;
+      } 
+    }
+    // Check for overlapping I2C address
+    if (i2cAddress && dev->_I2CAddress==i2cAddress) {
+      if (!silent) DIAG(F("WARNING HAL Overlap. i2c Addr %s ignored."),i2cAddress.toString());
+      return false;
+    } 
+  }
+  return true;  // no overlaps... OK to go on with constructor
+}
   
+
 //==================================================================================================================
 // Static data
 //------------------------------------------------------------------------------------------------------------------
@@ -239,15 +412,12 @@ IODevice *IODevice::findDevice(VPIN vpin) {
 // Chain of callback blocks (identifying registered callback functions for state changes)
 IONotifyCallback *IONotifyCallback::first = 0;
 
-// Start of chain of devices.
+// Start and end of chain of devices.
 IODevice *IODevice::_firstDevice = 0;
 
 // Reference to next device to be called on _loop() method.
 IODevice *IODevice::_nextLoopDevice = 0;
 
-// Flag which is reset when IODevice::begin has been called.
-bool IODevice::_initPhase = true;  
-
 
 //==================================================================================================================
 // Instance members
@@ -258,48 +428,22 @@ bool IODevice::owns(VPIN id) {
   return (id >= _firstVpin && id < _firstVpin + _nPins);
 }
 
-// Read value from virtual pin.
-int IODevice::read(VPIN vpin) {
-  for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) {
-    if (dev->owns(vpin)) 
-      return dev->_read(vpin);
-  }
-#ifdef DIAG_IO
-  DIAG(F("IODevice::read(): Vpin %d not found!"), (int)vpin);
-#endif
-  return false;
-}
-
-// Read analogue value from virtual pin.
-int IODevice::readAnalogue(VPIN vpin) {
-  for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) {
-    if (dev->owns(vpin)) 
-      return dev->_readAnalogue(vpin);
-  }
-#ifdef DIAG_IO
-  DIAG(F("IODevice::readAnalogue(): Vpin %d not found!"), (int)vpin);
-#endif
-  return false;
-}
-
 
 #else // !defined(IO_NO_HAL)
 
 // Minimal implementations of public HAL interface, to support Arduino pin I/O and nothing more.
 
 void IODevice::begin() { DIAG(F("NO HAL CONFIGURED!")); }
-bool IODevice::configure(VPIN pin, ConfigTypeEnum, int, int p[]) {
+bool IODevice::configure(VPIN pin, ConfigTypeEnum configType, int nParams, int p[]) {
+  if (configType!=CONFIGURE_INPUT || nParams!=1 || pin >= NUM_DIGITAL_PINS) return false;
   #ifdef DIAG_IO
-  DIAG(F("Arduino _configurePullup Pin:%d Val:%d"), pin, p[0]);
+  DIAG(F("Arduino _configurePullup pin:%d Val:%d"), pin, p[0]);
   #endif
-  if (p[0]) {
-    pinMode(pin, INPUT_PULLUP);
-  } else {
-    pinMode(pin, INPUT);
-  }
+  pinMode(pin, p[0] ? INPUT_PULLUP : INPUT);
   return true;
 }
 void IODevice::write(VPIN vpin, int value) {
+  if (vpin >= NUM_DIGITAL_PINS) return;
   digitalWrite(vpin, value);
   pinMode(vpin, OUTPUT);
 }
@@ -307,14 +451,14 @@ void IODevice::writeAnalogue(VPIN, int, uint8_t, uint16_t) {}
 bool IODevice::isBusy(VPIN) { return false; }
 bool IODevice::hasCallback(VPIN) { return false; }
 int IODevice::read(VPIN vpin) { 
+  if (vpin >= NUM_DIGITAL_PINS) return 0;
   return !digitalRead(vpin);  // Return inverted state (5v=0, 0v=1)
 }
 int IODevice::readAnalogue(VPIN vpin) {
-  pinMode(vpin, INPUT);
-  noInterrupts();
-  int value = analogRead(vpin);
-  interrupts();
-  return value;
+  return ADCee::read(vpin);
+}
+int IODevice::configureAnalogIn(VPIN vpin) {
+  return ADCee::init(vpin);
 }
 void IODevice::loop() {}
 void IODevice::DumpAll() {
@@ -416,7 +560,18 @@ int ArduinoPins::_read(VPIN vpin) {
 
 // Device-specific readAnalogue function (analogue input)
 int ArduinoPins::_readAnalogue(VPIN vpin) {
-  int pin = vpin;
+  if (vpin > 255) return -1023;
+  uint8_t pin = vpin;
+  int value = ADCee::read(pin);
+
+  #ifdef DIAG_IO
+  DIAG(F("Arduino Read Pin:%d Value:%d"), pin, value);
+  #endif
+  return value;
+}
+int ArduinoPins::_configureAnalogIn(VPIN vpin) {
+  if (vpin > 255) return -1023;
+  uint8_t pin = vpin;
   uint8_t mask = 1 << ((pin-_firstVpin) % 8);
   uint8_t index = (pin-_firstVpin) / 8;
   if (_pinModes[index] & mask) {
@@ -428,28 +583,15 @@ int ArduinoPins::_readAnalogue(VPIN vpin) {
     else
       pinMode(pin, INPUT);
   }
-
-  // Since AnalogRead is also called from interrupt code, disable interrupts 
-  // while we're using it.  There's only one ADC shared by all analogue inputs 
-  // on the Arduino, so we don't want interruptions.
-  //******************************************************************************
-  // NOTE: If the HAL is running on a computer without the DCC signal generator,
-  // then interrupts needn't be disabled.  Also, the DCC signal generator puts
-  // the ADC into fast mode, so if it isn't present, analogueRead calls will be much
-  // slower!!
-  //******************************************************************************
-  noInterrupts();
-  int value = analogRead(pin);
-  interrupts();
-
+  int value = ADCee::init(pin);
   #ifdef DIAG_IO
-  DIAG(F("Arduino Read Pin:%d Value:%d"), pin, value);
+  DIAG(F("configureAnalogIn Pin:%d Value:%d"), pin, value);
   #endif
   return value;
 }
 
 void ArduinoPins::_display() {
-  DIAG(F("Arduino Vpins:%d-%d"), (int)_firstVpin, (int)_firstVpin+_nPins-1);
+  DIAG(F("Arduino Vpins:%u-%u"), (int)_firstVpin, (int)_firstVpin+_nPins-1);
 }
 
 /////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -485,4 +627,3 @@ bool ArduinoPins::fastReadDigital(uint8_t pin) {
 #endif
   return result;
 }
-

IODevice.h

@@ -1,4 +1,5 @@
 /*
+ *  © 2023, Paul Antoine, Discord user @ADUBOURG
  *  © 2021, Neil McKechnie. All rights reserved.
  *  
  *  This file is part of DCC++EX API
@@ -26,12 +27,6 @@
 // Define symbol DIAG_LOOPTIMES to enable CS loop execution time to be reported
 //#define DIAG_LOOPTIMES
 
-// Define symbol IO_NO_HAL to reduce FLASH footprint when HAL features not required
-// The HAL is disabled by default on Nano and Uno platforms, because of limited flash space.
-#if defined(ARDUINO_AVR_NANO) || defined(ARDUINO_AVR_UNO) 
-#define IO_NO_HAL
-#endif
-
 // Define symbol IO_SWITCH_OFF_SERVO to set the PCA9685 output to 0 when an 
 // animation has completed.  This switches off the servo motor, preventing 
 // the continuous buzz sometimes found on servos, and reducing the 
@@ -43,6 +38,7 @@
 #include "FSH.h"
 #include "I2CManager.h"
 #include "inttypes.h"
+#include "TemplateForEnums.h"
 
 typedef uint16_t VPIN;
 // Limit VPIN number to max 32767.  Above this number, printing often gives negative values.
@@ -93,6 +89,8 @@ public:
     CONFIGURE_INPUT = 1,
     CONFIGURE_SERVO = 2,
     CONFIGURE_OUTPUT = 3,
+    CONFIGURE_ANALOGOUTPUT = 4,
+    CONFIGURE_ANALOGINPUT = 5,
   } ConfigTypeEnum;
 
   typedef enum : uint8_t {
@@ -110,6 +108,10 @@ public:
   // Also, the _begin method of any existing instances is called from here.
   static void begin();
 
+  // reset function to invoke all driver's _begin() methods again, to
+  // reset the state of the devices and reinitialise.
+  static void reset();
+
   // configure is used invoke an IODevice instance's _configure method
   static bool configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]);
 
@@ -127,9 +129,11 @@ public:
 
   // write invokes the IODevice instance's _write method.
   static void write(VPIN vpin, int value);
+  static void writeRange(VPIN vpin, int value,int count);
 
   // write invokes the IODevice instance's _writeAnalogue method (not applicable for digital outputs)
   static void writeAnalogue(VPIN vpin, int value, uint8_t profile=0, uint16_t duration=0);
+  static void writeAnalogueRange(VPIN vpin, int value, uint8_t profile, uint16_t duration, int count);
 
   // isBusy returns true if the device is currently in an animation of some sort, e.g. is changing
   //  the output over a period of time.
@@ -143,6 +147,7 @@ public:
 
   // read invokes the IODevice instance's _readAnalogue method.
   static int readAnalogue(VPIN vpin);
+  static int configureAnalogIn(VPIN vpin);
 
   // loop invokes the IODevice instance's _loop method.
   static void loop();
@@ -152,6 +157,9 @@ public:
   // exists checks whether there is a device owning the specified vpin
   static bool exists(VPIN vpin);
 
+  // getStatus returns the state of the device at the specified vpin
+  static uint8_t getStatus(VPIN vpin);
+
   // Enable shared interrupt on specified pin for GPIO extender modules.  The extender module
   // should pull down this pin when requesting a scan.  The pin may be shared by multiple modules.
   // Without the shared interrupt, input states are scanned periodically to detect changes on 
@@ -160,34 +168,41 @@ public:
   // once the GPIO port concerned has been read.
   void setGPIOInterruptPin(int16_t pinNumber);
 
-  
-protected:
-  
-  // Constructor
-  IODevice(VPIN firstVpin=0, int nPins=0) {
-    _firstVpin = firstVpin;
-    _nPins = nPins;
-    _nextEntryTime = 0;
-  }
+  // Method to check if pins will overlap before creating new device. 
+  static bool checkNoOverlap(VPIN firstPin, uint8_t nPins=1, 
+                  I2CAddress i2cAddress=0, bool silent=false);
 
- // Method to perform initialisation of the device (optionally implemented within device class)
-  virtual void _begin() {}
-
-  // Method to configure device (optionally implemented within device class)
-  virtual bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) { 
-    (void)vpin; (void)configType; (void)paramCount; (void)params; // Suppress compiler warning.
-    return false;
-  };
+  // Method used by IODevice filters to locate slave pins that may be overlayed by their own
+  // pin range.  
+  IODevice *findDeviceFollowing(VPIN vpin);
 
   // Method to write new state (optionally implemented within device class)
   virtual void _write(VPIN vpin, int value) {
     (void)vpin; (void)value;
   };
+ 
+ // Method to write new state (optionally implemented within device class)
+ // This will, by default just write to one vpin and return whet to do next.
+ // the real power comes where a single driver can update many vpins in one call.
+  virtual VPIN _writeRange(VPIN vpin, int value, int count) {
+    (void)count;
+    _write(vpin,value); 
+    return vpin+1; // try next vpin 
+  };
 
   // Method to write an 'analogue' value (optionally implemented within device class)
-  virtual void _writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t param2) {
+  virtual void _writeAnalogue(VPIN vpin, int value, uint8_t param1=0, uint16_t param2=0) {
     (void)vpin; (void)value; (void) param1; (void)param2;
   };
+  
+  // Method to write an 'analogue' value to a VPIN range (optionally implemented within device class)
+  // This will, by default just write to one vpin and return whet to do next.
+  // the real power comes where a single driver can update many vpins in one call.
+  virtual VPIN _writeAnalogueRange(VPIN vpin, int value, uint8_t param1, uint16_t param2, int count) {
+    (void) count;
+    _writeAnalogue(vpin, value,  param1, param2);
+    return vpin+1; 
+  };
 
   // Method to read digital pin state (optionally implemented within device class)
   virtual int _read(VPIN vpin) { 
@@ -201,6 +216,33 @@ protected:
     return 0;
   };
 
+protected:
+  
+  // Constructor
+  IODevice(VPIN firstVpin=0, int nPins=0) {
+    _firstVpin = firstVpin;
+    _nPins = nPins;
+    _nextEntryTime = 0;
+    _I2CAddress=0;
+  }
+
+  // Method to perform initialisation of the device (optionally implemented within device class)
+  virtual void _begin() {}
+
+  // Method to check whether the vpin corresponds to this device
+  bool owns(VPIN vpin);
+
+  // Method to configure device (optionally implemented within device class)
+  virtual bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) { 
+    (void)vpin; (void)configType; (void)paramCount; (void)params; // Suppress compiler warning.
+    return false;
+  };
+
+  virtual int _configureAnalogIn(VPIN vpin) { 
+    (void)vpin; 
+    return 0;
+  };
+
   // Method to perform updates on an ongoing basis (optionally implemented within device class)
   virtual void _loop(unsigned long currentMicros) {
     delayUntil(currentMicros + 0x7fffffff); // Largest time in the future!  Effectively disable _loop calls.
@@ -220,32 +262,29 @@ protected:
   // Common object fields.
   VPIN _firstVpin;
   int _nPins;
-
+  I2CAddress _I2CAddress;
   // Flag whether the device supports callbacks.
   bool _hasCallback = false;
 
   // Pin number of interrupt pin for GPIO extender devices.  The extender module will pull this
   //  pin low if an input changes state.
   int16_t _gpioInterruptPin = -1;
-
+    
   // Static support function for subclass creation
-  static void addDevice(IODevice *newDevice);
+  static void addDevice(IODevice *newDevice, IODevice *slaveDevice = NULL);
+
+  // Method to find device handling Vpin
+  static IODevice *findDevice(VPIN vpin);
 
   // Current state of device
   DeviceStateEnum _deviceState = DEVSTATE_DORMANT;
 
 private:
-  // Method to check whether the vpin corresponds to this device
-  bool owns(VPIN vpin);
-  // Method to find device handling Vpin
-  static IODevice *findDevice(VPIN vpin);
-
   IODevice *_nextDevice = 0;
   unsigned long _nextEntryTime;
   static IODevice *_firstDevice;
 
   static IODevice *_nextLoopDevice;
-  static bool _initPhase;
 };
 
 
@@ -256,9 +295,7 @@ private:
  
 class PCA9685 : public IODevice {
 public:
-  static void create(VPIN vpin, int nPins, uint8_t I2CAddress);
-  // Constructor
-  PCA9685(VPIN vpin, int nPins, uint8_t I2CAddress);
+  static void create(VPIN vpin, int nPins, I2CAddress i2cAddress, uint16_t frequency = 50);
   enum ProfileType : uint8_t {
     Instant = 0,  // Moves immediately between positions (if duration not specified)
     UseDuration = 0, // Use specified duration
@@ -270,6 +307,8 @@ public:
   };
 
 private:
+  // Constructor
+  PCA9685(VPIN vpin, int nPins, I2CAddress i2cAddress, uint16_t frequency);
   // Device-specific initialisation
   void _begin() override;
   bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) override;
@@ -281,8 +320,7 @@ private:
   void updatePosition(uint8_t pin);
   void writeDevice(uint8_t pin, int value);
   void _display() override;
-
-  uint8_t _I2CAddress; // 0x40-0x43 possible
+  
 
   struct ServoData {
     uint16_t activePosition : 12; // Config parameter
@@ -300,13 +338,14 @@ private:
   struct ServoData *_servoData [16];
 
   static const uint8_t _catchupSteps = 5; // number of steps to wait before switching servo off
-  static const byte FLASH _bounceProfile[30];
+  static const uint8_t FLASH _bounceProfile[30];
 
   const unsigned int refreshInterval = 50; // refresh every 50ms
 
   // structures for setting up non-blocking writes to servo controller
   I2CRB requestBlock;
   uint8_t outputBuffer[5];
+  uint8_t prescaler; // clock prescaler for setting PWM frequency
 };
 
 /////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -317,10 +356,10 @@ private:
 class DCCAccessoryDecoder: public IODevice {
 public:
   static void create(VPIN firstVpin, int nPins, int DCCAddress, int DCCSubaddress);
-  // Constructor
-  DCCAccessoryDecoder(VPIN firstVpin, int nPins, int DCCAddress, int DCCSubaddress);
 
 private:
+  // Constructor
+  DCCAccessoryDecoder(VPIN firstVpin, int nPins, int DCCAddress, int DCCSubaddress);
   // Device-specific write function.
   void _begin() override;
   void _write(VPIN vpin, int value) override;
@@ -340,13 +379,13 @@ public:
     addDevice(new ArduinoPins(firstVpin, nPins));
   }
   
-  // Constructor
-  ArduinoPins(VPIN firstVpin, int nPins);
-
   static void fastWriteDigital(uint8_t pin, uint8_t value);
   static bool fastReadDigital(uint8_t pin);
 
 private:
+  // Constructor
+  ArduinoPins(VPIN firstVpin, int nPins);
+
   // Device-specific pin configuration
   bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) override;
   // Device-specific write function.
@@ -354,6 +393,7 @@ private:
   // Device-specific read functions.
   int _read(VPIN vpin) override;
   int _readAnalogue(VPIN vpin) override;
+  int _configureAnalogIn(VPIN vpin) override;
   void _display() override;
 
 
@@ -362,10 +402,176 @@ private:
   uint8_t *_pinInUse; 
 };
 
+#ifndef IO_NO_HAL
 /////////////////////////////////////////////////////////////////////////////////////////////////////
+/*
+ * IODevice subclass for EX-Turntable.
+ */
+ 
+class EXTurntable : public IODevice {
+public:
+  static void create(VPIN firstVpin, int nPins, I2CAddress I2CAddress);
+  // Constructor
+  EXTurntable(VPIN firstVpin, int nPins, I2CAddress I2CAddress);
+  enum ActivityNumber : uint8_t {
+    Turn = 0,             // Rotate turntable, maintain phase
+    Turn_PInvert = 1,     // Rotate turntable, invert phase
+    Home = 2,             // Initiate homing
+    Calibrate = 3,        // Initiate calibration sequence
+    LED_On = 4,           // Turn LED on
+    LED_Slow = 5,         // Set LED to a slow blink
+    LED_Fast = 6,         // Set LED to a fast blink
+    LED_Off = 7,          // Turn LED off
+    Acc_On = 8,           // Turn accessory pin on
+    Acc_Off = 9,          // Turn accessory pin off
+  };
+
+private:
+  // Device-specific write function.
+  void _begin() override;
+  void _loop(unsigned long currentMicros) override;
+  int _read(VPIN vpin) override;
+  void _broadcastStatus (VPIN vpin, uint8_t status, uint8_t activity);
+  void _writeAnalogue(VPIN vpin, int value, uint8_t activity, uint16_t duration) override;
+  void _display() override;
+  uint8_t _stepperStatus;
+  uint8_t _previousStatus;
+  uint8_t _currentActivity;
+};
+#endif
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////
+
+
+// IODevice framework for invoking user-written functions.
+// To use, define a function that you want to be regularly
+// invoked, and then create an instance of UserAddin.  
+// For example, you can show the status, on screen 3, of the first eight
+// locos in the speed table:
+// 
+// void updateLocoScreen() {
+//   for (int i=0; i<8; i++) {
+//     if (DCC::speedTable[i].loco > 0) {
+//       int speed = DCC::speedTable[i].speedCode;
+//       SCREEN(3, i, F("Loco:%4d %3d %c"), DCC::speedTable[i].loco,
+//         speed & 0x7f, speed & 0x80 ? 'R' : 'F');
+//     }
+//   }
+// }
+//
+// void halSetup() {
+//   ...
+//   UserAddin(updateLocoScreen, 1000);  // Update every 1000ms
+//   ...
+// }
+//
+class UserAddin : public IODevice {
+private:
+  void (*_invokeUserFunction)();
+  int _delay; // milliseconds
+public:
+  UserAddin(void (*func)(), int delay) {
+    _invokeUserFunction = func; 
+    _delay = delay; 
+    addDevice(this); 
+  }
+  // userFunction has no return value, no parameter.  delay is in milliseconds.
+  static void create(void (*userFunction)(), int delay) {
+    new UserAddin(userFunction, delay);
+  }
+protected:
+  void _begin() { _display(); }
+  void _loop(unsigned long currentMicros) override {
+    _invokeUserFunction();
+    // _loop won't be called again until _delay ms have elapsed.
+    delayUntil(currentMicros + _delay * 1000UL);
+  }
+  void _display() override {
+    DIAG(F("UserAddin run every %dms"), _delay);
+  }
+};
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////
+// 
+// This HAL device driver is intended for communication in automation
+// sequences.  A VPIN can be SET or RESET within a sequence, and its
+// current state checked elsewhere using IF, IFNOT, AT etc. or monitored
+// from JMRI using a Sensor object (DCC-EX <S ...> command).
+// Alternatively, the flag can be set from JMRI and other interfaces
+// using the <Z ...> command, to enable or disable actions within a sequence.
+// 
+// Example of configuration in halSetup.h:
+// 
+//  FLAGS::create(32000, 128);
+// 
+// or in myAutomation.h:
+//  
+//  HAL(FLAGS, 32000, 128);
+// 
+// Both create 128 flags numbered with VPINs 32000-32127.
+// 
+//
+
+class FLAGS : IODevice {
+private:
+  uint8_t *_states = NULL;
+
+public:
+  static void create(VPIN firstVpin, unsigned int nPins) {
+    if (checkNoOverlap(firstVpin, nPins))
+        new FLAGS(firstVpin, nPins);
+  }
+
+protected:
+  // Constructor performs static initialisation of the device object
+  FLAGS (VPIN firstVpin, int nPins) {
+    _firstVpin = firstVpin;
+    _nPins = nPins;
+    _states = (uint8_t *)calloc(1, (_nPins+7)/8);
+    if (!_states) {
+      DIAG(F("FLAGS: ERROR Memory Allocation Failure"));
+      return;
+    }
+
+    addDevice(this);
+  }
+
+  int _read(VPIN vpin) override {
+    int pin = vpin - _firstVpin;
+    if (pin >= _nPins || pin < 0) return 0;
+    uint8_t mask = 1 << (pin & 7);
+    return (_states[pin>>3] & mask) ? 1 : 0;
+  }
+
+  void _write(VPIN vpin, int value) override {
+    int pin = vpin - _firstVpin;
+    if (pin >= _nPins || pin < 0) return;
+    uint8_t mask = 1 << (pin & 7);
+    if (value) 
+      _states[pin>>3] |= mask;
+    else
+      _states[pin>>3] &= ~mask;
+  }
+
+  void _display() override {
+    DIAG(F("FLAGS configured on VPINs %u-%u"),
+      _firstVpin, _firstVpin+_nPins-1);
+  }
+
+};
 
 #include "IO_MCP23008.h"
 #include "IO_MCP23017.h"
 #include "IO_PCF8574.h"
+#include "IO_PCF8575.h"
+#include "IO_PCA9555.h"
+#include "IO_duinoNodes.h"
+#include "IO_EXIOExpander.h"
+#include "IO_trainbrains.h"
+#include "IO_EncoderThrottle.h"
+#include "IO_TCA8418.h"
+#include "IO_NeoPixel.h"
+#include "IO_TM1638.h"
+#include "IO_EXSensorCAM.h"
 
-#endif // iodevice_h
+#endif // iodevice_h

IO_AnalogueInputs.h

@@ -59,28 +59,33 @@
  **********************************************************************************************/
 class ADS111x: public IODevice { 
 public:
-  ADS111x(VPIN firstVpin, int nPins, uint8_t i2cAddress) {
+  static void create(VPIN firstVpin, int nPins, I2CAddress i2cAddress) {
+    if (checkNoOverlap(firstVpin,nPins,i2cAddress)) new ADS111x(firstVpin, nPins, i2cAddress);
+  }
+private:
+  ADS111x(VPIN firstVpin, int nPins, I2CAddress i2cAddress) {
     _firstVpin = firstVpin;
-    _nPins = min(nPins,4);
-    _i2cAddress = i2cAddress;
+    _nPins = (nPins > 4) ? 4 : nPins;
+    _I2CAddress = i2cAddress;
     _currentPin = 0;
     for (int8_t i=0; i<_nPins; i++)
       _value[i] = -1;
     addDevice(this);
   }
-  static void create(VPIN firstVpin, int nPins, uint8_t i2cAddress) {
-    new ADS111x(firstVpin, nPins, i2cAddress);
-  }
-private:
   void _begin() {
+    // Initialise I2C
+    I2CManager.begin();
+    // ADS111x support high-speed I2C (4.3MHz) but that requires special
+    // processing.  So stick to fast mode (400kHz maximum).
+    I2CManager.setClock(400000);
     // Initialise ADS device
-    if (I2CManager.exists(_i2cAddress)) {
+    if (I2CManager.exists(_I2CAddress)) {
       _nextState = STATE_STARTSCAN;
 #ifdef DIAG_IO
       _display();
 #endif
     } else {
-      DIAG(F("ADS111x device not found, I2C:%x"), _i2cAddress);
+      DIAG(F("ADS111x device not found, I2C:%s"), _I2CAddress.toString());
       _deviceState = DEVSTATE_FAILED;
     }
   }
@@ -98,7 +103,7 @@ private:
           _outBuffer[1] = 0xC0 + (_currentPin << 4); // Trigger single-shot, channel n
           _outBuffer[2] = 0xA3;           // 250 samples/sec, comparator off
           // Write command, without waiting for completion.
-          I2CManager.write(_i2cAddress, _outBuffer, 3, &_i2crb);
+          I2CManager.write(_I2CAddress, _outBuffer, 3, &_i2crb);
 
           delayUntil(currentMicros + scanInterval);
           _nextState = STATE_STARTREAD;
@@ -107,14 +112,14 @@ private:
         case STATE_STARTREAD:
           // Reading the pin value
           _outBuffer[0] = 0x00;  // Conversion register address
-          I2CManager.read(_i2cAddress, _inBuffer, 2, _outBuffer, 1, &_i2crb); // Read register
+          I2CManager.read(_I2CAddress, _inBuffer, 2, _outBuffer, 1, &_i2crb); // Read register
           _nextState = STATE_GETVALUE;
           break;
 
         case STATE_GETVALUE:
           _value[_currentPin] = ((uint16_t)_inBuffer[0] << 8) + (uint16_t)_inBuffer[1];
           #ifdef IO_ANALOGUE_SLOW
-          DIAG(F("ADS111x pin:%d value:%d"), _currentPin, _value[_currentPin]);
+          DIAG(F("ADS111x VPIN:%u value:%d"), _currentPin, _value[_currentPin]);
           #endif
 
           // Move to next pin
@@ -126,7 +131,7 @@ private:
           break;
       }
     } else { // error status
-      DIAG(F("ADS111x I2C:x%d Error:%d %S"), _i2cAddress, status, I2CManager.getErrorMessage(status));
+      DIAG(F("ADS111x I2C:%s Error:%d %S"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status));
       _deviceState = DEVSTATE_FAILED;
     }
   }
@@ -137,7 +142,7 @@ private:
   }
   
   void _display() override {
-    DIAG(F("ADS111x I2C:x%x Configured on Vpins:%d-%d %S"), _i2cAddress, _firstVpin, _firstVpin+_nPins-1,
+    DIAG(F("ADS111x I2C:%s Configured on Vpins:%u-%u %S"), _I2CAddress.toString(), _firstVpin, _firstVpin+_nPins-1,
       _deviceState == DEVSTATE_FAILED ? F("OFFLINE") : F(""));
   }
 
@@ -154,7 +159,6 @@ private:
     STATE_GETVALUE,
   };
   uint16_t _value[4];
-  uint8_t _i2cAddress;
   uint8_t _outBuffer[3];
   uint8_t _inBuffer[2];
   uint8_t _currentPin;  // ADC pin currently being scanned
@@ -162,4 +166,4 @@ private:
   uint8_t _nextState;
 };
 
-#endif // io_analogueinputs_h
+#endif // io_analogueinputs_h

IO_DCCAccessory.cpp

@@ -26,8 +26,8 @@
 #define ADDRESS(packedaddr) ((packedaddr) >> 2)
 #define SUBADDRESS(packedaddr) ((packedaddr) % 4)
 
-void DCCAccessoryDecoder::create(VPIN vpin, int nPins, int DCCAddress, int DCCSubaddress) {
-  new DCCAccessoryDecoder(vpin, nPins, DCCAddress, DCCSubaddress);
+void DCCAccessoryDecoder::create(VPIN firstVpin, int nPins, int DCCAddress, int DCCSubaddress) {
+  if (checkNoOverlap(firstVpin,nPins)) new DCCAccessoryDecoder(firstVpin, nPins, DCCAddress, DCCSubaddress);
 }
 
 // Constructors
@@ -47,18 +47,21 @@ void DCCAccessoryDecoder::_begin() {
 // Device-specific write function.  State 1=closed, 0=thrown.  Adjust for RCN-213 compliance
 void DCCAccessoryDecoder::_write(VPIN id, int state) {
   int packedAddress = _packedAddress + id - _firstVpin;
-  #ifdef DIAG_IO
-  DIAG(F("DCC Write Linear Address:%d State:%d"), packedAddress, state);
-  #endif
-#if !defined(DCC_ACCESSORY_RCN_213)
+#if defined(HAL_ACCESSORY_COMMAND_REVERSE)
   state = !state;
+#ifdef DIAG_IO
+  DIAG(F("DCC Write Linear Address:%d State:%d (inverted)"), packedAddress, state);
+#endif
+#else
+#ifdef DIAG_IO
+  DIAG(F("DCC Write Linear Address:%d State:%d"), packedAddress, state);
+#endif
 #endif
   DCC::setAccessory(ADDRESS(packedAddress), SUBADDRESS(packedAddress), state);
 }
 
 void DCCAccessoryDecoder::_display() {
   int endAddress = _packedAddress + _nPins - 1;
-  DIAG(F("DCCAccessoryDecoder Configured on Vpins:%d-%d Addresses %d/%d-%d/%d)"), _firstVpin, _firstVpin+_nPins-1,
+  DIAG(F("DCCAccessoryDecoder Configured on Vpins:%u-%u Addresses %d/%d-%d/%d)"), _firstVpin, _firstVpin+_nPins-1,
       ADDRESS(_packedAddress), SUBADDRESS(_packedAddress), ADDRESS(endAddress), SUBADDRESS(endAddress));
 }
-

IO_DFPlayer.h

@@ -1,5 +1,5 @@
 /*
- *  © 2021, Neil McKechnie. All rights reserved.
+ *  © 2023, Neil McKechnie. All rights reserved.
  *  
  *  This file is part of DCC++EX API
  *
@@ -33,27 +33,41 @@
  *   and Serialn is the name of the Serial port connected to the DFPlayer (e.g. Serial1).
  * 
  * Example:
- *   In mySetup function within mySetup.cpp:
+ *   In halSetup function within myHal.cpp:
  *       DFPlayer::create(3500, 5, Serial1);
+ *   or in myAutomation.h:
+ *       HAL(DFPlayer, 3500, 5, Serial1)
  * 
- * Writing an analogue value 0-2999 to the first pin will select a numbered file from the SD card;
- * Writing an analogue value 0-30 to the second pin will set the volume of the output;
- * Writing a digital value to the first pin will play or stop the file;
+ * Writing an analogue value 1-2999 to the first pin (3500) will play the numbered file from the
+ * SD card; e.g. a value of 1 will play the first file, 2 for the second file etc.
+ * Writing an analogue value 0 to the first pin (3500) will stop the file playing;
+ * Writing an analogue value 0-30 to the second pin (3501) will set the volume;
+ * Writing a digital value of 1 to a pin will play the file corresponding to that pin, e.g.
+   the first file will be played by setting pin 3500, the second by setting pin 3501 etc.;
+ * Writing a digital value of 0 to any pin will stop the player;
  * Reading a digital value from any pin will return true(1) if the player is playing, false(0) otherwise.
  * 
  * From EX-RAIL, the following commands may be used:
- *   SET(3500)      -- starts playing the first file on the SD card
- *   SET(3501)      -- starts playing the second file on the SD card
+ *   SET(3500)      -- starts playing the first file (file 1) on the SD card
+ *   SET(3501)      -- starts playing the second file (file 2) on the SD card
  *   etc.
  *   RESET(3500)    -- stops all playing on the player
  *   WAITFOR(3500)  -- wait for the file currently being played by the player to complete
- *   SERVO(3500,23,0)  -- plays file 23 at current volume
- *   SERVO(3500,23,30)  -- plays file 23 at volume 30 (maximum)
- *   SERVO(3501,20,0)   -- Sets the volume to 20
+ *   SERVO(3500,2,Instant)  -- plays file 2 at current volume
+ *   SERVO(3501,20,Instant)   -- Sets the volume to 20
  * 
  * NB The DFPlayer's serial lines are not 5V safe, so connecting the Arduino TX directly 
  * to the DFPlayer's RX terminal will cause lots of noise over the speaker, or worse.
  * A 1k resistor in series with the module's RX terminal will alleviate this.
+ * 
+ * Files on the SD card are numbered according to their order in the directory on the 
+ * card (as listed by the DIR command in Windows).  This may not match the order of the files 
+ * as displayed by Windows File Manager, which sorts the file names.  It is suggested that
+ * files be copied into an empty SDcard in the desired order, one at a time.
+ * 
+ * The driver now polls the device for its current status every second.  Should the device
+ * fail to respond it will be marked off-line and its busy indicator cleared, to avoid
+ * lock-ups in automation scripts that are executing for a WAITFOR().
  */
 
 #ifndef IO_DFPlayer_h
@@ -63,12 +77,25 @@
 
 class DFPlayer : public IODevice {
 private: 
+  const uint8_t MAXVOLUME=30;
   HardwareSerial *_serial;
   bool _playing = false;
   uint8_t _inputIndex = 0;
-  unsigned long _commandSendTime; // Allows timeout processing
-
+  unsigned long _commandSendTime; // Time (us) that last transmit took place.
+  unsigned long _timeoutTime;
+  uint8_t _recvCMD;  // Last received command code byte
+  bool _awaitingResponse = false;
+  uint8_t _requestedVolumeLevel = MAXVOLUME;
+  uint8_t _currentVolume = MAXVOLUME;
+  int _requestedSong = -1;  // -1=none, 0=stop, >0=file number
+  
 public:
+ 
+  static void create(VPIN firstVpin, int nPins, HardwareSerial &serial) {
+    if (checkNoOverlap(firstVpin,nPins)) new DFPlayer(firstVpin, nPins, serial);
+  }
+
+protected:
   // Constructor
   DFPlayer(VPIN firstVpin, int nPins, HardwareSerial &serial) :
     IODevice(firstVpin, nPins),
@@ -77,77 +104,159 @@ public:
     addDevice(this);
   }
 
-  static void create(VPIN firstVpin, int nPins, HardwareSerial &serial) {
-    new DFPlayer(firstVpin, nPins, serial);
-  }
-
-protected:
   void _begin() override {
-    _serial->begin(9600);
+    _serial->begin(9600, SERIAL_8N1); // 9600baud, no parity, 1 stop bit
+    // Flush any data in input queue
+    while (_serial->available()) _serial->read();
     _deviceState = DEVSTATE_INITIALISING;
 
     // Send a query to the device to see if it responds
     sendPacket(0x42); 
-    _commandSendTime = micros();
+    _timeoutTime = micros() + 5000000UL;  // 5 second timeout
+    _awaitingResponse = true;
   }
 
   void _loop(unsigned long currentMicros) override {
-    // Check for incoming data on _serial, and update busy flag accordingly.
-    // Expected message is in the form "7F FF 06 3D xx xx xx xx xx EF"
-    while (_serial->available()) {
-      int c = _serial->read();
-      if (c == 0x7E) 
-        _inputIndex = 1;
-      else if ((c==0xFF && _inputIndex==1)
-            || (c==0x3D && _inputIndex==3) 
-            || (_inputIndex >=4 && _inputIndex <= 8))
-        _inputIndex++;
-      else if (c==0x06 && _inputIndex==2) { 
-        // Valid message prefix, so consider the device online
-        if (_deviceState==DEVSTATE_INITIALISING) {
-          _deviceState = DEVSTATE_NORMAL;
-          #ifdef DIAG_IO
-          _display();
-          #endif
-        }
-        _inputIndex++;
-      } else if (c==0xEF && _inputIndex==9) {
-        // End of play
-        if (_playing) {
-          #ifdef DIAG_IO
-          DIAG(F("DFPlayer: Finished"));
-          #endif
-          _playing = false;
-        }
-        _inputIndex = 0;
-      } else 
-        _inputIndex = 0;  // Unrecognised character sequence, start again!
-    }
-    // Check if the initial prompt to device has timed out.  Allow 1 second
-    if (_deviceState == DEVSTATE_INITIALISING && currentMicros - _commandSendTime > 1000000UL) {
+
+    // Read responses from device
+    processIncoming();
+
+    // Check if a command sent to device has timed out.  Allow 0.5 second for response
+    if (_awaitingResponse && (int32_t)(currentMicros - _timeoutTime) > 0) {
       DIAG(F("DFPlayer device not responding on serial port"));
       _deviceState = DEVSTATE_FAILED;
+      _awaitingResponse = false;
+      _playing = false;
     }
+
+    // Send any commands that need to go.
+    processOutgoing(currentMicros);
+
     delayUntil(currentMicros + 10000); // Only enter every 10ms
   }
 
+  // Check for incoming data on _serial, and update busy flag and other state accordingly
+  void processIncoming() {
+    // Expected message is in the form "7E FF 06 3D xx xx xx xx xx EF"
+    bool ok = false;
+    while (_serial->available()) {
+      int c = _serial->read();
+      switch (_inputIndex) {
+        case 0:
+          if (c == 0x7E) ok = true;
+          break;
+        case 1:
+          if (c == 0xFF) ok = true;
+          break;
+        case 2:
+          if (c== 0x06) ok = true;
+          break;
+        case 3:
+          _recvCMD = c; // CMD byte
+          ok = true;
+          break;
+        case 6:
+          switch (_recvCMD) {
+            case 0x42:
+              // Response to status query
+              _playing = (c != 0);
+              // Mark the device online and cancel timeout
+              if (_deviceState==DEVSTATE_INITIALISING) {
+                _deviceState = DEVSTATE_NORMAL;
+                #ifdef DIAG_IO
+                _display();
+                #endif
+              }
+              _awaitingResponse = false;
+              break;
+            case 0x3d:
+              // End of play
+              if (_playing) {
+                #ifdef DIAG_IO
+                DIAG(F("DFPlayer: Finished"));
+                #endif
+                _playing = false;
+              }
+              break;
+            case 0x40:
+              // Error code
+              DIAG(F("DFPlayer: Error %d returned from device"), c);
+              _playing = false;
+              break;
+          }
+          ok = true;
+          break;
+        case 4: case 5: case 7: case 8: 
+          ok = true;  // Skip over these bytes in message.
+          break;
+        case 9:
+          if (c==0xef) {
+            // Message finished
+          }
+          break;
+        default:
+          break;
+      }
+      if (ok)
+        _inputIndex++;  // character as expected, so increment index
+      else
+        _inputIndex = 0;  // otherwise reset.
+    }
+  }
+
+  // Send any commands that need to be sent
+  void processOutgoing(unsigned long currentMicros) {
+
+    // When two commands are sent in quick succession, the device will often fail to 
+    // execute one.  Testing has indicated that a delay of 100ms or more is required
+    // between successive commands to get reliable operation.
+    // If 100ms has elapsed since the last thing sent, then check if there's some output to do.
+    if (((int32_t)currentMicros - _commandSendTime) > 100000) {
+      if (_currentVolume > _requestedVolumeLevel) {
+        // Change volume before changing song if volume is reducing.
+        _currentVolume = _requestedVolumeLevel;
+        sendPacket(0x06, _currentVolume);
+      } else if (_requestedSong > 0) {
+        // Change song
+        sendPacket(0x03, _requestedSong);
+        _requestedSong = -1;
+      } else if (_requestedSong == 0) {
+        sendPacket(0x16);  // Stop playing
+        _requestedSong = -1;
+      } else if (_currentVolume < _requestedVolumeLevel) {
+        // Change volume after changing song if volume is increasing.
+        _currentVolume = _requestedVolumeLevel;
+        sendPacket(0x06, _currentVolume);
+      } else if ((int32_t)currentMicros - _commandSendTime > 1000000) {
+        // Poll device every second that other commands aren't being sent,
+        // to check if it's still connected and responding.
+        sendPacket(0x42); 
+        if (!_awaitingResponse) {
+          _timeoutTime = currentMicros + 5000000UL;  // Timeout if no response within 5 seconds
+          _awaitingResponse = true;
+        }
+      }
+    }
+  }
+
   // Write with value 1 starts playing a song.  The relative pin number is the file number.
   // Write with value 0 stops playing.
   void _write(VPIN vpin, int value) override {
+    if (_deviceState == DEVSTATE_FAILED) return;
     int pin = vpin - _firstVpin;
     if (value) {
       // Value 1, start playing
       #ifdef DIAG_IO
       DIAG(F("DFPlayer: Play %d"), pin+1);
       #endif
-      sendPacket(0x03, pin+1);
+      _requestedSong = pin+1;
       _playing = true;
     } else {
       // Value 0, stop playing
       #ifdef DIAG_IO
       DIAG(F("DFPlayer: Stop"));
       #endif
-      sendPacket(0x16);
+      _requestedSong = 0;  // No song
       _playing = false;
     }
   }
@@ -156,51 +265,43 @@ protected:
   // Volume may be specified as second parameter to writeAnalogue.
   // If value is zero, the player stops playing.  
   // WriteAnalogue on second pin sets the output volume.
+  //
   void _writeAnalogue(VPIN vpin, int value, uint8_t volume=0, uint16_t=0) override { 
+    if (_deviceState == DEVSTATE_FAILED) return;
     uint8_t pin = vpin - _firstVpin;
  
+    #ifdef DIAG_IO
+    DIAG(F("DFPlayer: VPIN:%u FileNo:%d Volume:%d"), vpin, value, volume);
+    #endif
+
     // Validate parameter.
-    volume = min(30,volume);
+    if (volume > MAXVOLUME) volume = MAXVOLUME;
 
     if (pin == 0) {
       // Play track 
       if (value > 0) {
-        #ifdef DIAG_IO
-        DIAG(F("DFPlayer: Play %d"), value);
-        #endif
-        sendPacket(0x03, value); // Play track
+        if (volume > 0)
+          _requestedVolumeLevel = volume;
+        _requestedSong = value;
         _playing = true;
-        if (volume > 0) {
-          #ifdef DIAG_IO
-          DIAG(F("DFPlayer: Volume %d"), volume);
-          #endif
-          sendPacket(0x06, volume);  // Set volume
-        }
       } else {
-        #ifdef DIAG_IO
-        DIAG(F("DFPlayer: Stop"));
-        #endif
-        sendPacket(0x16); // Stop play
+        _requestedSong = 0; // stop playing
         _playing = false;
       }
     } else if (pin == 1) {
       // Set volume (0-30)
-      if (value > 30) value = 30;
-      else if (value < 0) value = 0;
-      #ifdef DIAG_IO
-      DIAG(F("DFPlayer: Volume %d"), value);
-      #endif
-      sendPacket(0x06, value);      
+      _requestedVolumeLevel = value;  
     }
   }
 
   // A read on any pin indicates whether the player is still playing.
   int _read(VPIN) override {
+    if (_deviceState == DEVSTATE_FAILED) return false;
     return _playing;
   }
 
   void _display() override {
-    DIAG(F("DFPlayer Configured on Vpins:%d-%d %S"), _firstVpin, _firstVpin+_nPins-1,
+    DIAG(F("DFPlayer Configured on Vpins:%u-%u %S"), _firstVpin, _firstVpin+_nPins-1,
       (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
   }
   
@@ -230,7 +331,10 @@ private:
 
     setChecksum(out);
 
+    // Output the command
     _serial->write(out, sizeof(out));
+
+    _commandSendTime = micros();
   }
 
   uint16_t calcChecksum(uint8_t* packet)

IO_EXFastclock.h

@@ -0,0 +1,126 @@
+/*
+ *  © 2022, Colin Murdoch. All rights reserved.
+ *
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+/*
+* The IO_EXFastclock device driver is used to interface the standalone fast clock and receive time data.
+*
+* The EX-fastClock code lives in a separate repo (https://github.com/DCC-EX/EX-Fastclock) and contains the clock logic.
+*
+*
+*/
+
+#ifndef IO_EXFastclock_h
+#define IO_EXFastclock_h
+
+
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+#include "EXRAIL2.h"
+#include "CommandDistributor.h"
+
+bool FAST_CLOCK_EXISTS = true;
+
+class EXFastClock : public IODevice {
+public:
+  // Constructor
+    EXFastClock(I2CAddress i2cAddress){
+    _I2CAddress = i2cAddress;
+    addDevice(this);
+  }
+
+static void create(I2CAddress i2cAddress) {
+
+  DIAG(F("Checking for Clock"));
+  // Start by assuming we will find the clock
+  // Check if specified I2C address is responding (blocking operation)
+  // Returns I2C_STATUS_OK (0) if OK, or error code.
+  I2CManager.begin();
+  uint8_t _checkforclock = I2CManager.checkAddress(i2cAddress);
+  DIAG(F("Clock check result - %d"), _checkforclock);
+  // XXXX change thistosave2 bytes
+  if (_checkforclock == 0) {
+      FAST_CLOCK_EXISTS = true;
+      //DIAG(F("I2C Fast Clock found at %s"), i2cAddress.toString());
+      new EXFastClock(i2cAddress); 
+    }
+    else {
+      FAST_CLOCK_EXISTS = false;
+      //DIAG(F("No Fast Clock found"));
+      LCD(6,F("CLOCK NOT FOUND"));
+    }
+    
+  }
+    
+private:
+  
+
+// Initialisation of Fastclock
+void _begin() override {
+  
+  if (FAST_CLOCK_EXISTS == true) {
+    I2CManager.begin();
+    if (I2CManager.exists(_I2CAddress)) {
+      _deviceState = DEVSTATE_NORMAL;
+      #ifdef DIAG_IO
+        _display();
+      #endif
+    } else {
+    _deviceState = DEVSTATE_FAILED;
+    //LCD(6,F("CLOCK NOT FOUND")); 
+    DIAG(F("Fast Clock Not Found at address %s"), _I2CAddress.toString());
+    }
+  }
+}
+
+// Processing loop to obtain clock time
+
+void _loop(unsigned long currentMicros) override{ 
+  
+  if (FAST_CLOCK_EXISTS==true) {
+      uint8_t readBuffer[3];
+      byte a,b;
+      #ifdef EXRAIL_ACTIVE
+        I2CManager.read(_I2CAddress, readBuffer, 3);
+        // XXXX change this to save a few bytes
+        a = readBuffer[0];
+        b = readBuffer[1];
+        //_clocktime = (a << 8) + b;
+        //_clockrate = readBuffer[2];
+
+        CommandDistributor::setClockTime(((a << 8) + b), readBuffer[2], 1);
+        //setClockTime(int16_t clocktime, int8_t clockrate, byte opt);
+        
+        // As the minimum clock increment is 2 seconds delay a bit - say 1 sec.
+        // Clock interval is 60/ clockspeed i.e 60/b seconds
+        delayUntil(currentMicros + ((60/b) * 1000000));  
+     
+      #endif
+    
+  }
+}
+
+  // Display EX-FastClock device driver info.
+  void _display() override {
+    DIAG(F("FastCLock on I2C:%s - %S"), _I2CAddress.toString(),  (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
+  }
+  
+};
+
+#endif

IO_EXIOExpander.h

@@ -0,0 +1,418 @@
+/*
+ *  © 2022, Peter Cole. All rights reserved.
+ *  © 2024, Harald Barth. All rights reserved.
+ *
+ *  This file is part of EX-CommandStation
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+/*
+* The IO_EXIOExpander.h device driver integrates with one or more EX-IOExpander devices.
+* This device driver will configure the device on startup, along with
+* interacting with the device for all input/output duties.
+*
+* To create EX-IOExpander devices, these are defined in myAutomation.h:
+* (Note the device driver is included by default)
+*
+* HAL(EXIOExpander,800,18,0x65)
+* 
+* All pins on an EX-IOExpander device are allocated according to the pin map for the specific
+* device in use. There is no way for the device driver to sanity check pins are used for the
+* correct purpose, however the EX-IOExpander device's pin map will prevent pins being used
+* incorrectly (eg. A6/7 on Nano cannot be used for digital input/output).
+*
+* The total number of pins cannot exceed 256 because of the communications packet format.
+* The number of analogue inputs cannot exceed 16 because of a limit on the maximum
+* I2C packet size of 32 bytes (in the Wire library).
+*/
+
+#ifndef IO_EX_IOEXPANDER_H
+#define IO_EX_IOEXPANDER_H
+
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+#include "FSH.h"
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////
+/*
+ * IODevice subclass for EX-IOExpander.
+ */
+class EXIOExpander : public IODevice {
+public:
+
+  enum ProfileType : uint8_t {
+    Instant = 0,  // Moves immediately between positions (if duration not specified)
+    UseDuration = 0, // Use specified duration
+    Fast = 1,     // Takes around 500ms end-to-end
+    Medium = 2,   // 1 second end-to-end
+    Slow = 3,     // 2 seconds end-to-end
+    Bounce = 4,   // For semaphores/turnouts with a bit of bounce!!
+    NoPowerOff = 0x80, // Flag to be ORed in to suppress power off after move.
+  };
+
+  static void create(VPIN vpin, int nPins, I2CAddress i2cAddress) {
+    if (checkNoOverlap(vpin, nPins, i2cAddress)) new EXIOExpander(vpin, nPins, i2cAddress);
+  }
+
+private:
+  // Constructor
+  EXIOExpander(VPIN firstVpin, int nPins, I2CAddress i2cAddress) {
+    _firstVpin = firstVpin;
+    // Number of pins cannot exceed 256 (1 byte) because of I2C message structure.
+    if (nPins > 256) nPins = 256;
+    _nPins = nPins;
+    _I2CAddress = i2cAddress;
+    addDevice(this);
+  }
+
+  void _begin() {
+    uint8_t status;
+    // Initialise EX-IOExander device
+    I2CManager.begin();
+    if (I2CManager.exists(_I2CAddress)) {
+      // Send config, if EXIOPINS returned, we're good, setup pin buffers, otherwise go offline
+      // NB The I2C calls here are done as blocking calls, as they're not time-critical
+      // during initialisation and the reads require waiting for a response anyway.
+      // Hence we can allocate I/O buffers from the stack.
+      uint8_t receiveBuffer[3];
+      uint8_t commandBuffer[4] = {EXIOINIT, (uint8_t)_nPins, (uint8_t)(_firstVpin & 0xFF), (uint8_t)(_firstVpin >> 8)};
+      status = I2CManager.read(_I2CAddress, receiveBuffer, sizeof(receiveBuffer), commandBuffer, sizeof(commandBuffer));
+      if (status == I2C_STATUS_OK) {
+        if (receiveBuffer[0] == EXIOPINS) {
+          _numDigitalPins = receiveBuffer[1];
+          _numAnaloguePins = receiveBuffer[2];
+
+          // See if we already have suitable buffers assigned
+          if (_numDigitalPins>0) {
+            size_t digitalBytesNeeded = (_numDigitalPins + 7) / 8;
+            if (_digitalPinBytes < digitalBytesNeeded) {
+              // Not enough space, free any existing buffer and allocate a new one
+              if (_digitalPinBytes > 0) free(_digitalInputStates);
+              if ((_digitalInputStates = (byte*) calloc(digitalBytesNeeded, 1)) != NULL) {
+                _digitalPinBytes = digitalBytesNeeded;
+              } else {
+                DIAG(F("EX-IOExpander I2C:%s ERROR alloc %d bytes"), _I2CAddress.toString(), digitalBytesNeeded);
+                _deviceState = DEVSTATE_FAILED;
+                _digitalPinBytes = 0;
+                return;
+              }
+            }
+          }
+          
+          if (_numAnaloguePins>0) {
+            size_t analogueBytesNeeded = _numAnaloguePins * 2;
+            if (_analoguePinBytes < analogueBytesNeeded) {
+              // Free any existing buffers and allocate new ones.
+              if (_analoguePinBytes > 0) {
+                free(_analogueInputBuffer);
+                free(_analogueInputStates);
+                free(_analoguePinMap);
+              }
+              _analogueInputStates = (uint8_t*) calloc(analogueBytesNeeded, 1);
+              _analogueInputBuffer = (uint8_t*) calloc(analogueBytesNeeded, 1);
+              _analoguePinMap = (uint8_t*) calloc(_numAnaloguePins, 1);
+	      if (_analogueInputStates  != NULL &&
+		  _analogueInputBuffer != NULL &&
+		  _analoguePinMap != NULL) {
+		_analoguePinBytes = analogueBytesNeeded;
+	      } else {
+		DIAG(F("EX-IOExpander I2C:%s ERROR alloc analog pin bytes"), _I2CAddress.toString());
+		_deviceState = DEVSTATE_FAILED;
+		_analoguePinBytes = 0;
+		return;
+	      }
+            }
+          }
+        } else {
+          DIAG(F("EX-IOExpander I2C:%s ERROR configuring device"), _I2CAddress.toString());
+          _deviceState = DEVSTATE_FAILED;
+          return;
+        }
+      } 
+      // We now need to retrieve the analogue pin map if there are analogue pins
+      if (status == I2C_STATUS_OK && _numAnaloguePins>0) {
+        commandBuffer[0] = EXIOINITA;
+        status = I2CManager.read(_I2CAddress, _analoguePinMap, _numAnaloguePins, commandBuffer, 1);
+      }
+      if (status == I2C_STATUS_OK) {
+        // Attempt to get version, if we don't get it, we don't care, don't go offline
+        uint8_t versionBuffer[3];
+        commandBuffer[0] = EXIOVER;
+        if (I2CManager.read(_I2CAddress, versionBuffer, sizeof(versionBuffer), commandBuffer, 1) == I2C_STATUS_OK) {
+          _majorVer = versionBuffer[0];
+          _minorVer = versionBuffer[1];
+          _patchVer = versionBuffer[2];
+        }
+        DIAG(F("EX-IOExpander device found, I2C:%s, Version v%d.%d.%d"),
+            _I2CAddress.toString(), _majorVer, _minorVer, _patchVer);
+
+#ifdef DIAG_IO
+        _display();
+#endif
+      }
+      if (status != I2C_STATUS_OK)
+        reportError(status);
+
+    } else {
+      DIAG(F("EX-IOExpander I2C:%s device not found"), _I2CAddress.toString());
+      _deviceState = DEVSTATE_FAILED;
+    }
+  }
+
+  // Digital input pin configuration, used to enable on EX-IOExpander device and set pullups if requested.
+  // Configuration isn't done frequently so we can use blocking I2C calls here, and so buffers can
+  // be allocated from the stack to reduce RAM allocation.
+  bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) override {
+    if (paramCount != 1) return false;
+    int pin = vpin - _firstVpin;
+    if (configType == CONFIGURE_INPUT) {
+      uint8_t pullup = params[0];
+      uint8_t outBuffer[] = {EXIODPUP, (uint8_t)pin, pullup};
+      uint8_t responseBuffer[1];
+      uint8_t status = I2CManager.read(_I2CAddress, responseBuffer, sizeof(responseBuffer),
+                                outBuffer, sizeof(outBuffer));
+      if (status == I2C_STATUS_OK) {
+        if (responseBuffer[0] == EXIORDY) {
+          return true;
+        } else {
+          DIAG(F("EXIOVpin %u cannot be used as a digital input pin"), (int)vpin);
+        }
+      } else
+        reportError(status);
+    } else if (configType == CONFIGURE_ANALOGINPUT) {
+      // TODO:  Consider moving code from _configureAnalogIn() to here and remove _configureAnalogIn
+      // from IODevice class definition.  Not urgent, but each virtual function defined
+      // means increasing the RAM requirement of every HAL device driver, whether it's relevant
+      // to the driver or not.
+      return false;
+    }
+    return false;
+  }
+
+  // Analogue input pin configuration, used to enable an EX-IOExpander device.
+  // Use I2C blocking calls and allocate buffers from stack to save RAM.
+  int _configureAnalogIn(VPIN vpin) override {
+    int pin = vpin - _firstVpin;
+    uint8_t commandBuffer[] = {EXIOENAN, (uint8_t)pin};
+    uint8_t responseBuffer[1];
+    uint8_t status = I2CManager.read(_I2CAddress, responseBuffer, sizeof(responseBuffer),
+                                  commandBuffer, sizeof(commandBuffer));
+    if (status == I2C_STATUS_OK) {
+      if (responseBuffer[0] == EXIORDY) {
+        return true;
+      } else {
+        DIAG(F("EX-IOExpander: Vpin %u cannot be used as an analogue input pin"), (int)vpin);
+      }
+    } else
+      reportError(status);
+
+    return false;
+  }
+
+  // Main loop, collect both digital and analogue pin states continuously (faster sensor/input reads)
+  void _loop(unsigned long currentMicros) override {
+    if (_deviceState == DEVSTATE_FAILED) return;    // If device failed, return
+
+    // Request block is used for analogue and digital reads from the IOExpander, which are performed
+    // on a cyclic basis.  Writes are performed synchronously as and when requested.
+
+    if (_readState != RDS_IDLE) {
+      if (_i2crb.isBusy()) return;                // If I2C operation still in progress, return
+
+      uint8_t status = _i2crb.status;
+      if (status == I2C_STATUS_OK) {             // If device request ok, read input data
+
+        // First check if we need to process received data
+        if (_readState == RDS_ANALOGUE) {
+          // Read of analogue values was in progress, so process received values
+          // Here we need to copy the values from input buffer to the analogue value array.  We need to 
+          // do this to avoid tearing of the values (i.e. one byte of a two-byte value being changed
+          // while the value is being read).
+          memcpy(_analogueInputStates, _analogueInputBuffer, _analoguePinBytes); // Copy I2C input buffer to states
+
+        } else if (_readState == RDS_DIGITAL) {
+          // Read of digital states was in progress, so process received values 
+          // The received digital states are placed directly into the digital buffer on receipt, 
+          // so don't need any further processing at this point (unless we want to check for
+          // changes and notify them to subscribers, to avoid the need for polling - see IO_GPIOBase.h).
+        }
+      } else
+        reportError(status, false);   // report eror but don't go offline.
+
+      _readState = RDS_IDLE;
+    }
+
+    // If we're not doing anything now, check to see if a new input transfer is due.
+    if (_readState == RDS_IDLE) {
+      if (_numDigitalPins>0 && currentMicros - _lastDigitalRead > _digitalRefresh) { // Delay for digital read refresh
+        // Issue new read request for digital states.  As the request is non-blocking, the buffer has to
+        // be allocated from heap (object state).
+        _readCommandBuffer[0] = EXIORDD;
+        I2CManager.read(_I2CAddress, _digitalInputStates, (_numDigitalPins+7)/8, _readCommandBuffer, 1, &_i2crb);
+                                                                // non-blocking read
+        _lastDigitalRead = currentMicros;
+        _readState = RDS_DIGITAL;
+      } else if (_numAnaloguePins>0 && currentMicros - _lastAnalogueRead > _analogueRefresh) { // Delay for analogue read refresh
+        // Issue new read for analogue input states
+        _readCommandBuffer[0] = EXIORDAN;
+        I2CManager.read(_I2CAddress, _analogueInputBuffer,
+            _numAnaloguePins * 2, _readCommandBuffer, 1, &_i2crb);
+        _lastAnalogueRead = currentMicros;
+        _readState = RDS_ANALOGUE;
+      }
+    }
+  }
+
+  // Obtain the correct analogue input value, with reference to the analogue
+  // pin map.  
+  // Obtain the correct analogue input value
+  int _readAnalogue(VPIN vpin) override {
+    if (_deviceState == DEVSTATE_FAILED) return 0;
+    int pin = vpin - _firstVpin;
+    for (uint8_t aPin = 0; aPin < _numAnaloguePins; aPin++) {
+      if (_analoguePinMap[aPin] == pin) {
+        uint8_t _pinLSBByte = aPin * 2;
+        uint8_t _pinMSBByte = _pinLSBByte + 1;
+        return (_analogueInputStates[_pinMSBByte] << 8) + _analogueInputStates[_pinLSBByte];
+      }
+    }
+    return -1;  // pin not found in table
+  }
+
+  // Obtain the correct digital input value
+  int _read(VPIN vpin) override {
+    if (_deviceState == DEVSTATE_FAILED) return 0;
+    int pin = vpin - _firstVpin;
+    uint8_t pinByte = pin / 8;
+    bool value = bitRead(_digitalInputStates[pinByte], pin - pinByte * 8);
+    return value;
+  }
+
+  // Write digital value.  We could have an output buffer of states, that is periodically
+  // written to the device if there are any changes; this would reduce the I2C overhead
+  // if lots of output requests are being made.  We could also cache the last value 
+  // sent so that we don't write the same value over and over to the output.  
+  // However, for the time being, we just write the current value (blocking I2C) to the
+  // IOExpander node.  As it is a blocking request, we can use buffers allocated from
+  // the stack to save RAM allocation.
+  void _write(VPIN vpin, int value) override {
+    uint8_t digitalOutBuffer[3];
+    uint8_t responseBuffer[1];
+    if (_deviceState == DEVSTATE_FAILED) return;
+    int pin = vpin - _firstVpin;
+    digitalOutBuffer[0] = EXIOWRD;
+    digitalOutBuffer[1] = pin;
+    digitalOutBuffer[2] = value;
+    uint8_t status = I2CManager.read(_I2CAddress, responseBuffer, 1, digitalOutBuffer, 3);
+    if (status != I2C_STATUS_OK) {
+      reportError(status);
+    } else {
+      if (responseBuffer[0] != EXIORDY) {
+        DIAG(F("Vpin %u cannot be used as a digital output pin"), (int)vpin);
+      }
+    }
+  }
+
+  // Write analogue (integer) value.  Write the parameters (blocking I2C) to the
+  // IOExpander node.  As it is a blocking request, we can use buffers allocated from
+  // the stack to reduce RAM allocation.
+  void _writeAnalogue(VPIN vpin, int value, uint8_t profile, uint16_t duration) override {
+    uint8_t servoBuffer[7];
+    uint8_t responseBuffer[1];
+
+    if (_deviceState == DEVSTATE_FAILED) return;
+    int pin = vpin - _firstVpin;
+#ifdef DIAG_IO
+    DIAG(F("Servo: WriteAnalogue Vpin:%u Value:%d Profile:%d Duration:%d %S"), 
+      vpin, value, profile, duration, _deviceState == DEVSTATE_FAILED?F("DEVSTATE_FAILED"):F(""));
+#endif
+    servoBuffer[0] = EXIOWRAN;
+    servoBuffer[1] = pin;
+    servoBuffer[2] = value & 0xFF;
+    servoBuffer[3] = value >> 8;
+    servoBuffer[4] = profile;
+    servoBuffer[5] = duration & 0xFF;
+    servoBuffer[6] = duration >> 8;
+    uint8_t status = I2CManager.read(_I2CAddress, responseBuffer, 1, servoBuffer, 7);
+    if (status != I2C_STATUS_OK) {
+      DIAG(F("EX-IOExpander I2C:%s Error:%d %S"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status));
+      _deviceState = DEVSTATE_FAILED;
+    } else {
+      if (responseBuffer[0] != EXIORDY) {
+        DIAG(F("Vpin %u cannot be used as a servo/PWM pin"), (int)vpin);
+      }
+    }
+  }
+
+  // Display device information and status.
+  void _display() override {
+    DIAG(F("EX-IOExpander I2C:%s v%d.%d.%d Vpins %u-%u %S"),
+              _I2CAddress.toString(), _majorVer, _minorVer, _patchVer,
+              (int)_firstVpin, (int)_firstVpin+_nPins-1,
+              _deviceState == DEVSTATE_FAILED ? F("OFFLINE") : F(""));
+  }
+
+  // Helper function for error handling
+  void reportError(uint8_t status, bool fail=true) {
+    DIAG(F("EX-IOExpander I2C:%s Error:%d (%S)"), _I2CAddress.toString(), 
+      status, I2CManager.getErrorMessage(status));
+    if (fail)
+    _deviceState = DEVSTATE_FAILED;
+  }
+
+  uint8_t _numDigitalPins = 0;
+  uint8_t _numAnaloguePins = 0;
+
+  uint8_t _majorVer = 0;
+  uint8_t _minorVer = 0;
+  uint8_t _patchVer = 0;
+
+  uint8_t* _digitalInputStates  = NULL;
+  uint8_t* _analogueInputStates = NULL;
+  uint8_t* _analogueInputBuffer = NULL;  // buffer for I2C input transfers
+  uint8_t _readCommandBuffer[1];
+
+  uint8_t _digitalPinBytes = 0;   // Size of allocated memory buffer (may be longer than needed)
+  uint8_t _analoguePinBytes = 0;  // Size of allocated memory buffer (may be longer than needed)
+  uint8_t* _analoguePinMap = NULL;
+  I2CRB _i2crb;
+
+  enum {RDS_IDLE, RDS_DIGITAL, RDS_ANALOGUE};  // Read operation states
+  uint8_t _readState = RDS_IDLE;
+  
+  unsigned long _lastDigitalRead = 0;
+  unsigned long _lastAnalogueRead = 0;
+  const unsigned long _digitalRefresh = 10000UL;    // Delay refreshing digital inputs for 10ms
+  const unsigned long _analogueRefresh = 50000UL;   // Delay refreshing analogue inputs for 50ms
+
+  // EX-IOExpander protocol flags
+  enum {
+    EXIOINIT = 0xE0,    // Flag to initialise setup procedure
+    EXIORDY = 0xE1,     // Flag we have completed setup procedure, also for EX-IO to ACK setup
+    EXIODPUP = 0xE2,    // Flag we're sending digital pin pullup configuration
+    EXIOVER = 0xE3,     // Flag to get version
+    EXIORDAN = 0xE4,    // Flag to read an analogue input
+    EXIOWRD = 0xE5,     // Flag for digital write
+    EXIORDD = 0xE6,     // Flag to read digital input
+    EXIOENAN = 0xE7,    // Flag to enable an analogue pin
+    EXIOINITA = 0xE8,   // Flag we're receiving analogue pin mappings
+    EXIOPINS = 0xE9,    // Flag we're receiving pin counts for buffers
+    EXIOWRAN = 0xEA,   // Flag we're sending an analogue write (PWM)
+    EXIOERR = 0xEF,     // Flag we've received an error
+  };
+};
+
+#endif

IO_EXSensorCAM.h

@@ -0,0 +1,425 @@
+/*  2024/08/14 
+ *  © 2024, Barry Daniel ESP32-CAM revision 
+ *
+ *  This file is part of EX-CommandStation
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+*/
+#define driverVer 305
+// v305 less debug & alpha ordered switch
+// v304 static oldb0;  t(##[,%%]; 
+// v303 zipped with CS 5.2.76 and uploaded to repo (with debug)
+// v302 SEND=StringFormatter::send, remove Sp(), add 'q', memcpy( .8) -> .7); 
+// v301 improved 'f','p'&'q' code and driver version calc. Correct bsNo calc. for 'a'							 
+// v300 stripped & revised without expander functionality. Needs sensorCAM.h v300 AND CamParser.cpp
+// v222 uses '@'for EXIORDD read.  handles <NB $> and <NN $ ##>
+// v216 includes 'j' command and uses CamParser rather than myFilter.h Incompatible with v203 senorCAM
+// v203 added pvtThreshold to 'i' output
+// v201 deleted code for compatibility with CAM pre v171. Needs CAM ver201 with o06 only
+// v200 rewrite reduces need for double reads of ESP32 slave CAM. Deleted ESP32CAP. 
+//  Inompatible with pre-v170 sensorCAM, unless set S06 to 0 and S07 to 1 (o06 & l07 say)
+/*
+ * The IO_EXSensorCAM.h device driver can integrate with the sensorCAM device.
+ * It is modelled on the IO_EXIOExpander.h device driver to include specific needs of the ESP32 sensorCAM 
+ * This device driver will configure the device on startup, along with CamParser.cpp
+ * interacting with the sensorCAM device for all input/output duties.
+ *
+ * #include "CamParser.h"      in DCCEXParser.cpp
+ * #include "IO_EXSensorCAM.h" in IODevice.h
+ * To create EX-SensorCAM devices, define them in myHal.cpp: with
+ * EXSensorCAM::create(baseVpin,num_vpins,i2c_address)  or
+ * alternatively use HAL(EXSensorCAM baseVpin numpins i2c_address) in myAutomation.h
+ * also #define SENSORCAM_VPIN baseVpin in config.h
+ *
+ * void halSetup() {
+ *   // EXSensorCAM::create(vpin, num_vpins, i2c_address);
+ *   EXSensorCAM::create(700, 80, 0x11);
+ * }
+ * 
+ * I2C packet size of 32 bytes (in the Wire library).
+*/
+# define DIGITALREFRESH 20000UL      // min uSec delay between digital reads of digitalInputStates
+#ifndef IO_EX_EXSENSORCAM_H
+#define IO_EX_EXSENSORCAM_H
+#define SEND StringFormatter::send
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+#include "FSH.h"
+#include "CamParser.h"
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////
+/*
+ * IODevice subclass for EX-SensorCAM.
+*/
+class EXSensorCAM : public IODevice {
+  public:
+    static void create(VPIN vpin, int nPins, I2CAddress i2cAddress) {
+      if (checkNoOverlap(vpin, nPins, i2cAddress)) 
+      new EXSensorCAM(vpin, nPins, i2cAddress);
+    }
+  																
+    static VPIN CAMBaseVpin;					   
+
+  private:
+   // Constructor
+    EXSensorCAM(VPIN firstVpin, int nPins, I2CAddress i2cAddress) {
+      _firstVpin = firstVpin;
+     // Number of pins cannot exceed 255 (1 byte) because of I2C message structure.
+      if (nPins > 80) nPins = 80;
+      _nPins = nPins;
+      _I2CAddress = i2cAddress;
+      addDevice(this);
+    }
+//*************************
+void _begin() {
+    uint8_t status;
+    // Initialise EX-SensorCAM device
+    I2CManager.begin();
+    if (!I2CManager.exists(_I2CAddress)) {
+      DIAG(F("EX-SensorCAM I2C:%s device not found"), _I2CAddress.toString());
+      _deviceState = DEVSTATE_FAILED;
+      return;
+    }else {
+      uint8_t commandBuffer[4]={EXIOINIT,(uint8_t)_nPins,(uint8_t)(_firstVpin & 0xFF),(uint8_t)(_firstVpin>>8)};                                                                                 
+      status = I2CManager.read(_I2CAddress,_inputBuf,sizeof(_inputBuf),commandBuffer,sizeof(commandBuffer));
+        //EXIOINIT needed to trigger and send firstVpin to CAM
+
+      if (status == I2C_STATUS_OK) {
+        // Attempt to get version, non-blocking results in poor placement of response.  Can be blocking here! 
+        commandBuffer[0] = '^';    //new version code
+    
+        status = I2CManager.read(_I2CAddress, _inputBuf, sizeof(_inputBuf), commandBuffer, 1); 
+         // for ESP32 CAM, read again for good immediate response version data
+        status = I2CManager.read(_I2CAddress, _inputBuf, sizeof(_inputBuf), commandBuffer, 1);
+        
+        if (status == I2C_STATUS_OK) {
+          _majorVer= _inputBuf[1]/10;	
+          _minorVer= _inputBuf[1]%10;
+          _patchVer= _inputBuf[2];				
+          DIAG(F("EX-SensorCAM device found, I2C:%s, Version v%d.%d.%d"),
+                       _I2CAddress.toString(),_majorVer, _minorVer,_patchVer);
+        }  	
+      }
+      if (status != I2C_STATUS_OK)
+        reportError(status);
+    } 
+}
+//*************************
+// Digital input pin configuration, used to enable on EX-IOExpander device and set pullups if requested.
+// Configuration isn't done frequently so we can use blocking I2C calls here, and so buffers can
+// be allocated from the stack to reduce RAM allocation.
+bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) override { 
+  (void)configType; (void)params; // unused
+  if(_verPrint) DIAG(F("_configure() driver IO_EXSensorCAM v0.%d.%d vpin: %d "), driverVer/100,driverVer%100,vpin);
+  _verPrint=false;           //only give driver versions once
+  if (paramCount != 1) return false;
+  return true; //at least confirm that CAM is (always) configured (no vpin check!)
+}
+//*************************															 
+// Analogue input pin configuration, used to enable an EX-IOExpander device.
+int _configureAnalogIn(VPIN vpin) override { 
+  DIAG(F("_configureAnalogIn() IO_EXSensorCAM vpin %d"),vpin); 
+  return true;     // NOTE: use of EXRAIL IFGTE() etc use "analog" reads.
+}
+//*************************
+// Main loop, collect both digital and "analog" pin states continuously (faster sensor/input reads)
+void _loop(unsigned long currentMicros) override {
+    if (_deviceState == DEVSTATE_FAILED) return;    
+      // Request block is used for "analogue" (cmd. data) and digital reads from the sensorCAM, which 
+      // are performed on a cyclic basis.  Writes are performed synchronously as and when requested.
+    if (_readState != RDS_IDLE) {                  //expecting a return packet
+      if (_i2crb.isBusy()) return;                 // If I2C operation still in progress, return
+      uint8_t status = _i2crb.status;
+      if (status == I2C_STATUS_OK) {               // If device request ok, read input data
+        //apparently the above checks do not guarantee a good packet! error rate about 1 pkt per 1000
+        //there should be a packet in _CAMresponseBuff[32]            
+        if ((_CAMresponseBuff[0] & 0x60) >= 0x60) {   //Buff[0] seems to have ascii cmd header (bit6 high) (o06)    
+            int error = processIncomingPkt( _CAMresponseBuff, _CAMresponseBuff[0]);   // '~' 'i' 'm' 'n' 't' etc
+              if (error>0) DIAG(F("CAM packet header(0x%x) not recognised"),_CAMresponseBuff[0]);                   
+        }else{ // Header not valid - typically replaced by bank 0 data!  To avoid any bad responses set S06 to 0  
+               // Versions of sensorCAM.h after v300 should return header for '@' of '`'(0x60) (not 0xE6)  
+               // followed by digitalInputStates sensor state array
+        }
+      }else   reportError(status, false);   // report i2c eror but don't go offline.
+      _readState = RDS_IDLE;
+    }      
+  
+    // If we're not doing anything now, check to see if a new state table transfer, or for 't' repeat, is due.
+    if (_readState == RDS_IDLE) {    //check if time for digitalRefresh   
+      if ( currentMicros - _lastDigitalRead > _digitalRefresh) { 
+        // Issue new read request for digital states.  
+             
+        _readCommandBuffer[0] = '@';  //start new read of digitalInputStates Table     // non-blocking read 
+        I2CManager.read(_I2CAddress,_CAMresponseBuff, 32,_readCommandBuffer, 1, &_i2crb);     
+        _lastDigitalRead = currentMicros;
+        _readState = RDS_DIGITAL;
+        
+      }else{    //slip in a repeat <NT n> if pending
+        if (currentMicros - _lasttStateRead > _tStateRefresh)  // Delay for "analog" command repetitions
+         if (_savedCmd[2]>1) {   //repeat a 't' command         
+          for (int i=0;i<7;i++)  _readCommandBuffer[i] =_savedCmd[i];
+          int errors = ioESP32(_I2CAddress, _CAMresponseBuff, 32, _readCommandBuffer, 7);    
+          _lasttStateRead = currentMicros;
+          _savedCmd[2] -= 1;     //decrement repeats                  
+          if (errors==0) return;
+          DIAG(F("ioESP32 error %d header 0x%x"),errors,_CAMresponseBuff[0]);  
+          _readState = RDS_TSTATE;  //this should stop further cmd requests until packet read (or timeout)
+        }
+      }   //end repeat 't'
+    }
+  }   
+//*************************
+// Obtain the bank of 8 sensors as an "analog" value
+// can be used to track the position through a sequential sensor bank
+int _readAnalogue(VPIN vpin) override {
+  if (_deviceState == DEVSTATE_FAILED) return 0;        
+  return _digitalInputStates[(vpin - _firstVpin) / 8];
+}
+//*************************
+// Obtain the correct digital sensor input value
+int _read(VPIN vpin) override {
+  if (_deviceState == DEVSTATE_FAILED) return 0;
+  int pin = vpin - _firstVpin;
+  return bitRead(_digitalInputStates[pin / 8], pin % 8);
+}
+//*************************
+// Write digital value.  
+void _write(VPIN vpin, int value) override { 
+  DIAG(F("**_write() vpin %d = %d"),vpin,value);
+  return ;
+}
+//*************************
+// i2cAddr of ESP32 CAM
+// rBuf   buffer for return packet 
+// inbytes number of bytes to request from CAM
+// outBuff holds outbytes to be sent to CAM  
+int ioESP32(uint8_t i2cAddr,uint8_t *rBuf,int inbytes,uint8_t *outBuff,int outbytes) {
+  uint8_t status = _i2crb.status;
+
+ while( _i2crb.status != I2C_STATUS_OK){status = _i2crb.status;}   //wait until bus free
+
+  status = I2CManager.read(i2cAddr, rBuf, inbytes, outBuff, outbytes);
+        
+  if (status != I2C_STATUS_OK){ 
+    DIAG(F("EX-SensorCAM I2C:%s Error:%d %S"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status));
+    reportError(status); return status;
+  }
+  return 0;  // 0 for no error != 0 for error number.
+}
+//*************************
+//function to interpret packet from sensorCAM.ino
+//i2cAddr to identify CAM# (if # >1)
+//rBuf contains packet of up to 32 bytes usually with (ascii) cmd header in rBuf[0]
+//sensorCmd command header byte from CAM (in rBuf[0]?)
+int processIncomingPkt(uint8_t *rBuf,uint8_t sensorCmd) {
+//static uint8_t oldb0;   //for debug only
+  int k; 
+  int b;
+  char str[] = "11111111";
+ // if (sensorCmd <= '~') DIAG(F("processIncomingPkt %c %d %d %d"),rBuf[0],rBuf[1],rBuf[2],rBuf[3]);
+  switch (sensorCmd){
+    case '`':      //response to request for digitalInputStates[] table  '@'=>'`'  
+      memcpy(_digitalInputStates, rBuf+1, digitalBytesNeeded);
+//      if ( _digitalInputStates[0]!=oldb0) { oldb0=_digitalInputStates[0];  //debug
+//        for (k=0;k<5;k++) {Serial.print(" ");Serial.print(_digitalInputStates[k],HEX);}
+//      }
+      break;                                                 
+
+    case EXIORDY:  //some commands give back acknowledgement only
+      break;
+
+    case CAMERR:   //cmd format error code from CAM
+      DIAG(F("CAM cmd error 0xFE 0x%x"),rBuf[1]); 
+      break;
+
+    case '~':      //information from '^' version request <N v[er]>
+      DIAG(F("EX-SensorCAM device found, I2C:%s,CAM Version v%d.%d.%d vpins %u-%u"),
+              _I2CAddress.toString(), rBuf[1]/10, rBuf[1]%10, rBuf[2],(int) _firstVpin, (int) _firstVpin +_nPins-1);
+      DIAG(F("IO_EXSensorCAM driver  v0.%d.%d vpin: %d "), driverVer/100,driverVer%100,_firstVpin);
+      break;
+ 
+    case 'f':
+      DIAG(F("(f %%%%) frame header 'f' for bsNo %d/%d - showing Quarter sample (1 row) only"), rBuf[1]/8,rBuf[1]%8);  
+      SEND(&USB_SERIAL,F("<n  row: %d  Ref bytes: "),rBuf[2]);
+      for(k=3;k<15;k++)
+        SEND(&USB_SERIAL,F("%x%x%s"), rBuf[k]>>4, rBuf[k]&15, k%3==2 ? "  " : " "); 
+      Serial.print(" latest grab: "); 
+      for(k=16;k<28;k++)
+        SEND(&USB_SERIAL,F("%x%x%s"), rBuf[k]>>4, rBuf[k]&15, (k%3==0) ? "  " : " ");
+      Serial.print(" n>\n");
+      break; 
+
+    case 'i':      //information from i%%
+      k=256*rBuf[5]+rBuf[4];
+      DIAG(F("(i%%%%[,$$]) Info: Sensor 0%o(%d) enabled:%d status:%d row=%d x=%d Twin=0%o pvtThreshold=%d A~%d")
+              ,rBuf[1],rBuf[1],rBuf[3],rBuf[2],rBuf[6],k,rBuf[7],rBuf[9],int(rBuf[8])*16);	 
+      break;
+
+    case 'm':
+      DIAG(F("(m$[,##]) Min/max: $ frames min2flip (trip) %d, maxSensors 0%o, minSensors 0%o, nLED %d,"
+              " threshold %d, TWOIMAGE_MAXBS 0%o"),rBuf[1],rBuf[3],rBuf[2],rBuf[4],rBuf[5],rBuf[6]);
+      break;
+
+    case 'n':
+      DIAG(F("(n$[,##]) Nominate: $ nLED %d, ## minSensors 0%o (maxSensors 0%o threshold %d)")
+                                       ,rBuf[4],rBuf[2],rBuf[3],rBuf[5]);                                                               
+      break;
+
+    case 'p':
+      b=rBuf[1]-2;  
+      if(b<4) { Serial.print("<n (p%%) Bank empty  n>\n"); break; }
+      SEND(&USB_SERIAL,F("<n (p%%) Bank: %d "),(0x7F&rBuf[2])/8);
+      for (int j=2; j<b; j+=3)  
+        SEND(&USB_SERIAL,F(" S[%d%d]: r=%d x=%d"),0x7F&rBuf[j]/8,0x7F&rBuf[j]%8,rBuf[j+1],rBuf[j+2]+2*(rBuf[j]&0x80));
+      Serial.print("  n>\n");
+      break;
+
+    case 'q':
+      for (int i =0; i<8; i++) str[i] = ((rBuf[2] << i) & 0x80 ? '1' : '0');
+      DIAG(F("(q $) Query bank %c ENABLED sensors(S%c7-%c0): %s "), rBuf[1], rBuf[1], rBuf[1], str);
+      break;
+
+    case 't':      //threshold etc. from t##           //bad pkt if 't' FF's
+      if(rBuf[1]==0xFF) {Serial.println("<n bad CAM 't' packet: 74 FF  n>");_savedCmd[2] +=1; return 0;}
+      SEND(&USB_SERIAL,F("<n (t[##[,%%%%]]) Threshold:%d sensor S00:-%d"),rBuf[1],min(rBuf[2]&0x7F,99));
+      if(rBuf[2]>127) Serial.print("##* "); 
+      else{ 
+        if(rBuf[2]>rBuf[1]) Serial.print("-?* "); 
+        else Serial.print("--* ");
+      }
+      for(int i=3;i<31;i+=2){
+        uint8_t valu=rBuf[i];        //get bsn
+        if(valu==80) break;          //80 = end flag
+        else{ 
+          SEND(&USB_SERIAL,F("%d%d:"), (valu&0x7F)/8,(valu&0x7F)%8);
+          if(valu>=128) Serial.print("?-"); 
+          else {if(rBuf[i+1]>=128) Serial.print("oo");else Serial.print("--");}
+          valu=rBuf[i+1]; 
+          SEND(&USB_SERIAL,F("%d%s"),min(valu&0x7F,99),(valu<128) ? "--* ":"##* ");
+        }
+      } 
+      Serial.print(" >\n");
+      break;
+
+    default:        //header not a recognised cmd character
+      DIAG(F("CAM packet header not valid (0x%x) (0x%x) (0x%x)"),rBuf[0],rBuf[1],rBuf[2]);
+      return 1;
+  }			 
+  return 0;  
+}
+//*************************											  
+// Write (analogue) 8bit (command) values.  Write the parameters to the sensorCAM
+void _writeAnalogue(VPIN vpin, int param1, uint8_t camop, uint16_t param3) override {
+    uint8_t outputBuffer[7];
+    int errors=0;
+    outputBuffer[0] = camop;  
+    int pin = vpin - _firstVpin;
+
+    if(camop >= 0x80) {   //case "a" (4p) also (3p) e.g. <N 713 210 310> 
+      camop=param1;        //put row (0-236) in expected place 
+      param1=param3;        //put column in expected place
+      outputBuffer[0] = 'A';
+      pin = (pin/8)*10 + pin%8;   //restore bsNo. as integer
+    }   
+    if (_deviceState == DEVSTATE_FAILED) return;
+   
+    outputBuffer[1] = pin;          //vpin => bsn
+    outputBuffer[2] = param1 & 0xFF;
+    outputBuffer[3] = param1 >> 8;
+    outputBuffer[4] = camop;        //command code
+    outputBuffer[5] = param3 & 0xFF;
+    outputBuffer[6] = param3 >> 8;
+
+    int count=param1+1;
+    if(camop=='Q'){
+      if(param3<=10) {count=param3; camop='B';}
+      //if(param1<10) outputBuffer[2] = param1*10;
+    }
+    if(camop=='B'){   //then 'b'(b%) cmd - can totally deal with that here. (but can't do b%,# (brightSF))
+      if(param1>97) return;
+      if(param1>9) param1 = param1/10;  //accept a bsNo
+      for(int bnk=param1;bnk<count;bnk++) {
+        uint8_t b=_digitalInputStates[bnk];
+        char str[] = "11111111";
+        for (int i=0;i<8;i++) if(((b<<i)&0x80) == 0) str[i]='0';
+        DIAG(F("(b $) Bank: %d activated byte: 0x%x%x (sensors S%d7->%d0) %s"), bnk,b>>4,b&15,bnk,bnk,str ); 
+      }
+      return;
+    } 
+    if (outputBuffer[4]=='T') {   //then 't' cmd
+      if(param1<31) {   //repeated calls if param < 31
+          //for (int i=0;i<7;i++) _savedCmd[i]=outputBuffer[i];
+        memcpy( _savedCmd, outputBuffer, 7);
+      }else _savedCmd[2] = 0;   //no repeats if ##>30 
+    }else _savedCmd[2] = 0;       //no repeats unless 't'
+  
+    _lasttStateRead = micros();    //don't repeat until _tStateRefresh mSec
+
+    errors = ioESP32(_I2CAddress, _CAMresponseBuff, 32 , outputBuffer, 7);  //send to esp32-CAM
+    if (errors==0) return;
+    else {    //       if (_CAMresponseBuff[0] != EXIORDY)   //can't be sure what is inBuff[0] !
+      DIAG(F("ioESP32 i2c error %d header 0x%x"),errors,_CAMresponseBuff[0]);  
+    }
+}
+//*************************
+ // Display device information and status.
+  void _display() override {
+    DIAG(F("EX-SensorCAM I2C:%s v%d.%d.%d Vpins %u-%u %S"),
+              _I2CAddress.toString(), _majorVer, _minorVer, _patchVer,
+              (int)_firstVpin, (int)_firstVpin+_nPins-1,
+              _deviceState == DEVSTATE_FAILED ? F("OFFLINE") : F(""));
+  }
+//*************************
+// Helper function for error handling
+void reportError(uint8_t status, bool fail=true) {
+  DIAG(F("EX-SensorCAM I2C:%s Error:%d (%S)"), _I2CAddress.toString(), 
+        status, I2CManager.getErrorMessage(status));
+  if (fail)  _deviceState = DEVSTATE_FAILED;
+}
+//************************* 
+  uint8_t _numDigitalPins = 80;   
+  size_t  digitalBytesNeeded=10;
+  uint8_t _CAMresponseBuff[34];
+  
+  uint8_t _majorVer = 0;
+  uint8_t _minorVer = 0;
+  uint8_t _patchVer = 0;
+
+  uint8_t _digitalInputStates[10];
+  I2CRB _i2crb;
+  uint8_t _inputBuf[12];
+  byte _outputBuffer[8];
+
+  bool    _verPrint=true;
+
+  uint8_t _readCommandBuffer[8];
+  uint8_t _savedCmd[8];           //for repeat 't' command
+  //uint8_t _digitalPinBytes = 10;  // Size of allocated memory buffer (may be longer than needed)
+
+  enum {RDS_IDLE, RDS_DIGITAL, RDS_TSTATE};  // Read operation states
+  uint8_t _readState = RDS_IDLE;
+  //uint8_t cmdBuffer[7]={0,0,0,0,0,0,0};
+  unsigned long _lastDigitalRead = 0;
+  unsigned long _lasttStateRead = 0;
+  unsigned long _digitalRefresh = DIGITALREFRESH;  // Delay refreshing digital inputs for 10ms
+  const unsigned long _tStateRefresh = 120000UL;   // Delay refreshing repeat "tState" inputs
+
+  enum {
+    EXIOINIT = 0xE0,    // Flag to initialise setup procedure
+    EXIORDY = 0xE1,     // Flag we have completed setup procedure, also for EX-IO to ACK setup
+    CAMERR = 0xFE
+  };
+};
+#endif

IO_EXTurntable.cpp

@@ -0,0 +1,147 @@
+/*
+ *  © 2021, Peter Cole. All rights reserved.
+ *
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+/*
+* The IO_EXTurntable device driver is used to control a turntable via an Arduino with a stepper motor over I2C.
+*
+* The EX-Turntable code lives in a separate repo (https://github.com/DCC-EX/EX-Turntable) and contains the stepper motor logic.
+*
+* This device driver sends a step position to EX-Turntable to indicate the step position to move to using either of these commands:
+* <D TT vpin steps activity> in the serial console
+* MOVETT(vpin, steps, activity) in EX-RAIL
+* Refer to the documentation for further information including the valid activities.
+*/
+
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+#include "Turntables.h"
+#include "CommandDistributor.h"
+
+#ifndef IO_NO_HAL
+
+void EXTurntable::create(VPIN firstVpin, int nPins, I2CAddress I2CAddress) {
+  new EXTurntable(firstVpin, nPins, I2CAddress);
+}
+
+// Constructor
+EXTurntable::EXTurntable(VPIN firstVpin, int nPins, I2CAddress I2CAddress) {
+  _firstVpin = firstVpin;
+  _nPins = nPins;
+  _I2CAddress = I2CAddress;
+  _stepperStatus = 0;
+  _previousStatus = 0;
+  addDevice(this);
+}
+
+// Initialisation of EXTurntable
+void EXTurntable::_begin() {
+  I2CManager.begin();
+  if (I2CManager.exists(_I2CAddress)) {
+    DIAG(F("EX-Turntable device found, I2C:%s"), _I2CAddress.toString());
+#ifdef DIAG_IO
+    _display();
+#endif
+  } else {
+    DIAG(F("EX-Turntable I2C:%s device not found"), _I2CAddress.toString());
+    _deviceState = DEVSTATE_FAILED;
+  }
+}
+
+// Processing loop to obtain status of stepper
+// 0 = finished moving and in correct position
+// 1 = still moving
+void EXTurntable::_loop(unsigned long currentMicros) {
+  uint8_t readBuffer[1];
+  I2CManager.read(_I2CAddress, readBuffer, 1);
+  _stepperStatus = readBuffer[0];
+  if (_stepperStatus != _previousStatus && _stepperStatus == 0) { // Broadcast when a rotation finishes
+    if ( _currentActivity < 4) {
+      _broadcastStatus(_firstVpin, _stepperStatus, _currentActivity);
+    }
+    _previousStatus = _stepperStatus;
+  }
+  delayUntil(currentMicros + 100000);  // Wait 100ms before checking again
+}
+
+// Read returns status as obtained in our loop.
+// Return false if our status value is invalid.
+int EXTurntable::_read(VPIN vpin) {
+  (void)vpin; // surpress warning
+  if (_deviceState == DEVSTATE_FAILED) return 0;
+  if (_stepperStatus > 1) {
+    return false;
+  } else {
+    return _stepperStatus;
+  }
+}
+
+// If a status change has occurred for a turntable object, broadcast it
+void EXTurntable::_broadcastStatus (VPIN vpin, uint8_t status, uint8_t activity) {
+  Turntable *tto = Turntable::getByVpin(vpin);
+  if (tto) {
+    if (activity < 4) {
+      tto->setMoving(status);
+      CommandDistributor::broadcastTurntable(tto->getId(), tto->getPosition(), status);
+    }
+  }
+}
+
+// writeAnalogue to send the steps and activity to Turntable-EX.
+// Sends 3 bytes containing the MSB and LSB of the step count, and activity.
+// value contains the steps, bit shifted to MSB + LSB.
+// activity contains the activity flag as per this list:
+// 
+// Turn = 0,             // Rotate turntable, maintain phase
+// Turn_PInvert = 1,     // Rotate turntable, invert phase
+// Home = 2,             // Initiate homing
+// Calibrate = 3,        // Initiate calibration sequence
+// LED_On = 4,           // Turn LED on
+// LED_Slow = 5,         // Set LED to a slow blink
+// LED_Fast = 6,         // Set LED to a fast blink
+// LED_Off = 7,          // Turn LED off
+// Acc_On = 8,           // Turn accessory pin on
+// Acc_Off = 9           // Turn accessory pin off
+void EXTurntable::_writeAnalogue(VPIN vpin, int value, uint8_t activity, uint16_t duration) {
+  if (_deviceState == DEVSTATE_FAILED) return;
+  if (value < 0) return;
+  uint8_t stepsMSB = value >> 8;
+  uint8_t stepsLSB = value & 0xFF;
+#ifdef DIAG_IO
+  DIAG(F("EX-Turntable WriteAnalogue VPIN:%u Value:%d Activity:%d Duration:%d"),
+    vpin, value, activity, duration);
+  DIAG(F("I2CManager write I2C Address:%d stepsMSB:%d stepsLSB:%d activity:%d"),
+    _I2CAddress.toString(), stepsMSB, stepsLSB, activity);
+#else
+  (void)duration;
+#endif
+  if (activity < 4) _stepperStatus = 1;     // Tell the device driver Turntable-EX is busy
+  _previousStatus = _stepperStatus;
+  _currentActivity = activity;
+  _broadcastStatus(vpin, _stepperStatus, activity); // Broadcast when the rotation starts
+  I2CManager.write(_I2CAddress, 3, stepsMSB, stepsLSB, activity);
+}
+
+// Display Turnetable-EX device driver info.
+void EXTurntable::_display() {
+  DIAG(F("EX-Turntable I2C:%s Configured on Vpins:%u-%u %S"), _I2CAddress.toString(), (int)_firstVpin, 
+    (int)_firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
+}
+
+#endif

IO_EncoderThrottle.cpp

@@ -0,0 +1,143 @@
+/*
+ *  © 2024, Chris Harlow. All rights reserved.
+ *
+ *  This file is part of EX-CommandStation
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+/*
+* The IO_EncoderThrottle device driver uses a rotary encoder connected to vpins
+* to drive a loco.
+*  Loco id is selected by writeAnalog.
+*/
+
+#include "IODevice.h"
+#include "DIAG.h"
+#include "DCC.h"
+
+const byte _DIR_CW = 0x10;  // Clockwise step
+const byte _DIR_CCW = 0x20;  // Counter-clockwise step
+
+const byte transition_table[5][4]= {
+    {0,1,3,0},            // 0: 00
+    {1,1,1,2 | _DIR_CW},  // 1: 00->01
+    {2,2,0,2},            // 2: 00->01->11
+    {3,3,3,4 | _DIR_CCW}, // 3: 00->10
+    {4,0,4,4}             // 4: 00->10->11
+};
+
+const byte _STATE_MASK = 0x07;
+const byte _DIR_MASK = 0x30;
+
+
+
+  void EncoderThrottle::create(VPIN firstVpin, int dtPin, int clkPin, int clickPin, byte notch) {
+    if (checkNoOverlap(firstVpin)) new EncoderThrottle(firstVpin, dtPin,clkPin,clickPin,notch);
+  }
+
+
+  // Constructor
+  EncoderThrottle::EncoderThrottle(VPIN firstVpin, int dtPin, int clkPin, int clickPin, byte notch){
+    _firstVpin = firstVpin;
+    _nPins = 1;
+    _I2CAddress = 0;
+    _dtPin=dtPin;
+    _clkPin=clkPin;
+    _clickPin=clickPin;
+    _notch=notch;
+    _locoid=0;
+    _stopState=xrSTOP;
+    _rocoState=0; 
+    _prevpinstate=4; // not 01..11 
+    IODevice::configureInput(dtPin,true);
+    IODevice::configureInput(clkPin,true);
+    IODevice::configureInput(clickPin,true);
+    addDevice(this);
+    _display();
+  }
+
+  
+
+  void EncoderThrottle::_loop(unsigned long currentMicros)  {
+    if (_locoid==0) return;  // not in use
+    
+    // Clicking down on the roco, stops the loco and sets the direction as unknown.
+  if (IODevice::read(_clickPin)) {
+    if (_stopState==xrSTOP) return; // debounced multiple stops
+    DCC::setThrottle(_locoid,1,DCC::getThrottleDirection(_locoid));
+    _stopState=xrSTOP;
+    DIAG(F("DRIVE %d STOP"),_locoid);
+    return; 
+  }
+
+  // read roco pins and detect state change 
+  byte pinstate = (IODevice::read(_dtPin) << 1) | IODevice::read(_clkPin);
+  if (pinstate==_prevpinstate) return;
+  _prevpinstate=pinstate;
+
+  _rocoState = transition_table[_rocoState & _STATE_MASK][pinstate];
+  if ((_rocoState & _DIR_MASK) == 0) return; // no value change 
+
+  int change=(_rocoState & _DIR_CW)?+1:-1;
+  // handle roco change -1 or +1 (clockwise)
+  
+  if (_stopState==xrSTOP) {
+      // first move after button press sets the direction. (clockwise=fwd)
+      _stopState=change>0?xrFWD:xrREV;
+    }
+
+    // when going fwd, clockwise increases speed. 
+    // but when reversing, anticlockwise increases speed.
+    // This is similar to a center-zero pot control but with
+    // the added safety that you cant panic-spin into the other
+    // direction.
+    if (_stopState==xrREV) change=-change; 
+    //  manage limits
+    int oldspeed=DCC::getThrottleSpeed(_locoid);
+    if (oldspeed==1)oldspeed=0; // break out of estop
+    int  newspeed=change>0 ?  (min((oldspeed+_notch),126)) : (max(0,(oldspeed-_notch)));
+    if (newspeed==1) newspeed=0; // normal decelereated stop. 
+    if (oldspeed!=newspeed) {
+        DIAG(F("DRIVE %d notch %S %d %S"),_locoid,
+             change>0?F("UP"):F("DOWN"),_notch,
+             _stopState==xrFWD?F("FWD"):F("REV"));
+        DCC::setThrottle(_locoid,newspeed,_stopState==xrFWD);
+        }
+}
+
+  // Selocoid as analog value to start drive
+  // use <z vpin locoid [notch]>
+  void EncoderThrottle::_writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t param2)  {  
+    (void) param2;
+    _locoid=value;
+    if (param1>0) _notch=param1;
+    _rocoState=0;
+    
+    // If loco is moving, we inherit direction from it.
+    _stopState=xrSTOP;
+    if (_locoid>0) {
+        auto speedbyte=DCC::getThrottleSpeedByte(_locoid);
+        if ((speedbyte & 0x7f) >1) {
+            // loco is moving
+            _stopState= (speedbyte & 0x80)?xrFWD:xrREV;
+        } 
+    }
+    _display();
+  }
+
+  
+  void EncoderThrottle::_display() {
+    DIAG(F("DRIVE vpin %d loco %d notch %d"),_firstVpin,_locoid,_notch);
+  }

IO_EncoderThrottle.h

@@ -0,0 +1,53 @@
+/*
+ *  © 2024, Chris Harlow. All rights reserved.
+ *
+ *  This file is part of EX-CommandStation
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+/*
+* The IO_EncoderThrottle device driver uses a rotary encoder connected to vpins
+* to drive a loco.
+*  Loco id is selected by writeAnalog.
+*/
+
+#ifndef IO_EncoderThrottle_H
+#define IO_EncoderThrottle_H
+#include "IODevice.h"
+
+class EncoderThrottle : public IODevice {
+public:
+  
+  static void create(VPIN firstVpin, int dtPin, int clkPin, int clickPin, byte notch=10);
+ 
+private:
+  int _dtPin,_clkPin,_clickPin, _locoid, _notch,_prevpinstate; 
+  enum {xrSTOP,xrFWD,xrREV} _stopState;
+  byte _rocoState;  
+
+  // Constructor
+  EncoderThrottle(VPIN firstVpin, int dtPin, int clkPin, int clickPin, byte notch);
+  
+  void _loop(unsigned long currentMicros) override ;
+
+  // Selocoid as analog value to start drive
+  // use <z vpin locoid [notch]>
+  void _writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t param2) override;
+  
+  void _display() override ;
+
+ };
+
+#endif

IO_ExampleSerial.cpp

@@ -1,129 +0,0 @@
-/*
- *  © 2021, Neil McKechnie. All rights reserved.
- *  
- *  This file is part of DCC++EX API
- *
- *  This 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.
- *
- *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-#include <Arduino.h>
-#include "IO_ExampleSerial.h"
-#include "FSH.h"
-
-// Constructor
-IO_ExampleSerial::IO_ExampleSerial(VPIN firstVpin, int nPins, HardwareSerial *serial, unsigned long baud) {
-  _firstVpin = firstVpin;
-  _nPins = nPins;
-  _pinValues = (uint16_t *)calloc(_nPins, sizeof(uint16_t));
-  _baud = baud;
-  
-  // Save reference to serial port driver
-  _serial = serial;
-
-  addDevice(this);
-}
-
-// Static create method for one module.
-void IO_ExampleSerial::create(VPIN firstVpin, int nPins, HardwareSerial *serial, unsigned long baud) {
-  new IO_ExampleSerial(firstVpin, nPins, serial, baud);
-}
-
-// Device-specific initialisation
-void IO_ExampleSerial::_begin() {
-  _serial->begin(_baud);
-#if defined(DIAG_IO)
-  _display();
-#endif
-
-  // Send a few # characters to the output
-  for (uint8_t i=0; i<3; i++)
-    _serial->write('#');
-}
-
-// Device-specific write function.  Write a string in the form "#Wm,n#"
-//  where m is the vpin number, and n is the value.
-void IO_ExampleSerial::_write(VPIN vpin, int value) {
-  int pin = vpin -_firstVpin;
-  #ifdef DIAG_IO
-  DIAG(F("IO_ExampleSerial::_write Pin:%d Value:%d"), (int)vpin, value);
-  #endif
-  // Send a command string over the serial line
-  _serial->print('#');
-  _serial->print('W');
-  _serial->print(pin);
-  _serial->print(',');
-  _serial->print(value);
-  _serial->println('#');
-  DIAG(F("ExampleSerial Sent command, p1=%d, p2=%d"), vpin, value);
- }
-
-// Device-specific read function.
-int IO_ExampleSerial::_read(VPIN vpin) {
-
-  // Return a value for the specified vpin.
-  int result = _pinValues[vpin-_firstVpin];
-
-  return result;
-}
-
-// Loop function to do background scanning of the input port.  State 
-//  machine parses the incoming command as it is received.  Command
-//  is in the form "#Nm,n#" where m is the index and n is the value.
-void IO_ExampleSerial::_loop(unsigned long currentMicros) {
-  (void)currentMicros;  // Suppress compiler warnings
-  if (_serial->available()) {
-    // Input data available to read.  Read a character.
-    char c = _serial->read();
-    switch (_inputState) {
-      case 0: // Waiting for start of command
-        if (c == '#')  // Start of command received.
-          _inputState = 1;
-        break;
-      case 1: // Expecting command character
-        if (c == 'N') { // 'Notify' character received
-          _inputState = 2;
-          _inputValue = _inputIndex = 0;
-        } else
-          _inputState = 0; // Unexpected char, reset
-        break;
-      case 2: // reading first parameter (index)
-        if (isdigit(c))
-          _inputIndex = _inputIndex * 10 + (c-'0');
-        else if (c==',') 
-          _inputState = 3;
-        else
-          _inputState = 0; // Unexpected char, reset
-        break;
-      case 3: // reading reading second parameter (value)
-        if (isdigit(c)) 
-          _inputValue = _inputValue * 10 - (c-'0');
-        else if (c=='#') { // End of command
-          // Complete command received, do something with it.
-          DIAG(F("ExampleSerial Received command, p1=%d, p2=%d"), _inputIndex, _inputValue);
-          if (_inputIndex < _nPins) { // Store value
-            _pinValues[_inputIndex] = _inputValue;
-          }
-          _inputState = 0; // Done, start again.
-        } else
-          _inputState = 0; // Unexpected char, reset
-        break;
-    }
-  }
-}
-
-void IO_ExampleSerial::_display() {
-  DIAG(F("IO_ExampleSerial Configured on VPins:%d-%d"), (int)_firstVpin, 
-    (int)_firstVpin+_nPins-1);
-}
-

IO_ExampleSerial.h

@@ -35,24 +35,131 @@
 #include "IODevice.h"
 
 class IO_ExampleSerial : public IODevice {
-public:
-  IO_ExampleSerial(VPIN firstVpin, int nPins, HardwareSerial *serial, unsigned long baud);
-  static void create(VPIN firstVpin, int nPins, HardwareSerial *serial, unsigned long baud);  
-
-protected:
-  void _begin() override;
-  void _loop(unsigned long currentMicros) override;
-  void _write(VPIN vpin, int value) override;
-  int _read(VPIN vpin) override;
-  void _display() override;
-
 private:
+  // Here we define the device-specific variables.  
   HardwareSerial *_serial;
   uint8_t _inputState = 0;
   int _inputIndex = 0;
   int _inputValue = 0;
   uint16_t *_pinValues; // Pointer to block of memory containing pin values
   unsigned long _baud;
+
+public:
+  //  Static function to handle "IO_ExampleSerial::create(...)" calls.
+  static void create(VPIN firstVpin, int nPins, HardwareSerial *serial, unsigned long baud) {
+    if (checkNoOverlap(firstVpin,nPins)) new IO_ExampleSerial(firstVpin, nPins, serial, baud);
+  } 
+
+protected:
+  // Constructor.  This should initialise variables etc. but not call other objects yet
+  // (e.g. Serial, I2CManager, and other parts of the CS functionality).
+  // defer those until the _begin() function.  The 'addDevice' call is required unless
+  // the device is not to be added (e.g. because of incorrect parameters).
+  IO_ExampleSerial(VPIN firstVpin, int nPins, HardwareSerial *serial, unsigned long baud) {
+    _firstVpin = firstVpin;
+    _nPins = nPins;
+    _pinValues = (uint16_t *)calloc(_nPins, sizeof(uint16_t));
+    _baud = baud;
+    
+    // Save reference to serial port driver
+    _serial = serial;
+
+    addDevice(this);
+  }
+
+  // Device-specific initialisation
+  void _begin() override {
+    _serial->begin(_baud);
+#if defined(DIAG_IO)
+    _display();
+#endif
+
+    // Send a few # characters to the output
+    for (uint8_t i=0; i<3; i++)
+      _serial->write('#');
+  }
+  
+  // Device-specific write function.  Write a string in the form "#Wm,n#"
+  //  where m is the vpin number, and n is the value.
+  void _write(VPIN vpin, int value) {
+    int pin = vpin -_firstVpin;
+    #ifdef DIAG_IO
+    DIAG(F("IO_ExampleSerial::_write VPIN:%u Value:%d"), (int)vpin, value);
+    #endif
+    // Send a command string over the serial line
+    _serial->print('#');
+    _serial->print('W');
+    _serial->print(pin);
+    _serial->print(',');
+    _serial->print(value);
+    _serial->println('#');
+    DIAG(F("ExampleSerial Sent command, p1=%d, p2=%d"), vpin, value);
+  }
+
+  // Device-specific read function.
+  int _read(VPIN vpin) {
+
+    // Return a value for the specified vpin.
+    int result = _pinValues[vpin-_firstVpin];
+
+    return result;
+  }
+
+  // Loop function to do background scanning of the input port.  State 
+  //  machine parses the incoming command as it is received.  Command
+  //  is in the form "#Nm,n#" where m is the index and n is the value.
+  void _loop(unsigned long currentMicros) {
+    (void)currentMicros;  // Suppress compiler warnings
+    if (_serial->available()) {
+      // Input data available to read.  Read a character.
+      char c = _serial->read();
+      switch (_inputState) {
+        case 0: // Waiting for start of command
+          if (c == '#')  // Start of command received.
+            _inputState = 1;
+          break;
+        case 1: // Expecting command character
+          if (c == 'N') { // 'Notify' character received
+            _inputState = 2;
+            _inputValue = _inputIndex = 0;
+          } else
+            _inputState = 0; // Unexpected char, reset
+          break;
+        case 2: // reading first parameter (index)
+          if (isdigit(c))
+            _inputIndex = _inputIndex * 10 + (c-'0');
+          else if (c==',') 
+            _inputState = 3;
+          else
+            _inputState = 0; // Unexpected char, reset
+          break;
+        case 3: // reading reading second parameter (value)
+          if (isdigit(c)) 
+            _inputValue = _inputValue * 10 - (c-'0');
+          else if (c=='#') { // End of command
+            // Complete command received, do something with it.
+            DIAG(F("ExampleSerial Received command, p1=%d, p2=%d"), _inputIndex, _inputValue);
+            if (_inputIndex >= 0 && _inputIndex < _nPins) { // Store value
+              _pinValues[_inputIndex] = _inputValue;
+            }
+            _inputState = 0; // Done, start again.
+          } else
+            _inputState = 0; // Unexpected char, reset
+          break;
+      }
+    }
+  }
+
+  // Display information about the device, and perhaps its current condition (e.g. active, disabled etc).
+  // Here we display the current values held for the pins.
+  void _display() {
+    DIAG(F("IO_ExampleSerial Configured on Vpins:%u-%u"), (int)_firstVpin, 
+      (int)_firstVpin+_nPins-1);
+    for (int i=0; i<_nPins; i++)
+      DIAG(F("  VPin %2u: %d"), _firstVpin+i, _pinValues[i]);
+  }
+
+
 };
 
-#endif // IO_EXAMPLESERIAL_H
+#endif // IO_EXAMPLESERIAL_H

IO_GPIOBase.h

@@ -34,7 +34,7 @@ class GPIOBase : public IODevice {
 
 protected:
   // Constructor
-  GPIOBase(FSH *deviceName, VPIN firstVpin, uint8_t nPins, uint8_t I2CAddress, int interruptPin);
+  GPIOBase(FSH *deviceName, VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin);
   // Device-specific initialisation
   void _begin() override;
   // Device-specific pin configuration function.  
@@ -47,15 +47,15 @@ protected:
   void _loop(unsigned long currentMicros) override;
 
   // Data fields
-  uint8_t _I2CAddress; 
+ 
   // Allocate enough space for all input pins
-  T _portInputState; 
-  T _portOutputState;
-  T _portMode;
-  T _portPullup;
-  T _portInUse;
-  // Interval between refreshes of each input port
-  static const int _portTickTime = 4000;
+  T _portInputState; // 1=high (inactive), 0=low (activated)
+  T _portOutputState; // 1 =high, 0=low
+  T _portMode;  // 0=input, 1=output
+  T _portPullup; // 0=nopullup, 1=pullup
+  T _portInUse;  // 0=not in use, 1=in use
+  // Target interval between refreshes of each input port
+  static const int _portTickTime = 4000; // 4ms
 
   // Virtual functions for interfacing with I2C GPIO Device
   virtual void _writeGpioPort() = 0;
@@ -76,15 +76,21 @@ protected:
 
 // Constructor
 template <class T>
-GPIOBase<T>::GPIOBase(FSH *deviceName, VPIN firstVpin, uint8_t nPins, uint8_t I2CAddress, int interruptPin) :
+GPIOBase<T>::GPIOBase(FSH *deviceName, VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin) :
   IODevice(firstVpin, nPins)
 {
+  if (_nPins > (int)sizeof(T)*8) _nPins = sizeof(T)*8;  // Ensure nPins is consistent with the number of bits in T
   _deviceName = deviceName;
-  _I2CAddress = I2CAddress;
+  _I2CAddress = i2cAddress;
   _gpioInterruptPin = interruptPin;
   _hasCallback = true;
   // Add device to list of devices.
   addDevice(this);
+
+  _portMode = 0;  // default to input mode
+  _portPullup = -1; // default to pullup enabled
+  _portInputState = -1;  // default to all inputs high (inactive)
+  _portInUse = 0;  // No ports in use initially.
 }
 
 template <class T>
@@ -99,21 +105,16 @@ void GPIOBase<T>::_begin() {
 #if defined(DIAG_IO)
     _display();
 #endif
-    _portMode = 0;  // default to input mode
-    _portPullup = -1; // default to pullup enabled
-    _portInputState = -1;
-    _portInUse = 0;
     _setupDevice();
     _deviceState = DEVSTATE_NORMAL;
   } else {
-    DIAG(F("%S I2C:x%x Device not detected"), _deviceName, _I2CAddress);
+    DIAG(F("%S I2C:%s Device not detected"), _deviceName, _I2CAddress.toString());
     _deviceState = DEVSTATE_FAILED;
   }
 }
 
 // Configuration parameters for inputs: 
 //  params[0]: enable pullup
-//  params[1]: invert input (optional)
 template <class T>
 bool GPIOBase<T>::_configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) {
   if (configType != CONFIGURE_INPUT) return false;
@@ -121,7 +122,7 @@ bool GPIOBase<T>::_configure(VPIN vpin, ConfigTypeEnum configType, int paramCoun
   bool pullup = params[0];
   int pin = vpin - _firstVpin;
   #ifdef DIAG_IO
-  DIAG(F("%S I2C:x%x Config Pin:%d Val:%d"), _deviceName, _I2CAddress, pin, pullup);
+  DIAG(F("%S I2C:%s Config Pin:%d Val:%d"), _deviceName, _I2CAddress.toString(), pin, pullup);
   #endif
   uint16_t mask = 1 << pin;
   if (pullup) 
@@ -151,7 +152,7 @@ void GPIOBase<T>::_loop(unsigned long currentMicros) {
       _deviceState = DEVSTATE_NORMAL;
     } else {
       _deviceState = DEVSTATE_FAILED;
-      DIAG(F("%S I2C:x%x Error:%d %S"), _deviceName, _I2CAddress, status, 
+      DIAG(F("%S I2C:%s Error:%d %S"), _deviceName, _I2CAddress.toString(), status, 
         I2CManager.getErrorMessage(status));
     }
     _processCompletion(status);
@@ -174,7 +175,7 @@ void GPIOBase<T>::_loop(unsigned long currentMicros) {
 
     #ifdef DIAG_IO
     if (differences)
-      DIAG(F("%S I2C:x%x PortStates:%x"), _deviceName, _I2CAddress, _portInputState);
+      DIAG(F("%S I2C:%s PortStates:%x"), _deviceName, _I2CAddress.toString(), _portInputState);
     #endif
   }
 
@@ -195,7 +196,7 @@ void GPIOBase<T>::_loop(unsigned long currentMicros) {
 
 template <class T>
 void GPIOBase<T>::_display() {
-  DIAG(F("%S I2C:x%x Configured on Vpins:%d-%d %S"), _deviceName, _I2CAddress, 
+  DIAG(F("%S I2C:%s Configured on Vpins:%u-%u %S"), _deviceName, _I2CAddress.toString(), 
     _firstVpin, _firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
 }
 
@@ -204,7 +205,7 @@ void GPIOBase<T>::_write(VPIN vpin, int value) {
   int pin = vpin - _firstVpin;
   T mask = 1 << pin;
   #ifdef DIAG_IO
-  DIAG(F("%S I2C:x%x Write Pin:%d Val:%d"), _deviceName, _I2CAddress, pin, value);
+  DIAG(F("%S I2C:%s Write Pin:%d Val:%d"), _deviceName, _I2CAddress.toString(), pin, value);
   #endif
 
   // Set port mode output if currently not output mode
@@ -240,10 +241,10 @@ int GPIOBase<T>::_read(VPIN vpin) {
   // Set unused pin and write mode pin value to 1
     _portInputState |= ~_portInUse | _portMode;
     #ifdef DIAG_IO
-    DIAG(F("%S I2C:x%x PortStates:%x"), _deviceName, _I2CAddress, _portInputState);
+    DIAG(F("%S I2C:%s PortStates:%x"), _deviceName, _I2CAddress.toString(), _portInputState);
     #endif
   }
   return (_portInputState & mask) ? 0 : 1;  // Invert state (5v=0, 0v=1)
 }
 
-#endif
+#endif

IO_HALDisplay.h

@@ -0,0 +1,265 @@
+/*
+ *  © 2024, Paul Antoine
+ *  © 2023, Neil McKechnie
+ *  All rights reserved.
+ *  
+ *  This file is part of DCC-EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/* 
+ * This driver provides a more immediate interface into the OLED display
+ * than the one installed through the config.h file.  When an LCD(...) call
+ * is made, the text is output immediately to the specified display line,
+ * without waiting for the next 2.5 second refresh.  However, if the line 
+ * specified is off the screen then the text in the bottom line will be 
+ * overwritten.  There is however a special case that if line 255 is specified, 
+ * the existing text will scroll up and the new line added to the bottom
+ * line of the screen.
+ * 
+ * To install, use the following command in myHal.cpp:
+ *
+ *    HALDisplay<OLED>::create(address, width, height);
+ * 
+ * where address is the I2C address of the OLED display (0x3c or 0x3d),
+ * width is the width in pixels, and height is the height in pixels.
+ * 
+ * Valid width and height are 128x32 (SSD1306 controller), 
+ * 128x64 (SSD1306) and 132x64 (SH1106).  The driver uses
+ * a 5x7 character set in a 6x8 pixel cell.
+ * 
+ * OR
+ * 
+ *    HALDisplay<LiquidCrystal>::create(address, width, height);
+ * 
+ * where address is the I2C address of the LCD display (0x27 typically),
+ * width is the width in characters (16 or 20 typically),
+ * and height is the height in characters (2 or 4 typically).
+ */
+
+
+#ifndef IO_HALDisplay_H
+#define IO_HALDisplay_H
+
+#include "IODevice.h"
+#include "DisplayInterface.h"
+#include "SSD1306Ascii.h"
+#include "LiquidCrystal_I2C.h"
+#include "version.h"
+
+typedef SSD1306AsciiWire OLED;
+typedef LiquidCrystal_I2C LiquidCrystal; 
+
+template <class T> 
+class HALDisplay : public IODevice, public DisplayInterface {
+private:
+  // Here we define the device-specific variables.  
+  uint8_t _height; // in pixels
+  uint8_t _width;  // in pixels
+  T *_displayDriver;
+  uint8_t _rowNo = 0;   // Row number being written by caller
+  uint8_t _colNo = 0;  // Position in line being written by caller
+  uint8_t _numRows;
+  uint8_t _numCols;
+  char *_buffer = NULL;
+  uint8_t *_rowGeneration = NULL;
+  uint8_t *_lastRowGeneration = NULL;
+  uint8_t _rowNoToScreen = 0; 
+  uint8_t _charPosToScreen = 0;
+  bool _startAgain = false;
+  DisplayInterface *_nextDisplay = NULL;
+
+public:
+  //  Static function to handle "HALDisplay::create(...)" calls.
+  static void create(I2CAddress i2cAddress, int width, int height) {
+    if (checkNoOverlap(0, 0, i2cAddress)) new HALDisplay(0, i2cAddress, width, height);
+  } 
+  static void create(uint8_t displayNo, I2CAddress i2cAddress, int width, int height) {
+    if (checkNoOverlap(0, 0, i2cAddress)) new HALDisplay(displayNo, i2cAddress, width, height);
+  } 
+
+protected:
+  // Constructor
+  HALDisplay(uint8_t displayNo, I2CAddress i2cAddress, int width, int height) {
+    _displayDriver = new T(i2cAddress, width, height);
+    if (!_displayDriver) return;  // Check for memory allocation failure
+    _I2CAddress = i2cAddress;
+    _width = width;
+    _height = height;
+    _numCols = _displayDriver->getNumCols();
+    _numRows = _displayDriver->getNumRows();
+
+    _charPosToScreen = _numCols;
+
+    // Allocate arrays
+    _buffer = (char *)calloc(_numRows*_numCols, sizeof(char));
+    if (!_buffer) return;  // Check for memory allocation failure
+    _rowGeneration = (uint8_t *)calloc(_numRows, sizeof(uint8_t));
+    if (!_rowGeneration) return;  // Check for memory allocation failure
+    _lastRowGeneration = (uint8_t *)calloc(_numRows, sizeof(uint8_t));
+    if (!_lastRowGeneration) return;  // Check for memory allocation failure
+
+    // Fill buffer with spaces
+    memset(_buffer, ' ', _numCols*_numRows);
+
+    // Add device to list of HAL devices (not necessary but allows
+    // status to be displayed using <D HAL SHOW> and device to be
+    // reinitialised using <D HAL RESET>).
+    IODevice::addDevice(this);
+
+    // Moved after addDevice() to ensure I2CManager.begin() has been called fisrt
+    _displayDriver->clearNative();
+
+    // Also add this display to list of display handlers
+    DisplayInterface::addDisplay(displayNo);
+
+    // Is this the system display (0)?
+    if (displayNo == 0) {
+      // Set first two lines on screen
+      this->setRow(displayNo, 0);
+      print(F("DCC-EX v"));
+      print(F(VERSION));
+      setRow(displayNo, 1);
+      print(F("Lic GPLv3"));
+    }
+  }
+  
+  
+  void screenUpdate() {
+    // Loop through the buffer and if a row has changed
+    // (rowGeneration[row] is changed) then start writing the
+    // characters from the buffer, one character per entry, 
+    // to the screen until that row has been refreshed.
+
+    // First check if the OLED driver is still busy from a previous 
+    // call.  If so, don't do anything until the next entry.
+    if (!_displayDriver->isBusy()) {
+      // Check if we've just done the end of a row
+      if (_charPosToScreen >= _numCols) {
+        // Move to next line
+        if (++_rowNoToScreen >= _numRows || _startAgain) {
+          _rowNoToScreen = 0; // Wrap to first row
+          _startAgain = false;
+        }
+
+        if (_rowGeneration[_rowNoToScreen] != _lastRowGeneration[_rowNoToScreen]) {
+          // Row content has changed, so start outputting it
+          _lastRowGeneration[_rowNoToScreen] = _rowGeneration[_rowNoToScreen];
+          _displayDriver->setRowNative(_rowNoToScreen);
+          _charPosToScreen = 0;  // Prepare to output first character on next entry
+        } else {
+          // Row not changed, don't bother writing it.
+        }
+      } else {
+        // output character at current position
+        _displayDriver->writeNative(_buffer[_rowNoToScreen*_numCols+_charPosToScreen++]);
+      }  
+    }
+    return;
+  }
+
+  /////////////////////////////////////////////////
+  // IODevice Class Member Overrides
+  /////////////////////////////////////////////////
+
+  // Device-specific initialisation
+  void _begin() override {
+    // Initialise device
+    if (_displayDriver->begin()) {
+
+      _display();
+
+      // Force all rows to be redrawn
+      for (uint8_t row=0; row<_numRows; row++)
+        _rowGeneration[row]++;
+      
+      // Start with top line (looks better).  
+      // The numbers will wrap round on the first loop2 entry.
+      _rowNoToScreen = _numRows;
+      _charPosToScreen = _numCols;
+    }
+  }
+
+  void _loop(unsigned long) override {
+    screenUpdate();
+  }
+  
+  // Display information about the device.
+  void _display() {
+    DIAG(F("HALDisplay %d configured on addr %s"), _displayNo, _I2CAddress.toString());
+  }
+  
+  /////////////////////////////////////////////////
+  // DisplayInterface functions
+  // 
+  /////////////////////////////////////////////////
+  
+public:
+  void _displayLoop() override {
+    screenUpdate();
+  }
+
+  // Position on nominated line number (0 to number of lines -1)
+  // Clear the line in the buffer ready for updating
+  // The displayNo referenced here is remembered and any following
+  // calls to write() will be directed to that display.
+  void _setRow(byte line) override {
+    if (line == 255) {
+      // LCD(255,"xxx") or SCREEN(displayNo,255, "xxx") - 
+      // scroll the contents of the buffer and put the new line
+      // at the bottom of the screen
+      for (int row=1; row<_numRows; row++) {
+        strncpy(&_buffer[(row-1)*_numCols], &_buffer[row*_numCols], _numCols);
+        _rowGeneration[row-1]++;
+      }
+      line = _numRows-1;
+    } else if (line >= _numRows) 
+      line = _numRows - 1;  // Overwrite bottom line.
+
+    _rowNo = line;
+    // Fill line with blanks
+    for (_colNo = 0; _colNo < _numCols; _colNo++)
+      _buffer[_rowNo*_numCols+_colNo] = ' ';
+    _colNo = 0;
+    // Mark that the buffer has been touched.  It will start being 
+    // sent to the screen on the next loop entry, by which time
+    // the line should have been written to the buffer.
+    _rowGeneration[_rowNo]++;
+    // Indicate that the output loop is to start updating the screen again from
+    // row 0.  Otherwise, on a full screen rewrite the bottom part may be drawn
+    // before the top part!
+    _startAgain = true;
+  }
+
+  // Write one character to the screen referenced in the last setRow() call.
+  virtual size_t _write(uint8_t c) override {
+    // Write character to buffer (if there's space)
+    if (_colNo < _numCols) {
+      _buffer[_rowNo*_numCols+_colNo++] = c;
+    }
+    return 1;
+  }
+
+  // Write blanks to all of the screen buffer
+  void _clear() {
+    // Clear buffer
+    memset(_buffer, ' ', _numCols*_numRows);
+    _colNo = 0;
+    _rowNo = 0;
+  }
+
+};
+
+#endif // IO_HALDisplay_H

IO_HCSR04.h

@@ -30,7 +30,7 @@
  *
  * This driver polls the HC-SR04 by sending the trigger pulse and then measuring
  * the length of the received pulse.  If the calculated distance is less than
- * the threshold, the output state returned by a read() call changes to 1.  If
+ * the threshold, the output _state returned by a read() call changes to 1.  If
  * the distance is greater than the threshold plus a hysteresis margin, the
  * output changes to 0. The device also supports readAnalogue(), which returns
  * the measured distance in cm, or 32767 if the distance exceeds the
@@ -48,6 +48,20 @@
  * Note: The timing accuracy required for measuring the pulse length means that
  * the pins have to be direct Arduino pins; GPIO pins on an IO Extender cannot
  * provide the required accuracy.
+ * 
+ * Example configuration:
+ *  HCSR04::create(23000, 32, 33, 80, 85);
+ * 
+ * Where 23000 is the VPIN allocated,
+ *       32 is the pin connected to the HCSR04 trigger terminal,
+ *       33 is the pin connected to the HCSR04 echo terminal,
+ *       80 is the distance in cm below which pin 23000 will be active,
+ *   and 85 is the distance in cm above which pin 23000 will be inactive.
+ * 
+ * Alternative configuration, which hogs the processor until the measurement is complete
+ * (old behaviour, more accurate but higher impact on other CS tasks):
+ *  HCSR04::create(23000, 32, 33, 80, 85, HCSR04::LOOP);
+ * 
  */
 
 #ifndef IO_HCSR04_H
@@ -61,37 +75,52 @@ private:
   // pins must be arduino GPIO pins, not extender pins or HAL pins.
   int _trigPin = -1;
   int _echoPin = -1;
-  // Thresholds for setting active state in cm.
+  // Thresholds for setting active _state in cm.
   uint8_t _onThreshold;  // cm
   uint8_t _offThreshold; // cm
   // Last measured distance in cm.
   uint16_t _distance;
-  // Active=1/inactive=0 state 
+  // Active=1/inactive=0 _state 
   uint8_t _value = 0;
-  // Factor for calculating the distance (cm) from echo time (ms).
+  // Factor for calculating the distance (cm) from echo time (us).
   //  Based on a speed of sound of 345 metres/second.
-  const uint16_t factor = 58; // ms/cm
+  const uint16_t factor = 58; // us/cm
+  // Limit the time spent looping by dropping out when the expected
+  // worst case threshold value is greater than an arbitrary value.
+  const uint16_t maxPermittedLoopTime = 10 * factor; // max in us
+  unsigned long _startTime = 0;
+  unsigned long _maxTime = 0;
+  enum {DORMANT, MEASURING}; // _state values
+  uint8_t _state = DORMANT;
+  uint8_t _counter = 0;
+  uint16_t _options = 0;
 
 public:
-  // Constructor perfroms static initialisation of the device object
-  HCSR04 (VPIN vpin, int trigPin, int echoPin, uint16_t onThreshold, uint16_t offThreshold) {
+  enum Options {
+    LOOP = 1,  // Option HCSR04::LOOP reinstates old behaviour, i.e. complete measurement in one loop entry.
+  };
+ 
+  // Static create function provides alternative way to create object
+  static void create(VPIN vpin, int trigPin, int echoPin, uint16_t onThreshold, uint16_t offThreshold, uint16_t options = 0) {
+    if (checkNoOverlap(vpin))
+        new HCSR04(vpin, trigPin, echoPin, onThreshold, offThreshold, options);
+  }
+
+protected:
+  // Constructor performs static initialisation of the device object
+  HCSR04 (VPIN vpin, int trigPin, int echoPin, uint16_t onThreshold, uint16_t offThreshold, uint16_t options) {
     _firstVpin = vpin;
     _nPins = 1;
     _trigPin = trigPin;
     _echoPin = echoPin;
     _onThreshold = onThreshold;
     _offThreshold = offThreshold;
+    _options = options;
     addDevice(this);
   }
-
-  // Static create function provides alternative way to create object
-  static void create(VPIN vpin, int trigPin, int echoPin, uint16_t onThreshold, uint16_t offThreshold) {
-    new HCSR04(vpin, trigPin, echoPin, onThreshold, offThreshold);
-  }
-
-protected:
-  // _begin function called to perform dynamic initialisation of the device
+ // _begin function called to perform dynamic initialisation of the device
   void _begin() override {
+    _state = 0;
     pinMode(_trigPin, OUTPUT);
     pinMode(_echoPin, INPUT);
     ArduinoPins::fastWriteDigital(_trigPin, 0);
@@ -111,78 +140,104 @@ protected:
     return _distance;
   }
 
-  // _loop function - read HC-SR04 once every 50 milliseconds.
+  // _loop function - read HC-SR04 once every 100 milliseconds.
   void _loop(unsigned long currentMicros) override {
-    read_HCSR04device();
-    // Delay next loop entry until 50ms have elapsed.
-    delayUntil(currentMicros + 50000UL);
+    unsigned long waitTime;
+    switch(_state) {
+      case DORMANT: // Issue pulse
+        // If receive pin is still set on from previous call, do nothing till next entry.
+        if (ArduinoPins::fastReadDigital(_echoPin)) return;
+
+        // Send 10us pulse to trigger transmitter
+        ArduinoPins::fastWriteDigital(_trigPin, 1);
+        delayMicroseconds(10);
+        ArduinoPins::fastWriteDigital(_trigPin, 0);
+
+        // Wait, with timeout, for echo pin to become set.
+        // Measured time delay is just under 500us, so 
+        // wait for max of 1000us.
+        _startTime = micros();
+        _maxTime = 1000;
+
+        while (!ArduinoPins::fastReadDigital(_echoPin)) {
+          // Not set yet, see if we've timed out.
+          waitTime = micros() - _startTime;
+          if (waitTime > _maxTime) {
+            // Timeout waiting for pulse start, abort the read and start again
+            _state = DORMANT;
+            return;
+          }
+        }
+
+        // Echo pulse started, so wait for echo pin to reset, and measure length of pulse
+        _startTime = micros();
+        _maxTime = factor * _offThreshold;
+        _state = MEASURING;
+        // If maximum measurement time is high, then skip until next loop entry before 
+        // starting to look for pulse end.
+        // This gives better accuracy at shorter distance thresholds but without extending 
+        // loop execution time for longer thresholds.  If LOOP option is set on, then
+        // the entire measurement will be done in one loop entry, i.e. the code will fall
+        // through into the measuring phase.
+        if (!(_options & LOOP) && _maxTime > maxPermittedLoopTime) break;
+        /* fallthrough */
+
+      case MEASURING: // Check if echo pulse has finished
+        do {
+          waitTime = micros() - _startTime;
+          if (!ArduinoPins::fastReadDigital(_echoPin)) {
+            // Echo pulse completed; check if pulse length is below threshold and if so set value.
+            if (waitTime <= factor * _onThreshold) {
+              // Measured time is within the onThreshold, so value is one.
+              _value = 1;
+              // If the new distance value is less than the current, use it immediately.
+              // But if the new distance value is longer, then it may be erroneously long
+              // (because of extended loop times delays), so apply a delay to distance increases.
+              uint16_t estimatedDistance = waitTime / factor;
+              if (estimatedDistance < _distance) 
+                _distance = estimatedDistance;
+              else
+                _distance += 1;  // Just increase distance slowly.
+              _counter = 0;
+              //DIAG(F("HCSR04: Pulse Len=%l Distance=%d"), waitTime, _distance);
+            }
+            _state = DORMANT;
+          } else {
+            // Echo pulse hasn't finished, so check if maximum time has elapsed
+            // If pulse is too long then set return value to zero,
+            //  and finish without waiting for end of pulse.
+            if (waitTime > _maxTime) {
+              // Pulse length longer than maxTime, value is provisionally zero.
+              // But don't change _value unless provisional value is zero for 10 consecutive measurements
+              if (_value == 1) {
+                if (++_counter >= 10) {
+                  _value = 0;
+                  _distance = 32767;
+                  _counter = 0;
+                }
+              }
+              _state = DORMANT; // start again
+            }
+          }
+          // If there's lots of time remaining before the expected completion time,
+          // then exit and wait for next loop entry.  Otherwise, loop until we finish.
+          // If option LOOP is set, then we loop until finished anyway.
+          uint32_t remainingTime = _maxTime - waitTime;
+          if (!(_options & LOOP) && remainingTime < maxPermittedLoopTime) return;
+        } while (_state == MEASURING) ;
+        break;
+    }
+    // Datasheet recommends a wait of at least 60ms between measurement cycles
+    if (_state == DORMANT)
+      delayUntil(currentMicros+60000UL); // wait 60ms till next measurement
+
   }
 
   void _display() override {
-    DIAG(F("HCSR04 Configured on Vpin:%d TrigPin:%d EchoPin:%d On:%dcm Off:%dcm"),
+    DIAG(F("HCSR04 Configured on VPIN:%u TrigPin:%d EchoPin:%d On:%dcm Off:%dcm"),
       _firstVpin, _trigPin, _echoPin, _onThreshold, _offThreshold);
   }
 
-private:
-  // This polls the HC-SR04 device by sending a pulse and measuring the duration of
-  //  the pulse observed on the receive pin.  In order to be kind to the rest of the CS
-  //  software, no interrupts are used and interrupts are not disabled.  The pulse duration
-  //  is measured in a loop, using the micros() function.  Therefore, interrupts from other
-  //  sources may affect the result.  However, interrupts response code in CS typically takes
-  //  much less than the 58us frequency for the DCC interrupt, and 58us corresponds to only 1cm
-  //  in the HC-SR04.
-  //  To reduce chatter on the output, hysteresis is applied on reset: the output is set to 1 when the 
-  //  measured distance is less than the onThreshold, and is set to 0 if the measured distance is
-  //  greater than the offThreshold.
-  //
-  void read_HCSR04device() {
-    // uint16 enough to time up to 65ms
-    uint16_t startTime, waitTime, currentTime, maxTime;  
-
-    // If receive pin is still set on from previous call, abort the read.
-    if (ArduinoPins::fastReadDigital(_echoPin))
-      return;
-
-    // Send 10us pulse to trigger transmitter
-    ArduinoPins::fastWriteDigital(_trigPin, 1);
-    delayMicroseconds(10);
-    ArduinoPins::fastWriteDigital(_trigPin, 0);
-
-    // Wait for receive pin to be set
-    startTime = currentTime = micros();
-    maxTime = factor * _offThreshold * 2;
-    while (!ArduinoPins::fastReadDigital(_echoPin)) {
-      // lastTime = currentTime;
-      currentTime = micros();
-      waitTime = currentTime - startTime;
-      if (waitTime > maxTime) {
-        // Timeout waiting for pulse start, abort the read
-        return;
-      }
-    }
-
-    // Wait for receive pin to reset, and measure length of pulse
-    startTime = currentTime = micros();
-    maxTime = factor * _offThreshold;
-    while (ArduinoPins::fastReadDigital(_echoPin)) {
-      currentTime = micros();
-      waitTime = currentTime - startTime;
-      // If pulse is too long then set return value to zero,
-      //  and finish without waiting for end of pulse.
-      if (waitTime > maxTime) {
-        // Pulse length longer than maxTime, reset value.
-        _value = 0;
-        _distance = 32767;
-        return;
-      }
-    } 
-    // Check if pulse length is below threshold, if so set value.
-    //DIAG(F("HCSR04: Pulse Len=%l Distance=%d"), waitTime, distance);
-    _distance = waitTime / factor; // in centimetres
-    if (_distance < _onThreshold) 
-      _value = 1;
-  }
-
 };
 
-#endif //IO_HCSR04_H
+#endif //IO_HCSR04_H

IO_I2CDFPlayer.h

@@ -0,0 +1,805 @@
+   /*
+ *  © 2023, Neil McKechnie. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/*
+ * DFPlayer is an MP3 player module with an SD card holder.  It also has an integrated
+ * amplifier, so it only needs a power supply and a speaker.
+ * This driver is a modified version of the IO_DFPlayer.h file
+ * *********************************************************************************************
+ * 
+ * Dec 2023, Added NXP SC16IS752 I2C Dual UART to enable the DFPlayer connection over the I2C bus
+ * The SC16IS752 has 64 bytes TX & RX FIFO buffer
+ * First version without interrupts from I2C UART and only RX/TX are used, interrupts may not be
+ * needed as the RX Fifo holds the reply 
+ * 
+ * Jan 2024, Issue with using both UARTs simultaniously, the secod uart seems to work  but the first transmit 
+ * corrupt data. This need more analysis and experimenatation. 
+ * Will push this driver to the dev branch with the uart fixed to 0 
+ * Both SC16IS750 (single uart) and SC16IS752 (dual uart, but only uart 0 is enable)
+ * 
+ * myHall.cpp configuration syntax:
+ * 
+ * I2CDFPlayer::create(1st vPin, vPins, I2C address, xtal);
+ * 
+ * Parameters:
+ * 1st vPin     : First virtual pin that EX-Rail can control to play a sound, use PLAYSOUND command (alias of ANOUT)
+ * vPins        : Total number of virtual pins allocated (2 vPins are supported, one for each UART)
+ *                1st vPin for UART 0, 2nd for UART 1
+ * I2C Address  : I2C address of the serial controller, in 0x format
+ * xtal         : 0 for 1,8432Mhz, 1 for 14,7456Mhz
+ * 
+ * The vPin is also a pin that can be read, it indicate if the DFPlayer has finished playing a track
+ *
+ */
+
+#ifndef IO_I2CDFPlayer_h
+#define IO_I2CDFPlayer_h
+
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+
+// Debug and diagnostic defines, enable too many will result in slowing the driver
+//#define DIAG_I2CDFplayer
+//#define DIAG_I2CDFplayer_data
+//#define DIAG_I2CDFplayer_reg
+//#define DIAG_I2CDFplayer_playing
+
+class I2CDFPlayer : public IODevice {
+private: 
+  const uint8_t MAXVOLUME=30;
+  uint8_t RETRYCOUNT = 0x03;
+  bool _playing = false;
+  uint8_t _inputIndex = 0;
+  unsigned long _commandSendTime; // Time (us) that last transmit took place.
+  unsigned long _timeoutTime;
+  uint8_t _recvCMD;  // Last received command code byte
+  bool _awaitingResponse = false;  
+  uint8_t _retryCounter = RETRYCOUNT; // Max retries before timing out
+  uint8_t _requestedVolumeLevel = MAXVOLUME;
+  uint8_t _currentVolume = MAXVOLUME;
+  int _requestedSong = -1;  // -1=none, 0=stop, >0=file number
+  bool _repeat = false; // audio file is repeat playing
+  uint8_t _previousCmd = true;
+  // SC16IS752 defines
+  I2CAddress _I2CAddress;
+  I2CRB _rb;
+  uint8_t _UART_CH=0x00;  // Fix uart ch to 0 for now
+  // Communication parameters for the DFPlayer are fixed at 8 bit, No parity, 1 stopbit
+  uint8_t WORD_LEN = 0x03;    // Value LCR bit 0,1
+  uint8_t STOP_BIT = 0x00;    // Value LCR bit 2 
+  uint8_t PARITY_ENA = 0x00;  // Value LCR bit 3
+  uint8_t PARITY_TYPE = 0x00; // Value LCR bit 4
+  uint32_t BAUD_RATE = 9600;
+  uint8_t PRESCALER = 0x01;   // Value MCR bit 7
+  uint8_t TEMP_REG_VAL = 0x00;
+  uint8_t FIFO_RX_LEVEL = 0x00;
+  uint8_t RX_BUFFER = 0x00; // nr of bytes copied into _inbuffer
+  uint8_t FIFO_TX_LEVEL = 0x00;  
+  bool _playCmd = false;
+  bool _volCmd = false;
+  bool _folderCmd = false;
+  uint8_t _requestedFolder = 0x01; // default to folder 01
+  uint8_t _currentFolder = 0x01; // default to folder 01
+  bool _repeatCmd = false;
+  bool _stopplayCmd = false;
+  bool _resetCmd = false;
+  bool _eqCmd = false;
+  uint8_t _requestedEQValue = DF_NORMAL;
+  uint8_t _currentEQvalue = DF_NORMAL; // start equalizer value
+  bool _daconCmd = false;
+  uint8_t _audioMixer = 0x01; // Default to output amplifier 1
+  bool _setamCmd = false; // Set the Audio mixer channel
+  uint8_t _outbuffer [11]; // DFPlayer command is 10 bytes + 1 byte register address & UART channel
+  uint8_t _inbuffer[10]; // expected DFPlayer return 10 bytes
+   
+  unsigned long _sc16is752_xtal_freq;
+  unsigned long SC16IS752_XTAL_FREQ_LOW = 1843200; // To support cheap eBay/AliExpress SC16IS752 boards
+  unsigned long SC16IS752_XTAL_FREQ_HIGH = 14745600; // Support for higher baud rates, standard for modular EX-IO system
+   
+public:
+  // Constructor
+   I2CDFPlayer(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint8_t xtal){
+    _firstVpin = firstVpin;
+    _nPins = nPins;
+    _I2CAddress = i2cAddress;
+    if (xtal == 0){
+      _sc16is752_xtal_freq = SC16IS752_XTAL_FREQ_LOW;
+    } else { // should be 1
+        _sc16is752_xtal_freq = SC16IS752_XTAL_FREQ_HIGH;
+      }
+    addDevice(this);
+   } 
+  
+public:
+  static void create(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint8_t xtal) {
+    if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new I2CDFPlayer(firstVpin, nPins, i2cAddress, xtal); 
+    }
+
+  void _begin() override {
+    // check if SC16IS752 exist first, initialize and then resume DFPlayer init via SC16IS752
+    I2CManager.begin();
+    I2CManager.setClock(1000000);
+    if (I2CManager.exists(_I2CAddress)){
+      DIAG(F("SC16IS752 I2C:%s UART detected"), _I2CAddress.toString());
+      Init_SC16IS752(); // Initialize UART
+      if (_deviceState == DEVSTATE_FAILED){
+        DIAG(F("SC16IS752 I2C:%s UART initialization failed"), _I2CAddress.toString());
+        }
+      } else {
+         DIAG(F("SC16IS752 I2C:%s UART not detected"), _I2CAddress.toString());
+        }
+      #if defined(DIAG_IO)
+      _display();
+      #endif
+      // Now init DFPlayer
+      // Send a query to the device to see if it responds
+      _deviceState = DEVSTATE_INITIALISING; 
+      sendPacket(0x42,0,0);
+      _timeoutTime = micros() + 5000000UL;  // 5 second timeout      
+      _awaitingResponse = true; 
+     }
+  
+  
+  void _loop(unsigned long currentMicros) override {
+    // Read responses from device
+    uint8_t status = _rb.status;
+    if (status == I2C_STATUS_PENDING) return;  // Busy, so don't do anything
+    if (status == I2C_STATUS_OK) { 
+      processIncoming(currentMicros);
+          // Check if a command sent to device has timed out.  Allow 0.5 second for response
+          // added retry counter, sometimes we do not sent keep alive due to other commands sent to DFPlayer
+      if (_awaitingResponse && (int32_t)(currentMicros - _timeoutTime) > 0) { // timeout triggered
+        if(_retryCounter == 0){ // retry counter out of luck, must take the device to failed state     
+          DIAG(F("I2CDFPlayer:%s, DFPlayer not responding on UART channel: 0x%x"), _I2CAddress.toString(), _UART_CH);
+          _deviceState = DEVSTATE_FAILED;
+          _awaitingResponse = false;
+          _playing = false;
+          _retryCounter = RETRYCOUNT;
+        } else { // timeout and retry protection and recovery of corrupt data frames from DFPlayer
+            #ifdef DIAG_I2CDFplayer_playing
+              DIAG(F("I2CDFPlayer: %s, DFPlayer timout, retry counter: %d on UART channel: 0x%x"), _I2CAddress.toString(), _retryCounter, _UART_CH);
+            #endif
+            _timeoutTime = currentMicros + 5000000UL;  // Timeout if no response within 5 seconds// reset timeout
+            _awaitingResponse = false; // trigger sending a keep alive 0x42 in processOutgoing()
+            _retryCounter --; // decrement retry counter                        
+            resetRX_fifo(); // reset the RX fifo as it has corrupt data            
+          }
+      }      
+    }
+
+    status = _rb.status;
+    if (status == I2C_STATUS_PENDING) return;  // Busy, try next time
+    if (status == I2C_STATUS_OK) {
+     // Send any commands that need to go.
+      processOutgoing(currentMicros);
+     }
+    delayUntil(currentMicros + 10000); // Only enter every 10ms    
+  }
+
+ 
+  // Check for incoming data, and update busy flag and other state accordingly
+ 
+  void processIncoming(unsigned long currentMicros) {
+    // Expected message is in the form "7E FF 06 3D xx xx xx xx xx EF"
+    RX_fifo_lvl();
+    if (FIFO_RX_LEVEL >= 10) {      
+      #ifdef DIAG_I2CDFplayer
+        DIAG(F("I2CDFPlayer: %s Retrieving data from RX Fifo on UART_CH: 0x%x FIFO_RX_LEVEL: %d"),_I2CAddress.toString(), _UART_CH, FIFO_RX_LEVEL); 
+      #endif
+      _outbuffer[0] = REG_RHR << 3 | _UART_CH << 1;
+      // Only copy 10 bytes from RX FIFO, there maybe additional partial return data after a track is finished playing in the RX FIFO
+      I2CManager.read(_I2CAddress, _inbuffer, 10, _outbuffer, 1); // inbuffer[] has the data now
+      //delayUntil(currentMicros + 10000); // Allow time to get the data
+      RX_BUFFER = 10; // We have copied 10 bytes from RX FIFO to _inbuffer
+        #ifdef DIAG_I2CDFplayer_data
+          DIAG(F("SC16IS752: At I2C: %s, UART channel: 0x%x, RX FIFO Data"), _I2CAddress.toString(), _UART_CH);
+          for (int i = 0; i < sizeof _inbuffer; i++){
+            DIAG(F("SC16IS752: Data _inbuffer[0x%x]: 0x%x"), i, _inbuffer[i]);  
+          }
+        #endif       
+    } else {
+        FIFO_RX_LEVEL = 0; //set to 0, we'll read a fresh FIFO_RX_LEVEL next time
+        return; // No data or not enough data in rx fifo, check again next time around
+      }
+
+    
+    bool ok = false;
+    //DIAG(F("I2CDFPlayer: RX_BUFFER: %d"), RX_BUFFER);
+    while (RX_BUFFER != 0) {
+      int c = _inbuffer[_inputIndex]; // Start at 0, increment to FIFO_RX_LEVEL
+      switch (_inputIndex) {
+        case 0:
+          if (c == 0x7E) ok = true;
+          break;
+        case 1:
+          if (c == 0xFF) ok = true;
+          break;
+        case 2:
+          if (c== 0x06) ok = true;
+          break;
+        case 3:
+          _recvCMD = c; // CMD byte
+          ok = true;
+          break;
+        case 6:
+          switch (_recvCMD) {
+            //DIAG(F("I2CDFPlayer: %s, _recvCMD: 0x%x _awaitingResponse: 0x0%x"),_I2CAddress.toString(), _recvCMD, _awaitingResponse);
+            case 0x42:
+              // Response to status query
+              _playing = (c != 0);              
+              // Mark the device online and cancel timeout
+              if (_deviceState==DEVSTATE_INITIALISING) {
+                _deviceState = DEVSTATE_NORMAL;
+                #ifdef DIAG_I2CDFplayer
+                 DIAG(F("I2CDFPlayer: %s, UART_CH: 0x0%x, _deviceState: 0x0%x"),_I2CAddress.toString(), _UART_CH, _deviceState);
+                #endif 
+                #ifdef DIAG_IO
+                _display();
+                #endif
+              }
+              _awaitingResponse = false;
+              break;
+            case 0x3d:            
+              // End of play
+              if (_playing) {
+                #ifdef DIAG_IO
+                  DIAG(F("I2CDFPlayer: Finished"));
+                #endif
+                _playing = false;
+              }
+              break;
+            case 0x40:
+              // Error codes; 1: Module Busy
+              DIAG(F("I2CDFPlayer: Error %d returned from device"), c);
+              _playing = false;
+              break;
+          }
+          ok = true;
+          break;
+        case 4: case 5: case 7: case 8: 
+          ok = true;  // Skip over these bytes in message.
+          break;
+        case 9:
+          if (c==0xef) {
+            // Message finished
+            _retryCounter = RETRYCOUNT; // reset the retry counter as we have received a valid packet
+          }
+          break;
+        default:
+          break;
+      }
+      if (ok){
+        _inputIndex++;  // character as expected, so increment index
+        RX_BUFFER --; // Decrease FIFO_RX_LEVEL with each character read from _inbuffer[_inputIndex]
+      } else {
+        _inputIndex = 0;  // otherwise reset.
+        RX_BUFFER = 0;
+      }
+    }
+    RX_BUFFER = 0; //Set to 0, we'll read a new RX FIFO level again
+  }
+
+
+  // Send any commands that need to be sent
+  void processOutgoing(unsigned long currentMicros) {
+    // When two commands are sent in quick succession, the device will often fail to 
+    // execute one.  Testing has indicated that a delay of 100ms or more is required
+    // between successive commands to get reliable operation.
+    // If 100ms has elapsed since the last thing sent, then check if there's some output to do.
+    if (((int32_t)currentMicros - _commandSendTime) > 100000) {
+      if ( _resetCmd == true){
+          sendPacket(0x0C,0,0);
+          _resetCmd = false;          
+      } else if(_volCmd == true) { // do the volme before palying a track
+         if(_requestedVolumeLevel >= 0 && _requestedVolumeLevel <= 30){         
+         _currentVolume = _requestedVolumeLevel; // If _requestedVolumeLevel is out of range, sent _currentV1olume      
+         }
+         sendPacket(0x06, 0x00, _currentVolume);
+        _volCmd = false;
+      } else if (_playCmd == true) {
+        // Change song
+        if (_requestedSong != -1) {
+          #ifdef DIAG_I2CDFplayer_playing
+           DIAG(F("I2CDFPlayer: _requestedVolumeLevel: %u, _requestedSong: %u, _currentFolder: %u _playCmd: 0x%x"), _requestedVolumeLevel, _requestedSong, _currentFolder, _playCmd);
+          #endif               
+          sendPacket(0x0F, _currentFolder, _requestedSong);  // audio file in folder          
+          _requestedSong = -1; 
+          _playCmd = false;
+        }           
+      } //else if (_requestedSong == 0) {
+        else if (_stopplayCmd == true) {
+          #ifdef DIAG_I2CDFplayer_playing
+           DIAG(F("I2CDFPlayer: Stop playing: _stopplayCmd: 0x%x"), _stopplayCmd);
+          #endif
+        sendPacket(0x16, 0x00, 0x00);  // Stop playing        
+        _requestedSong = -1;
+        _repeat = false; // reset repeat        
+        _stopplayCmd = false;
+        } else if (_folderCmd == true) {
+          #ifdef DIAG_I2CDFplayer_playing
+           DIAG(F("I2CDFPlayer: Folder: _folderCmd: 0x%x, _requestedFolder: %d"), _stopplayCmd, _requestedFolder);
+          #endif
+          if (_currentFolder != _requestedFolder){
+            _currentFolder = _requestedFolder;
+          }
+          _folderCmd = false;
+      } else if (_repeatCmd == true) {
+        if(_repeat == false) { // No repeat play currently
+          #ifdef DIAG_I2CDFplayer_playing
+           DIAG(F("I2CDFPlayer: Repeat: _repeatCmd: 0x%x, _requestedSong: %d, _repeat: 0x0%x"), _repeatCmd, _requestedSong, _repeat);
+          #endif 
+          sendPacket(0x08, 0x00, _requestedSong);  // repeat playing audio file in root folder          
+          _requestedSong = -1;
+          _repeat = true; 
+        }
+        _repeatCmd= false;      
+      } else if (_daconCmd == true) { // Always turn DAC on
+        #ifdef DIAG_I2CDFplayer_playing
+          DIAG(F("I2CDFPlayer: DACON: _daconCmd: 0x%x"), _daconCmd);
+        #endif 
+        sendPacket(0x1A,0,0x00);
+        _daconCmd = false;
+      } else if (_eqCmd == true){ // Set Equalizer, values 0x00 - 0x05        
+        if (_currentEQvalue != _requestedEQValue){
+          #ifdef DIAG_I2CDFplayer_playing
+           DIAG(F("I2CDFPlayer: EQ: _eqCmd: 0x%x, _currentEQvalue: 0x0%x, _requestedEQValue: 0x0%x"), _eqCmd, _currentEQvalue, _requestedEQValue);
+          #endif 
+          _currentEQvalue = _requestedEQValue;
+          sendPacket(0x07,0x00,_currentEQvalue);
+        }
+        _eqCmd = false;
+      } else if (_setamCmd == true){ // Set Audio mixer channel
+         setGPIO(); // Set the audio mixer channel
+         /*        
+          if (_audioMixer == 1){ // set to audio mixer 1       
+            if (_UART_CH == 0){ 
+              TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 0 to high
+            } else { // must be UART 1
+              TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 1 to high
+              }
+           //_setamCmd = false;
+           //UART_WriteRegister(REG_IOSTATE, TEMP_REG_VAL);
+          } else { // set to audio mixer 2
+              if (_UART_CH == 0){ 
+                TEMP_REG_VAL &= (0x00 << _UART_CH); //Set GPIO pin 0 to Low
+              } else { // must be UART 1
+                TEMP_REG_VAL &= (0x00 << _UART_CH); //Set GPIO pin 1 to Low
+                }
+              //_setamCmd = false;
+              //UART_WriteRegister(REG_IOSTATE, TEMP_REG_VAL);
+            }*/
+        _setamCmd = false;        
+      } else if ((int32_t)currentMicros - _commandSendTime > 1000000) {
+        // Poll device every second that other commands aren't being sent,
+        // to check if it's still connected and responding.
+          #ifdef DIAG_I2CDFplayer_playing
+           DIAG(F("I2CDFPlayer: Send keepalive") );
+          #endif
+        sendPacket(0x42,0,0); 
+        if (!_awaitingResponse) {
+          #ifdef DIAG_I2CDFplayer_playing
+           DIAG(F("I2CDFPlayer: Send keepalive, _awaitingResponse: 0x0%x"), _awaitingResponse );
+          #endif
+          _timeoutTime = currentMicros + 5000000UL;  // Timeout if no response within 5 seconds
+          _awaitingResponse = true;
+        }
+      }
+    }  
+  }
+
+
+  // Write to a vPin will do nothing
+  void _write(VPIN vpin, int value) override {
+    if (_deviceState == DEVSTATE_FAILED) return;
+      #ifdef DIAG_IO
+        DIAG(F("I2CDFPlayer: Writing to any vPin not supported"));
+      #endif
+  }
+
+
+  // WriteAnalogue on first pin uses the nominated value as a file number to start playing, if file number > 0.
+  // Volume may be specified as second parameter to writeAnalogue.
+  // If value is zero, the player stops playing.  
+  // WriteAnalogue on second pin sets the output volume.
+  //
+  // WriteAnalogue to be done on first vpin
+  //
+  //void _writeAnalogue(VPIN vpin, int value, uint8_t volume=0, uint16_t=0) override { 
+  void _writeAnalogue(VPIN vpin, int value, uint8_t volume=0, uint16_t cmd=0) override { 
+    if (_deviceState == DEVSTATE_FAILED) return;    
+    #ifdef DIAG_IO
+      DIAG(F("I2CDFPlayer: VPIN:%u FileNo:%d Volume:%d Command:0x%x"), vpin, value, volume, cmd);
+    #endif
+    uint8_t pin = vpin - _firstVpin;
+    if (pin == 0) { // Enhanced DFPlayer commands, do nothing if not vPin 0     
+     // Read command and value
+      switch (cmd){
+       //case NONE:
+       // DFPlayerCmd = cmd;
+       // break;
+       case DF_PLAY:
+        _playCmd = true;
+        _volCmd = true;        
+        _requestedSong = value;
+        _requestedVolumeLevel = volume; 
+        _playing = true;        
+        break;
+        case DF_VOL:
+          _volCmd = true;          
+          _requestedVolumeLevel = volume;
+        break;
+       case DF_FOLDER:
+        _folderCmd = true;
+        if (volume <= 0 || volume > 99){ // Range checking, valid values 1-99, else default to 1
+          _requestedFolder = 0x01; // if outside range, default to folder 01  
+        } else {
+          _requestedFolder = volume;
+        }        
+        break;
+       case DF_REPEATPLAY: // Need to check if _repeat == true, if so do nothing        
+        if (_repeat == false) {
+           #ifdef DIAG_I2CDFplayer_playing
+              DIAG(F("I2CDFPlayer: WriteAnalog Repeat: _repeat: 0x0%x, value: %d _repeatCmd: 0x%x"), _repeat, value, _repeatCmd);
+           #endif
+          _repeatCmd = true;          
+          _requestedSong = value;
+          _requestedVolumeLevel = volume;
+          _playing = true;         
+        }
+        break;
+       case DF_STOPPLAY:
+        _stopplayCmd = true;        
+        break;
+       case DF_EQ:
+        #ifdef DIAG_I2CDFplayer_playing
+          DIAG(F("I2CDFPlayer: WriteAnalog EQ: cmd: 0x%x, EQ value: 0x%x"), cmd, volume);
+        #endif
+        _eqCmd = true;        
+        if (volume <= 0 || volume > 5) { // If out of range, default to NORMAL
+          _requestedEQValue = DF_NORMAL;            
+        } else { // Valid EQ parameter range
+          _requestedEQValue = volume;     
+          }
+        break;        
+       case DF_RESET:
+        _resetCmd = true;      
+        break; 
+       case DF_DACON: // Works, but without the DACOFF command limited value, except when not relying on DFPlayer default to turn the DAC on
+        #ifdef DIAG_I2CDFplayer_playing
+          DIAG(F("I2CDFPlayer: WrtieAnalog DACON: cmd: 0x%x"), cmd);
+        #endif
+        _daconCmd = true;
+        break;
+        case DF_SETAM: // Set the audio mixer channel to 1 or 2
+          _setamCmd = true;
+          #ifdef DIAG_I2CDFplayer_playing
+            DIAG(F("I2CDFPlayer: WrtieAnalog SETAM: cmd: 0x%x"), cmd);
+          #endif
+          if (volume <= 0 || volume > 2) { // If out of range, default to 1
+            _audioMixer = 1;            
+          } else { // Valid SETAM parameter in range
+              _audioMixer = volume; // _audioMixer valid values 1 or 2
+            }          
+        break;
+       default:
+        break;
+      }
+    }    
+  }
+
+  // A read on any pin indicates if the player is still playing.
+  int _read(VPIN vpin) override {
+    if (_deviceState == DEVSTATE_FAILED) return false;
+    uint8_t pin = vpin - _firstVpin;
+      if (pin == 0) { // Do nothing if not vPin 0
+        return _playing;
+      }
+    }
+
+  void _display() override {
+    DIAG(F("I2CDFPlayer Configured on Vpins:%u-%u %S"), _firstVpin, _firstVpin+_nPins-1,
+      (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
+  }
+  
+private: 
+  // DFPlayer command frame
+  // 7E FF 06 0F 00 01 01 xx xx EF
+  // 0	  ->	7E is start code
+  // 1	  ->	FF is version
+  // 2	  ->	06 is length
+  // 3	  ->	0F is command
+  // 4	  ->	00 is no receive
+  // 5~6	->	01 01 is argument
+  // 7~8	->	checksum = 0 - ( FF+06+0F+00+01+01 )
+  // 9	  ->	EF is end code
+
+  void sendPacket(uint8_t command, uint8_t arg1 = 0, uint8_t arg2 = 0) {
+    FIFO_TX_LEVEL = 0; // Reset FIFO_TX_LEVEL    
+    uint8_t out[] = {
+        0x7E,
+        0xFF,
+        06,
+        command,
+        00,
+        //static_cast<uint8_t>(arg >> 8),
+        //static_cast<uint8_t>(arg & 0x00ff),
+        arg1,
+        arg2,
+        00,
+        00,
+        0xEF };
+
+    setChecksum(out);
+
+      // Prepend the DFPlayer command with REG address and UART Channel in _outbuffer
+      _outbuffer[0] = REG_THR << 3 | _UART_CH << 1; //TX FIFO and UART Channel      
+      for ( int i = 1; i < sizeof(out)+1 ; i++){
+        _outbuffer[i] = out[i-1];
+      }
+
+      #ifdef DIAG_I2CDFplayer_data
+       DIAG(F("SC16IS752: I2C: %s Sent packet function"), _I2CAddress.toString());
+       for (int i = 0; i < sizeof _outbuffer; i++){
+        DIAG(F("SC16IS752: Data _outbuffer[0x%x]: 0x%x"), i, _outbuffer[i]);  
+       }
+      #endif
+      
+    TX_fifo_lvl();
+    if(FIFO_TX_LEVEL > 0){ //FIFO is empty
+      I2CManager.write(_I2CAddress, _outbuffer, sizeof(_outbuffer), &_rb);
+      //I2CManager.write(_I2CAddress, _outbuffer, sizeof(_outbuffer));
+      #ifdef DIAG_I2CDFplayer
+       DIAG(F("SC16IS752: I2C: %s data transmit complete on UART: 0x%x"), _I2CAddress.toString(), _UART_CH);
+      #endif
+    } else {
+      DIAG(F("I2CDFPlayer at: %s, TX FIFO not empty on UART: 0x%x"), _I2CAddress.toString(), _UART_CH);
+      _deviceState = DEVSTATE_FAILED; // This should not happen      
+    }
+    _commandSendTime = micros();
+  }
+
+  uint16_t calcChecksum(uint8_t* packet)
+  {
+    uint16_t sum = 0;
+    for (int i = 1; i < 7; i++)
+    {
+      sum += packet[i];
+    }
+    return -sum;
+  }
+
+  void setChecksum(uint8_t* out)
+  {
+    uint16_t sum = calcChecksum(out);
+    out[7] = (sum >> 8);
+    out[8] = (sum & 0xff);
+  }
+
+  // SC16IS752 functions
+  // Initialise SC16IS752 only for this channel
+  // First a software reset
+  // Enable FIFO and clear TX & RX FIFO
+  // Need to set the following registers
+  // IOCONTROL set bit 1 and 2 to 0 indicating that they are GPIO
+  // IODIR set all bit to 1 indicating al are output
+  // IOSTATE set only bit 0 to 1 for UART 0, or only bit 1 for UART 1  // 
+  // LCR bit 7=0 divisor latch (clock division registers DLH & DLL, they store 16 bit divisor), 
+  //     WORD_LEN, STOP_BIT, PARITY_ENA and PARITY_TYPE
+  // MCR bit 7=0 clock divisor devide-by-1 clock input
+  // DLH most significant part of divisor
+  // DLL least significant part of divisor
+  //
+  // BAUD_RATE, WORD_LEN, STOP_BIT, PARITY_ENA and PARITY_TYPE have been defined and initialized
+  // 
+  void Init_SC16IS752(){ // Return value is in _deviceState
+    #ifdef DIAG_I2CDFplayer
+      DIAG(F("SC16IS752: Initialize I2C: %s , UART Ch: 0x%x"), _I2CAddress.toString(),  _UART_CH);      
+    #endif
+    //uint16_t _divisor = (SC16IS752_XTAL_FREQ / PRESCALER) / (BAUD_RATE * 16);
+    uint16_t _divisor = (_sc16is752_xtal_freq/PRESCALER)/(BAUD_RATE * 16);  // Calculate _divisor for baudrate
+    TEMP_REG_VAL = 0x08; // UART Software reset
+    UART_WriteRegister(REG_IOCONTROL, TEMP_REG_VAL);
+    TEMP_REG_VAL = 0x00; // Set pins to GPIO mode
+    UART_WriteRegister(REG_IOCONTROL, TEMP_REG_VAL);
+    TEMP_REG_VAL = 0xFF; //Set all pins as output
+    UART_WriteRegister(REG_IODIR, TEMP_REG_VAL);
+    UART_ReadRegister(REG_IOSTATE); // Read current state as not to overwrite the other GPIO pins
+    TEMP_REG_VAL = _inbuffer[0];
+    setGPIO(); // Set the audio mixer channel
+    /*
+    if (_UART_CH == 0){ // Set Audio mixer channel
+      TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 0 to high
+    } else { // must be UART 1
+      TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 1 to high
+    }
+    UART_WriteRegister(REG_IOSTATE, TEMP_REG_VAL);
+    */
+    TEMP_REG_VAL = 0x07; // Reset FIFO, clear RX & TX FIFO
+    UART_WriteRegister(REG_FCR, TEMP_REG_VAL);
+    TEMP_REG_VAL = 0x00; // Set MCR to all 0, includes Clock divisor
+    UART_WriteRegister(REG_MCR, TEMP_REG_VAL);
+    TEMP_REG_VAL = 0x80 | WORD_LEN | STOP_BIT | PARITY_ENA | PARITY_TYPE;
+    UART_WriteRegister(REG_LCR, TEMP_REG_VAL); // Divisor latch enabled
+    UART_WriteRegister(REG_DLL, (uint8_t)_divisor);  // Write DLL
+    UART_WriteRegister(REG_DLH, (uint8_t)(_divisor >> 8)); // Write DLH
+    UART_ReadRegister(REG_LCR);
+    TEMP_REG_VAL = _inbuffer[0] & 0x7F; // Disable Divisor latch enabled bit
+    UART_WriteRegister(REG_LCR, TEMP_REG_VAL); // Divisor latch disabled  
+
+    uint8_t status = _rb.status;
+    if (status != I2C_STATUS_OK) {
+      DIAG(F("SC16IS752: I2C: %s failed %S"), _I2CAddress.toString(), I2CManager.getErrorMessage(status));
+      _deviceState = DEVSTATE_FAILED;
+    } else {
+      #ifdef DIAG_IO
+       DIAG(F("SC16IS752: I2C: %s, _deviceState: %S"), _I2CAddress.toString(), I2CManager.getErrorMessage(status));
+      #endif
+     _deviceState = DEVSTATE_NORMAL; // If I2C state is OK, then proceed to initialize DFPlayer 
+    }
+  }
+
+  
+  // Read the Receive FIFO Level register (RXLVL), return a single unsigned integer
+  // of nr of characters in the RX FIFO, bit 6:0, 7 not used, set to zero
+  // value from 0 (0x00) to 64 (0x40) Only display if RX FIFO has data
+  // The RX fifo level is used to check if there are enough bytes to process a frame
+  void RX_fifo_lvl(){
+    UART_ReadRegister(REG_RXLV);
+    FIFO_RX_LEVEL = _inbuffer[0];
+    #ifdef DIAG_I2CDFplayer
+     if (FIFO_RX_LEVEL > 0){
+     //if (FIFO_RX_LEVEL > 0 && FIFO_RX_LEVEL < 10){
+      DIAG(F("SC16IS752: At I2C: %s, UART channel: 0x%x, FIFO_RX_LEVEL: 0d%d"), _I2CAddress.toString(), _UART_CH, _inbuffer[0]);
+    }
+    #endif   
+  }
+
+  // When a frame is transmitted from the DFPlayer to the serial port, and at the same time the CS is sending a 42 query
+  // the following two frames from the DFPlayer are corrupt. This result in the receive buffer being out of sync and the 
+  // CS will complain and generate a timeout.
+  // The RX fifo has corrupt data and need to be flushed, this function does that
+  // 
+  void resetRX_fifo(){
+    #ifdef DIAG_I2CDFplayer
+      DIAG(F("SC16IS752: At I2C: %s, UART channel: 0x%x, RX fifo reset"), _I2CAddress.toString(), _UART_CH);
+    #endif    
+    TEMP_REG_VAL = 0x03; // Reset RX fifo
+    UART_WriteRegister(REG_FCR, TEMP_REG_VAL);
+  }
+
+  // Set or reset GPIO pin 0 and 1 depending on the UART ch
+  // This function may be modified in a future release to enable all 8 pins to be set or reset with EX-Rail
+  // for various auxilary functions
+  void setGPIO(){
+    UART_ReadRegister(REG_IOSTATE); // Get the current GPIO pins state from the IOSTATE register
+    TEMP_REG_VAL = _inbuffer[0];
+    if (_audioMixer == 1){ // set to audio mixer 1
+      if (_UART_CH == 0){ 
+        TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 0 to high
+      } else { // must be UART 1
+         TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 1 to high
+        }
+    } else { // set to audio mixer 2
+        if (_UART_CH == 0){ 
+          TEMP_REG_VAL &= ~(0x01 << _UART_CH); //Set GPIO pin 0 to Low
+        } else { // must be UART 1
+           TEMP_REG_VAL &= ~(0x01 << _UART_CH); //Set GPIO pin 1 to Low
+          }
+      }    
+    UART_WriteRegister(REG_IOSTATE, TEMP_REG_VAL);
+    _setamCmd = false;  
+  }
+  
+
+  // Read the Tranmit FIFO Level register (TXLVL), return a single unsigned integer
+  // of nr characters free in the TX FIFO, bit 6:0, 7 not used, set to zero
+  // value from 0 (0x00) to 64 (0x40)
+  //
+  void TX_fifo_lvl(){
+    UART_ReadRegister(REG_TXLV);
+    FIFO_TX_LEVEL = _inbuffer[0];
+    #ifdef DIAG_I2CDFplayer
+    //  DIAG(F("SC16IS752: At I2C: %s, UART channel: 0x%x, FIFO_TX_LEVEL: 0d%d"), _I2CAddress.toString(), _UART_CH, FIFO_TX_LEVEL);
+    #endif 
+  }
+
+
+  //void UART_WriteRegister(I2CAddress _I2CAddress, uint8_t _UART_CH, uint8_t UART_REG, uint8_t Val, I2CRB &_rb){
+  void UART_WriteRegister(uint8_t UART_REG, uint8_t Val){
+    _outbuffer[0] = UART_REG << 3 | _UART_CH << 1;
+    _outbuffer[1] = Val;
+    #ifdef DIAG_I2CDFplayer_reg
+      DIAG(F("SC16IS752: Write register at I2C: %s, UART channel: 0x%x, Register: 0x%x, Data: 0b%b"), _I2CAddress.toString(), _UART_CH, UART_REG, _outbuffer[1]);
+    #endif
+    I2CManager.write(_I2CAddress, _outbuffer, 2);
+  }
+
+ 
+  void UART_ReadRegister(uint8_t UART_REG){
+     _outbuffer[0] = UART_REG << 3 | _UART_CH << 1; // _outbuffer[0] has now UART_REG and UART_CH
+     I2CManager.read(_I2CAddress, _inbuffer, 1, _outbuffer, 1);    
+    // _inbuffer has the REG data
+    #ifdef DIAG_I2CDFplayer_reg
+      DIAG(F("SC16IS752: Read register at I2C: %s, UART channel: 0x%x, Register: 0x%x, Data: 0b%b"), _I2CAddress.toString(), _UART_CH, UART_REG, _inbuffer[0]);
+    #endif
+  }
+
+// SC16IS752 General register set (from the datasheet)
+enum : uint8_t{
+    REG_RHR       = 0x00, // FIFO Read
+    REG_THR       = 0x00, // FIFO Write
+    REG_IER       = 0x01, // Interrupt Enable Register R/W
+    REG_FCR       = 0x02, // FIFO Control Register Write
+    REG_IIR       = 0x02, // Interrupt Identification Register Read
+    REG_LCR       = 0x03, // Line Control Register R/W
+    REG_MCR       = 0x04, // Modem Control Register R/W
+    REG_LSR       = 0x05, // Line Status Register Read
+    REG_MSR       = 0x06, // Modem Status Register Read
+    REG_SPR       = 0x07, // Scratchpad Register R/W
+    REG_TCR       = 0x06, // Transmission Control Register R/W
+    REG_TLR       = 0x07, // Trigger Level Register R/W    
+    REG_TXLV      = 0x08, // Transmitter FIFO Level register Read
+    REG_RXLV      = 0x09, // Receiver FIFO Level register Read
+    REG_IODIR     = 0x0A, // Programmable I/O pins Direction register R/W
+    REG_IOSTATE   = 0x0B, // Programmable I/O pins State register R/W
+    REG_IOINTENA  = 0x0C, // I/O Interrupt Enable register R/W
+    REG_IOCONTROL = 0x0E, // I/O Control register R/W
+    REG_EFCR      = 0x0F, // Extra Features Control Register R/W
+  };
+
+// SC16IS752 Special register set
+enum : uint8_t{
+    REG_DLL       = 0x00, // Division registers R/W
+    REG_DLH       = 0x01, // Division registers R/W
+  };
+
+// SC16IS752 Enhanced regiter set
+enum : uint8_t{
+    REG_EFR       = 0X02, // Enhanced Features Register R/W
+    REG_XON1      = 0x04, // R/W
+    REG_XON2      = 0x05, // R/W
+    REG_XOFF1     = 0x06, // R/W
+    REG_XOFF2     = 0x07, // R/W
+  };
+
+
+// DFPlayer commands and values
+// Declared in this scope
+enum  : uint8_t{
+    DF_PLAY          = 0x0F,
+    DF_VOL           = 0x06,
+    DF_FOLDER        = 0x2B, // Not a DFPlayer command, used to set folder nr where audio file is
+    DF_REPEATPLAY    = 0x08,
+    DF_STOPPLAY      = 0x16,
+    DF_EQ            = 0x07, // Set equaliser, require parameter NORMAL, POP, ROCK, JAZZ, CLASSIC or BASS
+    DF_RESET         = 0x0C,
+    DF_DACON         = 0x1A,
+    DF_SETAM         = 0x2A, // Set audio mixer 1 or 2 for this DFPLayer   
+    DF_NORMAL        = 0x00, // Equalizer parameters
+    DF_POP           = 0x01,
+    DF_ROCK          = 0x02,
+    DF_JAZZ          = 0x03,
+    DF_CLASSIC       = 0x04,
+    DF_BASS          = 0x05,    
+  };
+
+};
+
+#endif // IO_I2CDFPlayer_h

IO_MCP23008.h

@@ -1,4 +1,5 @@
 /*
+ *  © 2022 Paul M Antoine
  *  © 2021, Neil McKechnie. All rights reserved.
  *  
  *  This file is part of DCC++EX API
@@ -24,20 +25,20 @@
 
 class MCP23008 : public GPIOBase<uint8_t> {
 public:
-  static void create(VPIN firstVpin, uint8_t nPins, uint8_t I2CAddress, int interruptPin=-1) {
-    new MCP23008(firstVpin, nPins, I2CAddress, interruptPin);
+  static void create(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) {
+    if (checkNoOverlap(firstVpin, nPins,i2cAddress)) new MCP23008(firstVpin, nPins, i2cAddress, interruptPin);
   }
 
+private:
   // Constructor
-  MCP23008(VPIN firstVpin, uint8_t nPins, uint8_t I2CAddress, int interruptPin=-1)
-    : GPIOBase<uint8_t>((FSH *)F("MCP23008"), firstVpin, min(nPins, 8), I2CAddress, interruptPin) {
+  MCP23008(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1)
+    : GPIOBase<uint8_t>((FSH *)F("MCP23008"), firstVpin, nPins, i2cAddress, interruptPin) {
 
     requestBlock.setRequestParams(_I2CAddress, inputBuffer, sizeof(inputBuffer),
       outputBuffer, sizeof(outputBuffer));
     outputBuffer[0] = REG_GPIO;
   }
   
-private:
   void _writeGpioPort() override {
     I2CManager.write(_I2CAddress, 2, REG_GPIO, _portOutputState);
   }
@@ -59,7 +60,7 @@ private:
     if (immediate) {
       uint8_t buffer;
       I2CManager.read(_I2CAddress, &buffer, 1, 1, REG_GPIO);
-      _portInputState = buffer;
+      _portInputState = buffer | _portMode;
     } else {
       // Queue new request
       requestBlock.wait(); // Wait for preceding operation to complete
@@ -70,7 +71,7 @@ private:
   // This function is invoked when an I/O operation on the requestBlock completes.
   void _processCompletion(uint8_t status) override {
     if (status == I2C_STATUS_OK) 
-      _portInputState = inputBuffer[0];
+      _portInputState = inputBuffer[0] | _portMode;
     else  
       _portInputState = 0xff;
   }
@@ -97,4 +98,4 @@ private:
 
 };
 
-#endif
+#endif

IO_MCP23017.h

@@ -30,20 +30,19 @@
  
 class MCP23017 : public GPIOBase<uint16_t> {
 public:
-  static void create(VPIN vpin, int nPins, uint8_t I2CAddress, int interruptPin=-1) {
-    new MCP23017(vpin, min(nPins,16), I2CAddress, interruptPin);
+  static void create(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) {
+    if (checkNoOverlap(vpin, nPins, i2cAddress)) new MCP23017(vpin, nPins, i2cAddress, interruptPin);
   }
-  
+
+private:  
   // Constructor
-  MCP23017(VPIN vpin, int nPins, uint8_t I2CAddress, int interruptPin=-1) 
-    : GPIOBase<uint16_t>((FSH *)F("MCP23017"), vpin, nPins, I2CAddress, interruptPin) 
+  MCP23017(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) 
+    : GPIOBase<uint16_t>((FSH *)F("MCP23017"), vpin, nPins, i2cAddress, interruptPin) 
   {
     requestBlock.setRequestParams(_I2CAddress, inputBuffer, sizeof(inputBuffer),
       outputBuffer, sizeof(outputBuffer));
     outputBuffer[0] = REG_GPIOA;
   }
-
-private:
   void _writeGpioPort() override {
     I2CManager.write(_I2CAddress, 3, REG_GPIOA, _portOutputState, _portOutputState>>8);
   }
@@ -66,7 +65,7 @@ private:
     if (immediate) {
       uint8_t buffer[2];
       I2CManager.read(_I2CAddress, buffer, 2, 1, REG_GPIOA);
-      _portInputState = ((uint16_t)buffer[1]<<8) | buffer[0];
+      _portInputState = ((uint16_t)buffer[1]<<8) | buffer[0] | _portMode;
     } else {
       // Queue new request
       requestBlock.wait(); // Wait for preceding operation to complete
@@ -77,7 +76,7 @@ private:
   // This function is invoked when an I/O operation on the requestBlock completes.
   void _processCompletion(uint8_t status) override {
     if (status == I2C_STATUS_OK) 
-      _portInputState = ((uint16_t)inputBuffer[1]<<8) | inputBuffer[0];
+      _portInputState = (((uint16_t)inputBuffer[1]<<8) | inputBuffer[0]) | _portMode;
     else  
       _portInputState = 0xffff;
   }
@@ -109,4 +108,4 @@ private:
 
 };
 
-#endif
+#endif

IO_NeoPixel.h

@@ -0,0 +1,334 @@
+/*
+ *  © 2024, Chris Harlow. All rights reserved.
+ *
+ *  This file is part of EX-CommandStation
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+/*
+* The IO_NEOPIXEL.h device driver integrates with one or more Adafruit neopixel drivers.
+* This device driver will configure the device on startup, along with
+* interacting with the device for all input/output duties.
+*
+* To create NEOPIXEL devices, these are defined in myAutomation.h:
+* (Note the device driver is included by default)
+*
+* HAL(NEOPIXEL,first vpin, number of pixels,mode, i2c address) 
+* e.g. HAL(NEOPIXEL,1000,64,NEO_RGB,0x60)
+* This gives each pixel in the chain an individual vpin
+* The number of pixels must match the physical pixels in the chain. 
+* 
+* This driver maintains a colour (rgb value in 5,5,5 bits only) plus an ON bit.
+* This can be written/read with an analog write/read call. 
+* The ON bit can be set on and off with a digital write. This allows for 
+* a pixel to be preset a colour and then turned on and off like any other light. 
+*/
+
+#ifndef IO_EX_NeoPixel_H
+#define IO_EX_NeoPixel_H
+
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+#include "FSH.h"
+
+
+// The following macros to define the Neopixel String type
+// have been copied from the Adafruit Seesaw Library under the 
+// terms of the GPL. 
+// Credit to: https://github.com/adafruit/Adafruit_Seesaw
+
+// The order of primary colors in the NeoPixel data stream can vary
+// among device types, manufacturers and even different revisions of
+// the same item.  The third parameter to the seesaw_NeoPixel
+// constructor encodes the per-pixel byte offsets of the red, green
+// and blue primaries (plus white, if present) in the data stream --
+// the following #defines provide an easier-to-use named version for
+// each permutation.  e.g. NEO_GRB indicates a NeoPixel-compatible
+// device expecting three bytes per pixel, with the first byte
+// containing the green value, second containing red and third
+// containing blue.  The in-memory representation of a chain of
+// NeoPixels is the same as the data-stream order; no re-ordering of
+// bytes is required when issuing data to the chain.
+
+// Bits 5,4 of this value are the offset (0-3) from the first byte of
+// a pixel to the location of the red color byte.  Bits 3,2 are the
+// green offset and 1,0 are the blue offset.  If it is an RGBW-type
+// device (supporting a white primary in addition to R,G,B), bits 7,6
+// are the offset to the white byte...otherwise, bits 7,6 are set to
+// the same value as 5,4 (red) to indicate an RGB (not RGBW) device.
+// i.e. binary representation:
+// 0bWWRRGGBB for RGBW devices
+// 0bRRRRGGBB for RGB
+
+// RGB NeoPixel permutations; white and red offsets are always same
+// Offset:         W          R          G          B
+#define NEO_RGB ((0 << 6) | (0 << 4) | (1 << 2) | (2))
+#define NEO_RBG ((0 << 6) | (0 << 4) | (2 << 2) | (1))
+#define NEO_GRB ((1 << 6) | (1 << 4) | (0 << 2) | (2))
+#define NEO_GBR ((2 << 6) | (2 << 4) | (0 << 2) | (1))
+#define NEO_BRG ((1 << 6) | (1 << 4) | (2 << 2) | (0))
+#define NEO_BGR ((2 << 6) | (2 << 4) | (1 << 2) | (0))
+
+// RGBW NeoPixel permutations; all 4 offsets are distinct
+// Offset:         W          R          G          B
+#define NEO_WRGB ((0 << 6) | (1 << 4) | (2 << 2) | (3))
+#define NEO_WRBG ((0 << 6) | (1 << 4) | (3 << 2) | (2))
+#define NEO_WGRB ((0 << 6) | (2 << 4) | (1 << 2) | (3))
+#define NEO_WGBR ((0 << 6) | (3 << 4) | (1 << 2) | (2))
+#define NEO_WBRG ((0 << 6) | (2 << 4) | (3 << 2) | (1))
+#define NEO_WBGR ((0 << 6) | (3 << 4) | (2 << 2) | (1))
+
+#define NEO_RWGB ((1 << 6) | (0 << 4) | (2 << 2) | (3))
+#define NEO_RWBG ((1 << 6) | (0 << 4) | (3 << 2) | (2))
+#define NEO_RGWB ((2 << 6) | (0 << 4) | (1 << 2) | (3))
+#define NEO_RGBW ((3 << 6) | (0 << 4) | (1 << 2) | (2))
+#define NEO_RBWG ((2 << 6) | (0 << 4) | (3 << 2) | (1))
+#define NEO_RBGW ((3 << 6) | (0 << 4) | (2 << 2) | (1))
+
+#define NEO_GWRB ((1 << 6) | (2 << 4) | (0 << 2) | (3))
+#define NEO_GWBR ((1 << 6) | (3 << 4) | (0 << 2) | (2))
+#define NEO_GRWB ((2 << 6) | (1 << 4) | (0 << 2) | (3))
+#define NEO_GRBW ((3 << 6) | (1 << 4) | (0 << 2) | (2))
+#define NEO_GBWR ((2 << 6) | (3 << 4) | (0 << 2) | (1))
+#define NEO_GBRW ((3 << 6) | (2 << 4) | (0 << 2) | (1))
+
+#define NEO_BWRG ((1 << 6) | (2 << 4) | (3 << 2) | (0))
+#define NEO_BWGR ((1 << 6) | (3 << 4) | (2 << 2) | (0))
+#define NEO_BRWG ((2 << 6) | (1 << 4) | (3 << 2) | (0))
+#define NEO_BRGW ((3 << 6) | (1 << 4) | (2 << 2) | (0))
+#define NEO_BGWR ((2 << 6) | (3 << 4) | (1 << 2) | (0))
+#define NEO_BGRW ((3 << 6) | (2 << 4) | (1 << 2) | (0))
+
+// If 400 KHz support is enabled, the third parameter to the constructor
+// requires a 16-bit value (in order to select 400 vs 800 KHz speed).
+// If only 800 KHz is enabled (as is default on ATtiny), an 8-bit value
+// is sufficient to encode pixel color order, saving some space.
+
+#define NEO_KHZ800 0x0000 // 800 KHz datastream
+#define NEO_KHZ400 0x0100 // 400 KHz datastream
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////
+/*
+ * IODevice subclass for NeoPixel.
+ */
+
+class NeoPixel : public IODevice {
+public:
+  
+  static void create(VPIN vpin, int nPins, uint16_t mode=(NEO_GRB | NEO_KHZ800), I2CAddress i2cAddress=0x60) {
+    if (checkNoOverlap(vpin, nPins, i2cAddress)) new NeoPixel(vpin, nPins, mode, i2cAddress);
+  }
+
+private:
+  
+  static const byte SEESAW_NEOPIXEL_BASE=0x0E;
+  static const byte SEESAW_NEOPIXEL_STATUS = 0x00;
+  static const byte SEESAW_NEOPIXEL_PIN = 0x01;
+  static const byte SEESAW_NEOPIXEL_SPEED = 0x02;
+  static const byte SEESAW_NEOPIXEL_BUF_LENGTH = 0x03;
+  static const byte SEESAW_NEOPIXEL_BUF=0x04;
+  static const byte SEESAW_NEOPIXEL_SHOW=0x05;
+
+  // all adafruit examples say this pin. Presumably its hard wired 
+  // in the adapter anyway. 
+  static const byte SEESAW_PIN15 = 15;
+  
+  // Constructor
+  NeoPixel(VPIN firstVpin, int nPins, uint16_t mode, I2CAddress i2cAddress) {
+    _firstVpin = firstVpin;
+    _nPins=nPins;
+    _I2CAddress = i2cAddress;
+    
+    // calculate the offsets into the seesaw buffer for each colour depending
+    // on the pixel strip type passed in mode.
+
+    _redOffset=4+(mode >> 4 & 0x03);
+    _greenOffset=4+(mode >> 2 & 0x03); 
+    _blueOffset=4+(mode & 0x03); 
+    if (4+(mode >>6 & 0x03) == _redOffset) _bytesPerPixel=3; 
+    else _bytesPerPixel=4; // string has a white byte.
+    
+    _kHz800=(mode & NEO_KHZ400)==0;
+    _showPendimg=false;
+    
+    // Each pixel requires 3 bytes RGB memory.
+    // Although the driver device can remember this, it cant do off/on without
+    // forgetting what the on colour was!
+    pixelBuffer=(RGB *) malloc(_nPins*sizeof(RGB)); 
+    stateBuffer=(byte *) calloc((_nPins+7)/8,sizeof(byte)); // all pixels off  
+    if (pixelBuffer==nullptr || stateBuffer==nullptr) {
+      DIAG(F("NeoPixel I2C:%s not enough RAM"), _I2CAddress.toString());
+      return;
+    }
+    // preset all pins to white so a digital on/off will do something even if no colour set.
+    memset(pixelBuffer,0xFF,_nPins*sizeof(RGB));
+    addDevice(this);
+  }
+
+  void _begin() {
+    
+    // Initialise Neopixel device
+    I2CManager.begin();
+    if (!I2CManager.exists(_I2CAddress)) {
+      DIAG(F("NeoPixel I2C:%s device not found"), _I2CAddress.toString());
+      _deviceState = DEVSTATE_FAILED;
+      return;
+    }
+    
+    byte speedBuffer[]={SEESAW_NEOPIXEL_BASE, SEESAW_NEOPIXEL_SPEED,_kHz800};
+    I2CManager.write(_I2CAddress, speedBuffer, sizeof(speedBuffer));
+    
+    // In the driver there are 3 of 4 byts per pixel
+    auto numBytes=_bytesPerPixel * _nPins; 
+    byte setbuffer[] = {SEESAW_NEOPIXEL_BASE, SEESAW_NEOPIXEL_BUF_LENGTH,
+                  (byte)(numBytes >> 8), (byte)(numBytes & 0xFF)};
+    I2CManager.write(_I2CAddress, setbuffer, sizeof(setbuffer));
+    
+    const byte pinbuffer[] = {SEESAW_NEOPIXEL_BASE, SEESAW_NEOPIXEL_PIN,SEESAW_PIN15};
+    I2CManager.write(_I2CAddress, pinbuffer, sizeof(pinbuffer));
+    
+    for (auto pin=0;pin<_nPins;pin++) transmit(pin);
+     _display();
+  }
+  
+ // loop called by HAL supervisor 
+  void _loop(unsigned long currentMicros) override {
+    (void)currentMicros;
+    if (!_showPendimg) return;
+    byte showBuffer[]={SEESAW_NEOPIXEL_BASE,SEESAW_NEOPIXEL_SHOW};
+    I2CManager.write(_I2CAddress,showBuffer,sizeof(showBuffer));
+    _showPendimg=false;
+  }  
+  
+  
+  // read back pixel on/off
+  int _read(VPIN vpin) override {
+    if (_deviceState == DEVSTATE_FAILED) return 0;
+    return isPixelOn(vpin-_firstVpin);
+  }
+
+  // Write digital value. Sets pixel on or off
+  void _write(VPIN vpin, int value) override {
+    if (_deviceState == DEVSTATE_FAILED) return;
+    auto pixel=vpin-_firstVpin;
+    if (value) {
+      if (isPixelOn(pixel)) return;
+      setPixelOn(pixel);
+    }
+    else { // set off
+      if (!isPixelOn(pixel)) return;
+      setPixelOff(pixel);
+     }
+     transmit(pixel);
+  }
+   
+  VPIN _writeRange(VPIN vpin,int value, int count) {
+    // using write range cuts out the constant vpin to driver lookup so
+    // we can update multiple pixels much faster.
+    VPIN nextVpin=vpin +  (count>_nPins ? _nPins : count);
+    if (_deviceState != DEVSTATE_FAILED) while(vpin<nextVpin) {
+      _write(vpin,value);
+      vpin++;
+    }
+    return nextVpin;  // next pin we cant 
+  }  
+  // Write analogue value.
+  // The convoluted parameter mashing here is to allow passing the RGB and on/off
+  // information through the generic HAL _writeAnalog interface which was originally
+  // designed for servos and short integers  
+  void _writeAnalogue(VPIN vpin, int colour_RG, uint8_t onoff, uint16_t colour_B) override {
+    if (_deviceState == DEVSTATE_FAILED) return;
+    RGB newColour={(byte)((colour_RG>>8) & 0xFF), (byte)(colour_RG & 0xFF), (byte)(colour_B & 0xFF)};
+    auto pixel=vpin-_firstVpin;
+    if (pixelBuffer[pixel]==newColour && isPixelOn(pixel)==(bool)onoff) return; // no change  
+      
+    if (onoff) setPixelOn(pixel); else setPixelOff(pixel);
+    pixelBuffer[pixel]=newColour;
+    transmit(pixel);
+  }
+ VPIN _writeAnalogueRange(VPIN vpin, int colour_RG, uint8_t onoff, uint16_t colour_B, int count) override {
+    // using write range cuts out the constant vpin to driver lookup so
+    VPIN nextVpin=vpin +  (count>_nPins ? _nPins : count); 
+    if (_deviceState != DEVSTATE_FAILED) while(vpin<nextVpin) {
+      _writeAnalogue(vpin,colour_RG, onoff,colour_B);
+      vpin++;
+    }
+    return nextVpin;  // next pin we cant 
+ }
+ 
+  // Display device information and status.
+  void _display() override {
+    DIAG(F("NeoPixel I2C:%s Vpins %u-%u %S"),
+              _I2CAddress.toString(), 
+              (int)_firstVpin, (int)_firstVpin+_nPins-1,
+              _deviceState == DEVSTATE_FAILED ? F("OFFLINE") : F(""));
+  }
+
+
+  
+  bool isPixelOn(int16_t pixel) {return stateBuffer[pixel/8] & (0x80>>(pixel%8));}
+  void setPixelOn(int16_t pixel) {stateBuffer[pixel/8] |= (0x80>>(pixel%8));}
+  void setPixelOff(int16_t pixel) {stateBuffer[pixel/8] &= ~(0x80>>(pixel%8));}
+  
+  // Helper function for error handling
+  void reportError(uint8_t status, bool fail=true) {
+    DIAG(F("NeoPixel I2C:%s Error:%d (%S)"), _I2CAddress.toString(), 
+      status, I2CManager.getErrorMessage(status));
+    if (fail)
+    _deviceState = DEVSTATE_FAILED;
+  }
+
+  
+  void transmit(uint16_t pixel) { 
+    byte buffer[]={SEESAW_NEOPIXEL_BASE,SEESAW_NEOPIXEL_BUF,0x00,0x00,0x00,0x00,0x00};
+    uint16_t offset= pixel * _bytesPerPixel;
+    buffer[2]=(byte)(offset>>8);
+    buffer[3]=(byte)(offset & 0xFF);
+    
+    if (isPixelOn(pixel)) {
+      auto colour=pixelBuffer[pixel];    
+      buffer[_redOffset]=colour.red;
+      buffer[_greenOffset]=colour.green;
+      buffer[_blueOffset]=colour.blue;
+    } // else leave buffer black (in buffer preset to zeros above)
+    
+    // Transmit pixel to driver
+    I2CManager.write(_I2CAddress,buffer,4 +_bytesPerPixel);
+    _showPendimg=true;
+  
+  }
+  struct RGB { 
+      byte red; 
+      byte green; 
+      byte blue; 
+      bool operator==(const RGB& other) const {
+        return red == other.red && green == other.green && blue == other.blue;
+      }
+    };
+
+  RGB*   pixelBuffer = nullptr;
+  byte*  stateBuffer = nullptr;  // 1 bit per pixel
+  bool _showPendimg;
+  
+  // mapping of RGB onto pixel buffer for seesaw.
+  byte _bytesPerPixel;
+  byte _redOffset;
+  byte _greenOffset;
+  byte _blueOffset;
+  bool _kHz800; 
+};
+
+#endif

IO_PCA9555.h

@@ -0,0 +1,111 @@
+/*
+ *  © 2021, Neil McKechnie. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef io_pca9555_h
+#define io_pca9555_h
+
+#include "IO_GPIOBase.h"
+#include "FSH.h"
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////
+/*
+ * IODevice subclass for PCA9555 16-bit I/O expander (NXP & Texas Instruments).
+ */
+ 
+class PCA9555 : public GPIOBase<uint16_t> {
+public:
+  static void create(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) {
+    if (checkNoOverlap(vpin, nPins, i2cAddress)) new PCA9555(vpin,nPins, i2cAddress, interruptPin);
+  }
+
+private:  
+  // Constructor
+  PCA9555(VPIN vpin, uint8_t nPins, I2CAddress I2CAddress, int interruptPin=-1) 
+    : GPIOBase<uint16_t>((FSH *)F("PCA9555"), vpin, nPins, I2CAddress, interruptPin) 
+  {
+    requestBlock.setRequestParams(_I2CAddress, inputBuffer, sizeof(inputBuffer),
+      outputBuffer, sizeof(outputBuffer));
+    outputBuffer[0] = REG_INPUT_P0;
+  }
+  void _writeGpioPort() override {
+    I2CManager.write(_I2CAddress, 3, REG_OUTPUT_P0, _portOutputState, _portOutputState>>8);
+  }
+  void _writePullups() override {
+    // Do nothing, pull-ups are always in place for input ports
+    // This function is here for HAL GPIOBase API compatibilitiy
+      
+  }
+  void _writePortModes() override {
+    // Write 0 to REG_CONF_P0 & REG_CONF_P1 for in-use pins that are outputs, 1 for others.
+    // PCA9555 & TCA9555, Interrupt is always enabled for raising and falling edge
+    uint16_t temp = ~(_portMode & _portInUse);
+    I2CManager.write(_I2CAddress, 3, REG_CONF_P0, temp, temp>>8);    
+  }
+  void _readGpioPort(bool immediate) override {
+    if (immediate) {
+      uint8_t buffer[2];
+      I2CManager.read(_I2CAddress, buffer, 2, 1, REG_INPUT_P0);
+      _portInputState = ((uint16_t)buffer[1]<<8) | buffer[0];
+      /* PCA9555 Int bug fix, from PCA9555 datasheet: "must change command byte to something besides 00h 
+       * after a Read operation to the PCA9555 device or before reading from 
+       * another device"
+       * Recommended solution, read from REG_OUTPUT_P0, then do nothing with the received data
+       * Issue not seen during testing, uncomment if needed 
+       */
+      //I2CManager.read(_I2CAddress, buffer, 2, 1, REG_OUTPUT_P0);
+    } else {
+      // Queue new request
+      requestBlock.wait(); // Wait for preceding operation to complete
+      // Issue new request to read GPIO register
+      I2CManager.queueRequest(&requestBlock);
+    }
+  }
+  // This function is invoked when an I/O operation on the requestBlock completes.
+  void _processCompletion(uint8_t status) override {
+    if (status == I2C_STATUS_OK) 
+      _portInputState = ((uint16_t)inputBuffer[1]<<8) | inputBuffer[0];
+    else  
+      _portInputState = 0xffff;
+  }
+
+  void _setupDevice() override {
+    // HAL API calls
+    _writePortModes();
+    _writePullups();
+    _writeGpioPort();
+  }
+ 
+  uint8_t inputBuffer[2];
+  uint8_t outputBuffer[1];
+ 
+
+  enum {
+    REG_INPUT_P0 = 0x00,
+    REG_INPUT_P1 = 0x01,
+    REG_OUTPUT_P0 = 0x02,
+    REG_OUTPUT_P1 = 0x03,
+    REG_POL_INV_P0 = 0x04,
+    REG_POL_INV_P1 = 0x05,
+    REG_CONF_P0 = 0x06,
+    REG_CONF_P1 = 0x07,    
+  };
+
+};
+
+#endif

IO_PCA9685.cpp

@@ -31,15 +31,14 @@ static const byte MODE1_AI=0x20;      /**< Auto-Increment enabled */
 static const byte MODE1_RESTART=0x80; /**< Restart enabled */
 
 static const float FREQUENCY_OSCILLATOR=25000000.0; /** Accurate enough for our purposes  */
-static const uint8_t PRESCALE_50HZ = (uint8_t)(((FREQUENCY_OSCILLATOR / (50.0 * 4096.0)) + 0.5) - 1);
 static const uint32_t MAX_I2C_SPEED = 1000000L; // PCA9685 rated up to 1MHz I2C clock speed
 
 // Predeclare helper function
 static void writeRegister(byte address, byte reg, byte value);
 
 // Create device driver instance.
-void PCA9685::create(VPIN firstVpin, int nPins, uint8_t I2CAddress) {
-  new PCA9685(firstVpin, nPins, I2CAddress);
+void PCA9685::create(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint16_t frequency) {
+  if (checkNoOverlap(firstVpin, nPins,i2cAddress)) new PCA9685(firstVpin, nPins, i2cAddress, frequency);
 }
 
 // Configure a port on the PCA9685.
@@ -47,7 +46,7 @@ bool PCA9685::_configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, i
   if (configType != CONFIGURE_SERVO) return false;
   if (paramCount != 5) return false;
   #ifdef DIAG_IO
-  DIAG(F("PCA9685 Configure VPIN:%d Apos:%d Ipos:%d Profile:%d Duration:%d state:%d"), 
+  DIAG(F("PCA9685 Configure VPIN:%u Apos:%d Ipos:%d Profile:%d Duration:%d state:%d"), 
     vpin, params[0], params[1], params[2], params[3], params[4]);
   #endif
 
@@ -73,10 +72,14 @@ bool PCA9685::_configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, i
 }
 
 // Constructor
-PCA9685::PCA9685(VPIN firstVpin, int nPins, uint8_t I2CAddress) {
+PCA9685::PCA9685(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint16_t frequency) {
   _firstVpin = firstVpin;
-  _nPins = min(nPins, 16);
-  _I2CAddress = I2CAddress;
+    _nPins = (nPins > 16) ? 16 : nPins;
+  _I2CAddress = i2cAddress;
+  // Calculate prescaler value for PWM clock
+  if (frequency > 1526) frequency = 1526;
+  else if (frequency < 24) frequency = 24;
+  prescaler = FREQUENCY_OSCILLATOR / 4096 / frequency;
   // To save RAM, space for servo configuration is not allocated unless a pin is used.
   // Initialise the pointers to NULL.
   for (int i=0; i<_nPins; i++)
@@ -98,7 +101,7 @@ void PCA9685::_begin() {
   // Initialise I/O module here.
   if (I2CManager.exists(_I2CAddress)) {
     writeRegister(_I2CAddress, PCA9685_MODE1, MODE1_SLEEP | MODE1_AI);    
-    writeRegister(_I2CAddress, PCA9685_PRESCALE, PRESCALE_50HZ);   // 50Hz clock, 20ms pulse period.
+    writeRegister(_I2CAddress, PCA9685_PRESCALE, prescaler);
     writeRegister(_I2CAddress, PCA9685_MODE1, MODE1_AI);
     writeRegister(_I2CAddress, PCA9685_MODE1, MODE1_RESTART | MODE1_AI);
     // In theory, we should wait 500us before sending any other commands to each device, to allow
@@ -114,9 +117,8 @@ void PCA9685::_begin() {
 // Device-specific write function, invoked from IODevice::write().  
 // For this function, the configured profile is used.
 void PCA9685::_write(VPIN vpin, int value) {
-  if (_deviceState == DEVSTATE_FAILED) return;
   #ifdef DIAG_IO
-  DIAG(F("PCA9685 Write Vpin:%d Value:%d"), vpin, value);
+  DIAG(F("PCA9685 Write VPIN:%u Value:%d"), vpin, value);
   #endif
   int pin = vpin - _firstVpin;
   if (value) value = 1;
@@ -125,7 +127,10 @@ void PCA9685::_write(VPIN vpin, int value) {
   if (s != NULL) {
     // Use configured parameters
     _writeAnalogue(vpin, value ? s->activePosition : s->inactivePosition, s->profile, s->duration);
-  } // else { /* ignorethe request */ }
+  }  else {
+     /* simulate digital pin on PWM */
+      _writeAnalogue(vpin, value ? 4095 : 0, Instant | NoPowerOff, 0);     
+      }
 }
 
 // Device-specific writeAnalogue function, invoked from IODevice::writeAnalogue().
@@ -139,11 +144,11 @@ void PCA9685::_write(VPIN vpin, int value) {
 //             4 (Bounce)  Servo 'bounces' at extremes.
 //            
 void PCA9685::_writeAnalogue(VPIN vpin, int value, uint8_t profile, uint16_t duration) {
-  if (_deviceState == DEVSTATE_FAILED) return;
   #ifdef DIAG_IO
-  DIAG(F("PCA9685 WriteAnalogue Vpin:%d Value:%d Profile:%d Duration:%d"), 
-    vpin, value, profile, duration);
+  DIAG(F("PCA9685 WriteAnalogue VPIN:%u Value:%d Profile:%d Duration:%d %S"), 
+    vpin, value, profile, duration, _deviceState == DEVSTATE_FAILED?F("DEVSTATE_FAILED"):F(""));
   #endif
+  if (_deviceState == DEVSTATE_FAILED) return;
   int pin = vpin - _firstVpin;
   if (value > 4095) value = 4095;
   else if (value < 0) value = 0;
@@ -153,10 +158,10 @@ void PCA9685::_writeAnalogue(VPIN vpin, int value, uint8_t profile, uint16_t dur
     // Servo pin not configured, so configure now using defaults
     s = _servoData[pin] = (struct ServoData *) calloc(sizeof(struct ServoData), 1);
     if (s == NULL) return;  // Check for memory allocation failure
-    s->activePosition = 0;
+    s->activePosition = 4095;
     s->inactivePosition = 0;
     s->currentPosition = value;
-    s->profile = Instant;  // Use instant profile (but not this time)
+    s->profile = Instant | NoPowerOff;  // Use instant profile (but not this time)
   }
 
   // Animated profile.  Initiate the appropriate action.
@@ -237,13 +242,13 @@ void PCA9685::updatePosition(uint8_t pin) {
 // between 0 and 4095 for the PWM mark-to-period ratio, with 4095 being 100%.
 void PCA9685::writeDevice(uint8_t pin, int value) {
   #ifdef DIAG_IO
-  DIAG(F("PCA9685 I2C:x%x WriteDevice Pin:%d Value:%d"), _I2CAddress, pin, value);
+  DIAG(F("PCA9685 I2C:%s WriteDevice Pin:%d Value:%d"), _I2CAddress.toString(), pin, value);
   #endif
   // Wait for previous request to complete
   uint8_t status = requestBlock.wait();
   if (status != I2C_STATUS_OK) {
     _deviceState = DEVSTATE_FAILED;
-    DIAG(F("PCA9685 I2C:x%x failed %S"), _I2CAddress, I2CManager.getErrorMessage(status));
+    DIAG(F("PCA9685 I2C:%s failed %S"), _I2CAddress.toString(), I2CManager.getErrorMessage(status));
   } else {
     // Set up new request.
     outputBuffer[0] = PCA9685_FIRST_SERVO + 4 * pin;
@@ -257,7 +262,7 @@ void PCA9685::writeDevice(uint8_t pin, int value) {
 
 // Display details of this device.
 void PCA9685::_display() {
-  DIAG(F("PCA9685 I2C:x%x Configured on Vpins:%d-%d %S"), _I2CAddress, (int)_firstVpin, 
+  DIAG(F("PCA9685 I2C:%s Configured on Vpins:%u-%u %S"), _I2CAddress.toString(), (int)_firstVpin, 
     (int)_firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
 }
 
@@ -270,5 +275,5 @@ static void writeRegister(byte address, byte reg, byte value) {
 // The profile below is in the range 0-100% and should be combined with the desired limits
 // of the servo set by _activePosition and _inactivePosition.  The profile is symmetrical here,
 // i.e. the bounce is the same on the down action as on the up action.  First entry isn't used.
-const byte FLASH PCA9685::_bounceProfile[30] = 
+const uint8_t FLASH PCA9685::_bounceProfile[30] = 
     {0,2,3,7,13,33,50,83,100,83,75,70,65,60,60,65,74,84,100,83,75,70,70,72,75,80,87,92,97,100};

IO_PCA9685pwm.h

@@ -0,0 +1,170 @@
+/*
+ *  © 2023, Neil McKechnie. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/* 
+ * This driver performs the basic interface between the HAL and an 
+ * I2C-connected PCA9685 16-channel PWM module.  When requested, it 
+ * commands the device to set the PWM mark-to-period ratio accordingly.
+ * The call to IODevice::writeAnalogue(vpin, value) specifies the
+ * desired value in the range 0-4095 (0=0% and 4095=100%).
+ * 
+ * This driver can be used for simple servo control by writing values between
+ * about 102 and 450 (extremes of movement for 9g micro servos) or 150 to 250
+ * for a more restricted range (corresponding to 1.5ms to 2.5ms pulse length).
+ * A value of zero will switch off the servo.  To create the device, use
+ * the following syntax:
+ * 
+ * PCA9685_basic::create(vpin, npins, i2caddress);
+ * 
+ * For LED control, a value of 0 is fully off, and 4095 is fully on.  It is
+ * recommended, to reduce flicker of LEDs, that the frequency be configured
+ * to a value higher than the default of 50Hz.  To do this, create the device
+ * as follows, for a frequency of 200Hz.:
+ * 
+ * PCA9685_basic::create(vpin, npins, i2caddress, 200);
+ * 
+ */
+
+#ifndef PCA9685_BASIC_H
+#define PCA9685_BASIC_H
+
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+
+/*
+ * IODevice subclass for PCA9685 16-channel PWM module.
+ */
+ 
+class PCA9685pwm : public IODevice {
+public:
+  // Create device driver instance.
+  static void create(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint16_t frequency = 50) {
+    if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new PCA9685pwm(firstVpin, nPins, i2cAddress, frequency);
+  }
+
+private:
+  
+  // structures for setting up non-blocking writes to PWM controller
+  I2CRB requestBlock;
+  uint8_t outputBuffer[5];
+  uint16_t prescaler;
+
+  // REGISTER ADDRESSES
+  const uint8_t PCA9685_MODE1=0x00;      // Mode Register 
+  const uint8_t PCA9685_FIRST_SERVO=0x06;  /** low uint8_t first PWM register ON*/
+  const uint8_t PCA9685_PRESCALE=0xFE;     /** Prescale register for PWM output frequency */
+  // MODE1 bits
+  const uint8_t MODE1_SLEEP=0x10;   /**< Low power mode. Oscillator off */
+  const uint8_t MODE1_AI=0x20;      /**< Auto-Increment enabled */
+  const uint8_t MODE1_RESTART=0x80; /**< Restart enabled */
+
+  const uint32_t FREQUENCY_OSCILLATOR=25000000; /** Accurate enough for our purposes  */
+  const uint8_t PRESCALE_50HZ = (uint8_t)(((FREQUENCY_OSCILLATOR / (50.0 * 4096.0)) + 0.5) - 1);
+  const uint32_t MAX_I2C_SPEED = 1000000L; // PCA9685 rated up to 1MHz I2C clock speed
+
+  // Constructor
+  PCA9685pwm(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint16_t frequency) {
+    _firstVpin = firstVpin;
+    _nPins = (nPins>16) ? 16 : nPins;
+    _I2CAddress = i2cAddress;
+    if (frequency > 1526) frequency = 1526;
+    else if (frequency < 24) frequency = 24;
+    prescaler = FREQUENCY_OSCILLATOR / 4096 / frequency;
+    addDevice(this);
+
+    // Initialise structure used for setting pulse rate
+    requestBlock.setWriteParams(_I2CAddress, outputBuffer, sizeof(outputBuffer));
+  }
+
+  // Device-specific initialisation
+  void _begin() override {
+    I2CManager.begin();
+    I2CManager.setClock(1000000); // Nominally able to run up to 1MHz on I2C
+            // In reality, other devices including the Arduino will limit 
+            // the clock speed to a lower rate.
+
+    // Initialise I/O module here.
+    if (I2CManager.exists(_I2CAddress)) {
+      writeRegister(_I2CAddress, PCA9685_MODE1, MODE1_SLEEP | MODE1_AI);
+      writeRegister(_I2CAddress, PCA9685_PRESCALE, prescaler);
+      writeRegister(_I2CAddress, PCA9685_MODE1, MODE1_AI);
+      writeRegister(_I2CAddress, PCA9685_MODE1, MODE1_RESTART | MODE1_AI);
+      // In theory, we should wait 500us before sending any other commands to each device, to allow
+      // the PWM oscillator to get running.  However, we don't do any specific wait, as there's 
+      // plenty of other stuff to do before we will send a command.
+    #if defined(DIAG_IO)
+      _display();
+    #endif
+    } else
+      _deviceState = DEVSTATE_FAILED;
+  }
+
+  // Device-specific writeAnalogue function, invoked from IODevice::writeAnalogue().
+  //            
+  void _writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t param2) override {
+    (void)param1; (void)param2;  // suppress compiler warning
+    #ifdef DIAG_IO
+    DIAG(F("PCA9685pwm WriteAnalogue VPIN:%u Value:%d %S"), 
+      vpin, value, _deviceState == DEVSTATE_FAILED?F("DEVSTATE_FAILED"):F(""));
+    #endif
+    if (_deviceState == DEVSTATE_FAILED) return;
+    int pin = vpin - _firstVpin;
+    if (value > 4095) value = 4095;
+    else if (value < 0) value = 0;
+
+    writeDevice(pin, value);
+  }
+
+  // Display details of this device.
+  void _display() override {
+    DIAG(F("PCA9685pwm I2C:%s Configured on Vpins:%u-%u %S"), _I2CAddress.toString(), (int)_firstVpin, 
+      (int)_firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
+  }
+
+  // writeDevice (helper function) takes a pin in range 0 to _nPins-1 within the device, and a value
+  // between 0 and 4095 for the PWM mark-to-period ratio, with 4095 being 100%.
+  void writeDevice(uint8_t pin, int value) {
+    #ifdef DIAG_IO
+    DIAG(F("PCA9685pwm I2C:%s WriteDevice Pin:%d Value:%d"), _I2CAddress.toString(), pin, value);
+    #endif
+    // Wait for previous request to complete
+    uint8_t status = requestBlock.wait();
+    if (status != I2C_STATUS_OK) {
+      _deviceState = DEVSTATE_FAILED;
+      DIAG(F("PCA9685pwm I2C:%s failed %S"), _I2CAddress.toString(), I2CManager.getErrorMessage(status));
+    } else {
+      // Set up new request.
+      outputBuffer[0] = PCA9685_FIRST_SERVO + 4 * pin;
+      outputBuffer[1] = 0;
+      outputBuffer[2] = (value == 4095 ? 0x10 : 0);  // 4095=full on
+      outputBuffer[3] = value & 0xff;
+      outputBuffer[4] = value >> 8;
+      I2CManager.queueRequest(&requestBlock);
+    }
+  }
+
+  // Internal helper function for this device
+  static void writeRegister(I2CAddress address, uint8_t reg, uint8_t value) {
+    I2CManager.write(address, 2, reg, value);
+  }
+
+};
+
+#endif

IO_PCF8574.h

@@ -1,4 +1,5 @@
 /*
+ *  © 2022 Paul M Antoine
  *  © 2021, Neil McKechnie. All rights reserved.
  *  
  *  This file is part of DCC++EX API
@@ -42,20 +43,22 @@
 
 class PCF8574 : public GPIOBase<uint8_t> {
 public:
-  static void create(VPIN firstVpin, uint8_t nPins, uint8_t I2CAddress, int interruptPin=-1) {
-    new PCF8574(firstVpin, nPins, I2CAddress, interruptPin);
+  static void create(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) {
+    if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new PCF8574(firstVpin, nPins, i2cAddress, interruptPin);
   }
 
-  PCF8574(VPIN firstVpin, uint8_t nPins, uint8_t I2CAddress, int interruptPin=-1)
-    : GPIOBase<uint8_t>((FSH *)F("PCF8574"), firstVpin, min(nPins, 8), I2CAddress, interruptPin) 
+private:
+  PCF8574(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1)
+    : GPIOBase<uint8_t>((FSH *)F("PCF8574"), firstVpin, nPins, i2cAddress, interruptPin) 
   {
     requestBlock.setReadParams(_I2CAddress, inputBuffer, 1);
   }
   
-private:
-  // The pin state is '1' if the pin is an input or if it is an output set to 1.  Zero otherwise. 
+  // The PCF8574 handles inputs by applying a weak pull-up when output is driven to '1'.
+  // The pin state is driven '1' if the pin is an input, or if it is an output set to 1.
+  // Unused pins are driven '0'.
   void _writeGpioPort() override {
-    I2CManager.write(_I2CAddress, 1, _portOutputState | ~_portMode);
+    I2CManager.write(_I2CAddress, 1, (_portOutputState | ~_portMode) & _portInUse);
   }
 
   // The PCF8574 handles inputs by applying a weak pull-up when output is driven to '1'.
@@ -63,9 +66,8 @@ private:
   // and enable pull-up.
   void _writePullups() override { }
 
-  // The pin state is '1' if the pin is an input or if it is an output set to 1.  Zero otherwise. 
   void _writePortModes() override {
-    I2CManager.write(_I2CAddress, 1, _portOutputState | ~_portMode);
+    _writeGpioPort();
   }
 
   // In immediate mode, _readGpioPort reads the device GPIO port and updates _portInputState accordingly.
@@ -75,7 +77,7 @@ private:
     if (immediate) {
       uint8_t buffer[1];
       I2CManager.read(_I2CAddress, buffer, 1);
-      _portInputState = ((uint16_t)buffer) & 0xff;
+      _portInputState = buffer[0] | _portMode;
     } else {
       requestBlock.wait(); // Wait for preceding operation to complete
       // Issue new request to read GPIO register
@@ -86,7 +88,7 @@ private:
   // This function is invoked when an I/O operation on the requestBlock completes.
   void _processCompletion(uint8_t status) override {
     if (status == I2C_STATUS_OK) 
-      _portInputState = ((uint16_t)inputBuffer[0]) & 0xff;
+      _portInputState = inputBuffer[0] | _portMode;
     else  
       _portInputState = 0xff; 
   }
@@ -99,4 +101,4 @@ private:
   uint8_t inputBuffer[1];
 };
 
-#endif
+#endif

IO_PCF8575.h

@@ -0,0 +1,109 @@
+/*
+ *  © 2023, Paul Antoine, and Discord user @ADUBOURG
+ *  © 2021, Neil McKechnie. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/* 
+ * The PCF8575 is a simple device; it only has one register.  The device 
+ * input/output mode and pullup are configured through this, and the 
+ * output state is written and the input state read through it too.
+ * 
+ * This is accomplished by having a weak resistor in series with the output,
+ * and a read-back of the other end of the resistor.  As an output, the 
+ * pin state is set to 1 or 0, and the output voltage goes to +5V or 0V
+ * (through the weak resistor).
+ * 
+ * In order to use the pin as an input, the output is written as
+ * a '1' in order to pull up the resistor.  Therefore the input will be
+ * 1 unless the pin is pulled down externally, in which case it will be 0.
+ * 
+ * As a consequence of this approach, it is not possible to use the device for
+ * inputs without pullups.
+ */
+
+#ifndef IO_PCF8575_H
+#define IO_PCF8575_H
+
+#include "IO_GPIOBase.h"
+#include "FSH.h"
+
+class PCF8575 : public GPIOBase<uint16_t> {
+public:
+  static void create(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) {
+    if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new PCF8575(firstVpin, nPins, i2cAddress, interruptPin);
+  }
+
+private:
+  PCF8575(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1)
+    : GPIOBase<uint16_t>((FSH *)F("PCF8575"), firstVpin, nPins, i2cAddress, interruptPin)
+  {
+    requestBlock.setReadParams(_I2CAddress, inputBuffer, sizeof(inputBuffer));
+  }
+  
+  // The PCF8575 handles inputs by applying a weak pull-up when output is driven to '1'.
+  // The pin state is driven '1' if the pin is an input, or if it is an output set to 1.
+  // Unused pins are driven '0'.
+  void _writeGpioPort() override {
+    uint16_t bits = (_portOutputState | ~_portMode) & _portInUse;
+    I2CManager.write(_I2CAddress, 2, bits, bits>>8);
+  }
+
+  // The PCF8575 handles inputs by applying a weak pull-up when output is driven to '1'.
+  // Therefore, writing '1' in _writePortModes is enough to set the module to input mode 
+  // and enable pull-up.
+  void _writePullups() override { }
+
+  // The pin state is '1' if the pin is an input or if it is an output set to 1.  Zero otherwise. 
+  void _writePortModes() override {
+    _writeGpioPort();
+  }
+
+  // In immediate mode, _readGpioPort reads the device GPIO port and updates _portInputState accordingly.
+  //  When not in immediate mode, it initiates a request using the request block and returns.
+  //  When the request completes, _processCompletion finishes the operation.
+  void _readGpioPort(bool immediate) override {
+    if (immediate) {
+      uint8_t buffer[2];
+      I2CManager.read(_I2CAddress, buffer, 2);
+      _portInputState = (((uint16_t)buffer[1]<<8) | buffer[0]) | _portMode;
+    } else {
+      requestBlock.wait(); // Wait for preceding operation to complete
+      // Issue new request to read GPIO register
+      I2CManager.queueRequest(&requestBlock);
+    }
+  }
+
+  // This function is invoked when an I/O operation on the requestBlock completes.
+  void _processCompletion(uint8_t status) override {
+    if (status == I2C_STATUS_OK) 
+      _portInputState = (((uint16_t)inputBuffer[1]<<8) | inputBuffer[0]) | _portMode;
+    else  
+      _portInputState = 0xffff;
+  }
+
+  // Set up device ports
+  void _setupDevice() override { 
+    _writePortModes();
+    _writeGpioPort();
+    _writePullups();
+  }
+ 
+  uint8_t inputBuffer[2];
+};
+
+#endif

IO_RotaryEncoder.h

@@ -0,0 +1,192 @@
+/*
+ *  © 2023, Peter Cole. All rights reserved.
+ *  © 2022, Peter Cole. All rights reserved.
+ *
+ *  This file is part of EX-CommandStation
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+/*
+* The IO_RotaryEncoder device driver is used to receive positions from a rotary encoder connected to an Arduino via I2C.
+*
+* There is separate code required for the Arduino the rotary encoder is connected to, which is located here:
+* https://github.com/peteGSX-Projects/dcc-ex-rotary-encoder
+*
+* This device driver receives the rotary encoder position when the rotary encoder button is pushed, and these positions
+* can be tested in EX-RAIL with:
+* ONCHANGE(vpin) - flag when the rotary encoder position has changed from the previous position
+* IFRE(vpin, position) - test to see if specified rotary encoder position has been received
+*
+* Feedback can also be sent to the rotary encoder by using 2 Vpins, and sending a SET()/RESET() to the second Vpin.
+* A SET(vpin) will flag that a turntable (or anything else) is in motion, and a RESET(vpin) that the motion has finished.
+*
+* In addition, defining a third Vpin will allow a position number to be sent so that when an EXRAIL automation or some other
+* activity has moved a turntable, the position can be reflected in the rotary encoder software. This can be accomplished
+* using the EXRAIL SERVO(vpin, position, profile) command, where:
+* - vpin = the third defined Vpin (any other is ignored)
+* - position = the defined position in the DCC-EX Rotary Encoder software, 0 (Home) to 255
+* - profile = Must be defined as per the SERVO() command, but is ignored as it has no relevance
+*
+* Defining in myAutomation.h requires the device driver to be included in addition to the HAL() statement. Examples:
+*
+* #include "IO_RotaryEncoder.h"
+* HAL(RotaryEncoder, 700, 1, 0x67)    // Define single Vpin, no feedback or position sent to rotary encoder software
+* HAL(RotaryEncoder, 700, 2, 0x67)    // Define two Vpins, feedback only sent to rotary encoder software
+* HAL(RotaryEncoder, 700, 3, 0x67)    // Define three Vpins, can send feedback and position update to rotary encoder software
+*
+* Refer to the documentation for further information including the valid activities and examples.
+*/
+
+#ifndef IO_ROTARYENCODER_H
+#define IO_ROTARYENCODER_H
+
+#include "EXRAIL2.h"
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+
+class RotaryEncoder : public IODevice {
+public:
+  
+  static void create(VPIN firstVpin, int nPins, I2CAddress i2cAddress) {
+    if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new RotaryEncoder(firstVpin, nPins, i2cAddress);
+  }
+
+private:
+  // Constructor
+  RotaryEncoder(VPIN firstVpin, int nPins, I2CAddress i2cAddress){
+    _firstVpin = firstVpin;
+    _nPins = nPins;
+    if (_nPins > 3) {
+      _nPins = 3;
+      DIAG(F("RotaryEncoder WARNING:%d vpins defined, only 3 supported"), _nPins);
+    }
+    _I2CAddress = i2cAddress;
+    addDevice(this);
+  }
+
+  // Initiate the device
+  void _begin() {
+    uint8_t _status;
+    // Attempt to initilalise device
+    I2CManager.begin();
+    if (I2CManager.exists(_I2CAddress)) {
+      // Send RE_RDY, must receive RE_RDY to be online
+      _sendBuffer[0] = RE_RDY;
+      _status = I2CManager.read(_I2CAddress, _rcvBuffer, 1, _sendBuffer, 1);
+      if (_status == I2C_STATUS_OK) {
+        if (_rcvBuffer[0] == RE_RDY) {
+          _sendBuffer[0] = RE_VER;
+          if (I2CManager.read(_I2CAddress, _versionBuffer, 3, _sendBuffer, 1) == I2C_STATUS_OK) {
+            _majorVer = _versionBuffer[0];
+            _minorVer = _versionBuffer[1];
+            _patchVer = _versionBuffer[2];
+          }
+        } else {
+          DIAG(F("RotaryEncoder I2C:%s garbage received: %d"), _I2CAddress.toString(), _rcvBuffer[0]);
+          _deviceState = DEVSTATE_FAILED;
+          return;
+        }
+      } else {
+        DIAG(F("RotaryEncoder I2C:%s ERROR connecting"), _I2CAddress.toString());
+        _deviceState = DEVSTATE_FAILED;
+        return;
+      }
+#ifdef DIAG_IO
+      _display();
+#endif
+    } else {
+      DIAG(F("RotaryEncoder I2C:%s device not found"), _I2CAddress.toString());
+      _deviceState = DEVSTATE_FAILED;
+    }
+  }
+
+  void _loop(unsigned long currentMicros) override {
+    if (_deviceState == DEVSTATE_FAILED) return;  // Return if device has failed
+    if (_i2crb.isBusy()) return;                  // Return if I2C operation still in progress
+
+    if (currentMicros - _lastPositionRead > _positionRefresh) {
+      _lastPositionRead = currentMicros;
+      _sendBuffer[0] = RE_READ;
+      I2CManager.read(_I2CAddress, _rcvBuffer, 1, _sendBuffer, 1, &_i2crb); // Read position from encoder
+      _position = _rcvBuffer[0];
+      // If EXRAIL is active, we need to trigger the ONCHANGE() event handler if it's in use
+#if defined(EXRAIL_ACTIVE)
+      if (_position != _previousPosition) {
+        _previousPosition = _position;
+        RMFT2::changeEvent(_firstVpin, 1);
+      } else {
+        RMFT2::changeEvent(_firstVpin, 0);
+      }
+#endif
+    }
+  }
+
+  // Return the position sent by the rotary encoder software
+  int _readAnalogue(VPIN vpin) override {
+    if (_deviceState == DEVSTATE_FAILED) return 0;
+    return _position;
+  }
+
+  // Send the feedback value to the rotary encoder software
+  void _write(VPIN vpin, int value) override {
+    if (vpin == _firstVpin + 1) {
+      if (value != 0) value = 0x01;
+      byte _feedbackBuffer[2] = {RE_OP, (byte)value};
+      I2CManager.write(_I2CAddress, _feedbackBuffer, 2);
+    }
+  }
+
+  // Send a position update to the rotary encoder software
+  // To be valid, must be 0 to 255, and different to the current position
+  // If the current position is the same, it was initiated by the rotary encoder
+  void _writeAnalogue(VPIN vpin, int position, uint8_t profile, uint16_t duration) override {
+    if (vpin == _firstVpin + 2) {
+      if (position >= 0 && position <= 255 && position != _position) {
+        byte newPosition = position & 0xFF;
+        byte _positionBuffer[2] = {RE_MOVE, newPosition};
+        I2CManager.write(_I2CAddress, _positionBuffer, 2);
+      }
+    }
+  }
+  
+  void _display() override {
+    DIAG(F("Rotary Encoder I2C:%s v%d.%d.%d Configured on VPIN:%u-%d %S"), _I2CAddress.toString(), _majorVer, _minorVer, _patchVer,
+      (int)_firstVpin, _firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
+  }
+
+  int8_t _position;
+  int8_t _previousPosition = 0;
+  uint8_t _versionBuffer[3];
+  uint8_t _sendBuffer[1];
+  uint8_t _rcvBuffer[1];
+  uint8_t _majorVer = 0;
+  uint8_t _minorVer = 0;
+  uint8_t _patchVer = 0;
+  I2CRB _i2crb;
+  unsigned long _lastPositionRead = 0;
+  const unsigned long _positionRefresh = 100000UL;    // Delay refreshing position for 100ms
+
+  enum {
+    RE_RDY = 0xA0,   // Flag to check if encoder is ready for operation
+    RE_VER = 0xA1,   // Flag to retrieve rotary encoder software version
+    RE_READ = 0xA2,  // Flag to read the current position of the encoder
+    RE_OP = 0xA3,    // Flag for operation start/end, sent to when sending feedback on move start/end
+    RE_MOVE = 0xA4,  // Flag for sending a position update from the device driver to the encoder
+  };
+
+};
+
+#endif

IO_Servo.cpp

@@ -0,0 +1,32 @@
+/*
+ *  © 2023, Neil McKechnie. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#include "IO_Servo.h"
+#include "FSH.h"
+
+// Profile for a bouncing signal or turnout
+// The profile below is in the range 0-100% and should be combined with the desired limits
+// of the servo set by _activePosition and _inactivePosition.  The profile is symmetrical here,
+// i.e. the bounce is the same on the down action as on the up action.  First entry isn't used.
+//
+// Note: This has been put into its own .CPP file to ensure that duplicates aren't created
+// if the IO_Servo.h library is #include'd in multiple source files.
+//
+const uint8_t FLASH Servo::_bounceProfile[30] = 
+    {0,2,3,7,13,33,50,83,100,83,75,70,65,60,60,65,74,84,100,83,75,70,70,72,75,80,87,92,97,100};

IO_Servo.h

@@ -0,0 +1,298 @@
+/*
+ *  © 2023, Neil McKechnie. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/*
+ * This device is a layered device which is designed to sit on top of another
+ * device.  The underlying device class is expected to accept writeAnalogue calls 
+ * which will normally cause some physical movement of something.  The device may be a servo, 
+ * a motor or some other kind of positioner, and the something might be a turnout,
+ * a semaphore signal or something else.  One user has used this capability for
+ * moving a figure along the platform on their layout!
+ * 
+ * Example of use:
+ *    In myHal.cpp, 
+ * 
+ * #include "IO_Servo.h"
+ * ...
+ * PCA9685::create(100,16,0x40);   // First create the hardware interface device
+ * Servo::create(300,16,100);    // Then create the higher level device which 
+ *                               // references pins 100-115 or a subset of them.
+ * 
+ * Then any reference to pins 300-315 will cause the servo driver to send output
+ * PWM commands to the corresponding PCA9685 driver pins 100-115.  The PCA9685 driver may
+ * be substituted with any other driver which provides analogue output 
+ * capability, e.g. EX-IOExpander devices, as long as they are capable of interpreting 
+ * the writeAnalogue() function calls.
+ */
+
+#include "IODevice.h"
+
+#ifndef IO_SERVO_H
+#define IO_SERVO_H
+
+#include "I2CManager.h"
+#include "DIAG.h"
+
+class Servo : IODevice {
+
+public: 
+  enum ProfileType : uint8_t {
+    Instant = 0,  // Moves immediately between positions (if duration not specified)
+    UseDuration = 0, // Use specified duration
+    Fast = 1,     // Takes around 500ms end-to-end
+    Medium = 2,   // 1 second end-to-end
+    Slow = 3,     // 2 seconds end-to-end
+    Bounce = 4,   // For semaphores/turnouts with a bit of bounce!!
+    NoPowerOff = 0x80, // Flag to be ORed in to suppress power off after move.
+  };
+
+  // Create device driver instance.
+  static void create(VPIN firstVpin, int nPins, VPIN firstSlavePin=VPIN_NONE) {
+    new Servo(firstVpin, nPins, firstSlavePin);
+  }
+
+private:
+  VPIN _firstSlavePin;
+  IODevice *_slaveDevice = NULL;
+
+  struct ServoData {
+    uint16_t activePosition : 12; // Config parameter
+    uint16_t inactivePosition : 12; // Config parameter
+    uint16_t currentPosition : 12;
+    uint16_t fromPosition : 12;
+    uint16_t toPosition : 12; 
+    uint8_t profile;  // Config parameter
+    uint16_t stepNumber; // Index of current step (starting from 0)
+    uint16_t numSteps;  // Number of steps in animation, or 0 if none in progress.
+    uint8_t currentProfile; // profile being used for current animation.
+    uint16_t duration; // time (tenths of a second) for animation to complete.
+  }; // 14 bytes per element, i.e. per pin in use
+  
+  struct ServoData *_servoData [16];
+
+  static const uint8_t _catchupSteps = 5; // number of steps to wait before switching servo off
+  static const uint8_t FLASH _bounceProfile[30];
+
+  const unsigned int refreshInterval = 50; // refresh every 50ms
+
+
+  // Configure a port on the Servo.
+  bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) {
+    if (_deviceState == DEVSTATE_FAILED) return false;
+    if (configType != CONFIGURE_SERVO) return false;
+    if (paramCount != 5) return false;
+    #ifdef DIAG_IO
+    DIAG(F("Servo: Configure VPIN:%u Apos:%d Ipos:%d Profile:%d Duration:%d state:%d"), 
+      vpin, params[0], params[1], params[2], params[3], params[4]);
+    #endif
+
+    int8_t pin = vpin - _firstVpin;
+    struct ServoData *s = _servoData[pin];
+    if (s == NULL) { 
+      _servoData[pin] = (struct ServoData *)calloc(1, sizeof(struct ServoData));
+      s = _servoData[pin];
+      if (!s) return false; // Check for failed memory allocation
+    }
+
+    s->activePosition = params[0];
+    s->inactivePosition = params[1];
+    s->profile = params[2];
+    s->duration = params[3];
+    int state = params[4];
+
+    if (state != -1) {
+      // Position servo to initial state
+      writeAnalogue(vpin, state ? s->activePosition : s->inactivePosition);
+    } 
+    return true;
+  }
+
+  // Constructor
+  Servo(VPIN firstVpin, int nPins, VPIN firstSlavePin = VPIN_NONE) {
+    _firstVpin = firstVpin;
+    _nPins = (nPins > 16) ? 16 : nPins;
+    if (firstSlavePin == VPIN_NONE)
+      _firstSlavePin = firstVpin;
+    else
+      _firstSlavePin = firstSlavePin;
+
+    // To save RAM, space for servo configuration is not allocated unless a pin is used.
+    // Initialise the pointers to NULL.
+    for (int i=0; i<_nPins; i++)
+      _servoData[i] = NULL;
+
+    // Get reference to slave device.
+    _slaveDevice = findDevice(_firstSlavePin);
+    if (!_slaveDevice) {
+      DIAG(F("Servo: Slave device not found on Vpins %u-%u"), 
+        _firstSlavePin, _firstSlavePin+_nPins-1);
+      _deviceState = DEVSTATE_FAILED;
+    }      
+    if (_slaveDevice != findDevice(_firstSlavePin+_nPins-1)) {
+      DIAG(F("Servo: Slave device does not cover all Vpins %u-%u"), 
+        _firstSlavePin, _firstSlavePin+_nPins-1);
+      _deviceState = DEVSTATE_FAILED;
+    }
+
+    addDevice(this, _slaveDevice); // Link device ahead of slave device to intercept requests
+  }
+
+  // Device-specific initialisation
+  void _begin() override {
+    #if defined(DIAG_IO)
+    _display();
+    #endif
+  }
+
+  // Device-specific write function, invoked from IODevice::write().  
+  // For this function, the configured profile is used.
+  void _write(VPIN vpin, int value) override {
+    if (_deviceState == DEVSTATE_FAILED) return;
+    #ifdef DIAG_IO
+    DIAG(F("Servo Write VPIN:%u Value:%d"), vpin, value);
+    #endif
+    int pin = vpin - _firstVpin;
+    if (value) value = 1;
+
+    struct ServoData *s = _servoData[pin];
+    if (s != NULL) {
+      // Use configured parameters
+      writeAnalogue(vpin, value ? s->activePosition : s->inactivePosition, s->profile, s->duration);
+    }  else {
+      /* simulate digital pin on PWM */
+      writeAnalogue(vpin, value ? 4095 : 0, Instant | NoPowerOff, 0);     
+    }
+  }
+
+  // Device-specific writeAnalogue function, invoked from IODevice::writeAnalogue().
+  // Profile is as follows:
+  //  Bit 7:     0=Set output to 0% to power off servo motor when finished
+  //             1=Keep output at final position (better with LEDs, which will stay lit)
+  //  Bits 6-0:  0           Use specified duration (defaults to 0 deciseconds)
+  //             1 (Fast)    Move servo in 0.5 seconds
+  //             2 (Medium)  Move servo in 1.0 seconds
+  //             3 (Slow)    Move servo in 2.0 seconds
+  //             4 (Bounce)  Servo 'bounces' at extremes.
+  // Duration is in deciseconds (tenths of a second) and defaults to 0.  
+  //            
+  void _writeAnalogue(VPIN vpin, int value, uint8_t profile, uint16_t duration) override {
+    #ifdef DIAG_IO
+    DIAG(F("Servo: WriteAnalogue VPIN:%u Value:%d Profile:%d Duration:%d %S"), 
+      vpin, value, profile, duration, _deviceState == DEVSTATE_FAILED?F("DEVSTATE_FAILED"):F(""));
+    #endif
+    if (_deviceState == DEVSTATE_FAILED) return;
+    int pin = vpin - _firstVpin;
+    if (value > 4095) value = 4095;
+    else if (value < 0) value = 0;
+
+    struct ServoData *s = _servoData[pin];
+    if (s == NULL) {
+      // Servo pin not configured, so configure now using defaults
+      s = _servoData[pin] = (struct ServoData *) calloc(sizeof(struct ServoData), 1);
+      if (s == NULL) return;  // Check for memory allocation failure
+      s->activePosition = 4095;
+      s->inactivePosition = 0;
+      s->currentPosition = value;
+      s->profile = Instant | NoPowerOff;  // Use instant profile (but not this time)
+    }
+
+    // Animated profile.  Initiate the appropriate action.
+    s->currentProfile = profile;
+    uint8_t profileValue = profile & ~NoPowerOff;  // Mask off 'don't-power-off' bit.
+    s->numSteps = profileValue==Fast ? 10 :   // 0.5 seconds
+                  profileValue==Medium ? 20 : // 1.0 seconds
+                  profileValue==Slow ? 40 :   // 2.0 seconds
+                  profileValue==Bounce ? sizeof(_bounceProfile)-1 : // ~ 1.5 seconds
+                  duration * 2 + 1; // Convert from deciseconds (100ms) to refresh cycles (50ms)
+    s->stepNumber = 0;
+    s->toPosition = value;
+    s->fromPosition = s->currentPosition;
+  }
+
+  // _read returns true if the device is currently in executing an animation, 
+  //  changing the output over a period of time.
+  int _read(VPIN vpin) override {
+    if (_deviceState == DEVSTATE_FAILED) return 0;
+    int pin = vpin - _firstVpin;
+    struct ServoData *s = _servoData[pin];
+    if (s == NULL) 
+      return false; // No structure means no animation!
+    else
+      return (s->stepNumber < s->numSteps);
+  }
+
+  void _loop(unsigned long currentMicros) override {
+    if (_deviceState == DEVSTATE_FAILED) return;
+    for (int pin=0; pin<_nPins; pin++) {
+      updatePosition(pin);
+    }
+    delayUntil(currentMicros + refreshInterval * 1000UL);
+  }
+
+  // Private function to reposition servo
+  // TODO: Could calculate step number from elapsed time, to allow for erratic loop timing.
+  void updatePosition(uint8_t pin) {
+    struct ServoData *s = _servoData[pin];
+    if (s == NULL) return; // No pin configuration/state data
+
+    if (s->numSteps == 0) return; // No animation in progress
+
+    if (s->stepNumber == 0 && s->fromPosition == s->toPosition) {
+      // Go straight to end of sequence, output final position.
+      s->stepNumber = s->numSteps-1;
+    }
+
+    if (s->stepNumber < s->numSteps) {
+      // Animation in progress, reposition servo
+      s->stepNumber++;
+      if ((s->currentProfile & ~NoPowerOff) == Bounce) {
+        // Retrieve step positions from array in flash
+        uint8_t profileValue = GETFLASH(&_bounceProfile[s->stepNumber]);
+        s->currentPosition = map(profileValue, 0, 100, s->fromPosition, s->toPosition);
+      } else {
+        // All other profiles - calculate step by linear interpolation between from and to positions.
+        s->currentPosition = map(s->stepNumber, 0, s->numSteps, s->fromPosition, s->toPosition);
+      }
+      // Send servo command to output driver
+      _slaveDevice->_writeAnalogue(_firstSlavePin+pin, s->currentPosition);
+    } else if (s->stepNumber < s->numSteps + _catchupSteps) {
+      // We've finished animation, wait a little to allow servo to catch up
+      s->stepNumber++;
+    } else if (s->stepNumber == s->numSteps + _catchupSteps 
+              && s->currentPosition != 0) {
+  #ifdef IO_SWITCH_OFF_SERVO
+      if ((s->currentProfile & NoPowerOff) == 0) {
+        // Wait has finished, so switch off output driver to avoid servo buzz.
+        _slaveDevice->_writeAnalogue(_firstSlavePin+pin, 0);
+      }
+  #endif
+      s->numSteps = 0;  // Done now.
+    }
+  }
+
+  // Display details of this device.
+  void _display() override {
+    DIAG(F("Servo Configured on Vpins:%u-%u, slave pins:%d-%d %S"),
+      (int)_firstVpin, (int)_firstVpin+_nPins-1,
+      (int)_firstSlavePin, (int)_firstSlavePin+_nPins-1,
+      (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
+  }
+};
+
+#endif

IO_TCA8418.h

@@ -0,0 +1,371 @@
+/*
+ *  © 2023-2024, Paul M. Antoine
+ *  © 2021, Neil McKechnie. All rights reserved.
+ *  
+ *  This file is part of DCC-EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef io_tca8418_h
+#define io_tca8418_h
+
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+#include "FSH.h"
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////
+/*
+ * IODevice subclass for TCA8418 80-key keypad encoder, which we'll treat as 80 available VPINs where
+ * key down == 1 and key up == 0 by configuring just as an 8x10 keyboard matrix. Users can opt to use
+ * up to all 80 of the available VPINs for now, allowing memory to be saved if not all events are required.
+ * 
+ * The datasheet says:
+ * 
+ * The TCA8418 can be configured to support many different configurations of keypad setups.
+ * All 18 GPIOs for the rows and columns can be used to support up to 80 keys in an 8x10 key pad
+ * array. Another option is that all 18 GPIOs be used for GPIs to read 18 buttons which are
+ * not connected in an array. Any combination in between is also acceptable (for example, a
+ * 3x4 keypad matrix and using the remaining 11 GPIOs as a combination of inputs and outputs).
+ * 
+ * With an 8x10 key event matrix, the events are numbered as such:
+ * 
+ *     C0  C1  C2  C3  C4  C5  C6  C7  C8  C9
+ *    ========================================
+ * R0|  0   1   2   3   4   5   6   7   8   9
+ * R1| 10  11  12  13  14  15  16  17  18  19
+ * R2| 20  21  22  23  24  25  26  27  28  29
+ * R3| 30  31  32  33  34  35  36  37  38  39
+ * R4| 40  41  42  43  44  45  46  47  48  49
+ * R5| 50  51  52  53  54  55  56  57  58  59
+ * R6| 60  61  62  63  64  65  66  67  68  69
+ * R7| 70  71  72  73  74  75  76  77  78  79
+ * 
+ * So if you start with VPIN 300, R0/C0 will be 300, and R7/C9 will be 379.
+ * 
+ * HAL declaration for myAutomation.h is:
+ * HAL(TCA8418, firstVpin, numPins, I2CAddress, interruptPin)
+ * 
+ * Where numPins can be 1-80, and interruptPin can be any spare Arduino pin.
+ * 
+ * Configure using the following on the main I2C bus:
+ * HAL(TCA8418, 300, 80, 0x34)
+ * 
+ * Use something like this on a multiplexor, and with up to 8 of the 8-way multiplexors you could have 64 different TCA8418 boards:
+ * HAL(TCA8418, 400, 80, {SubBus_1, 0x34})
+ * 
+ * And if needing an Interrupt pin to speed up operations:
+ * HAL(TCA8418, 300, 80, 0x34, D21)
+ * 
+ * Note that using an interrupt pin speeds up button press acquisition considerably (less than a millisecond vs 10-100),
+ * but even with interrupts enabled the code presently checks every 100ms in case the interrupt pin becomes disconnected.
+ * Use any available Arduino pin for interrupt monitoring.
+ */
+ 
+class TCA8418 : public IODevice {
+public:
+
+  static void create(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) {
+    if (checkNoOverlap(firstVpin, nPins, i2cAddress))
+      new TCA8418(firstVpin, (nPins = (nPins > 80) ? 80 : nPins), i2cAddress, interruptPin);
+  }
+
+private:  
+
+  uint8_t* _digitalInputStates = NULL;  // Array of pin states
+  uint8_t _digitalPinBytes = 0;         // Number of bytes in pin state array
+
+  uint8_t _numKeyEvents = 0;            // Number of outsanding key events waiting for us
+
+  unsigned long _lastEventRead = 0;
+  unsigned long _eventRefresh = 10000UL;    // Delay refreshing events for 10ms
+  const unsigned long _eventRefreshSlow = 100000UL;   // Delay refreshing events for 100ms
+  bool _gpioInterruptsEnabled = false;
+
+  uint8_t _inputBuffer[1];
+  uint8_t _commandBuffer[1];
+  I2CRB _i2crb;
+
+  enum {RDS_IDLE, RDS_EVENT, RDS_KEYCODE};  // Read operation states
+  uint8_t _readState = RDS_IDLE;
+
+  // Constructor
+  TCA8418(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) {
+    if (nPins > 0)
+    {
+      _firstVpin = firstVpin;
+      _nPins = nPins;
+      _I2CAddress = i2cAddress;
+      _gpioInterruptPin = interruptPin;
+      addDevice(this);
+    }
+  }
+
+  void _begin() {
+
+    I2CManager.begin();
+
+    if (I2CManager.exists(_I2CAddress)) {
+      // Default all GPIO pins to INPUT
+      I2CManager.write(_I2CAddress, 2, REG_GPIO_DIR_1, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_GPIO_DIR_2, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_GPIO_DIR_3, 0x00);
+
+      // Remove all GPIO pins from events
+      I2CManager.write(_I2CAddress, 2, REG_GPI_EM_1, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_GPI_EM_2, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_GPI_EM_3, 0x00);
+
+      // Set all pins to FALLING interrupts
+      I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_LVL_1, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_LVL_2, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_LVL_3, 0x00);
+
+      // Remove all GPIO pins from interrupts
+      I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_EN_1, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_EN_2, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_EN_3, 0x00);
+
+      // Set up an 8 x 10 matrix by writing 0xFF to all the row and column configs
+      // Row config is maximum of 8, and in REG_KP_GPIO_1
+      I2CManager.write(_I2CAddress, 2, REG_KP_GPIO_1, 0xFF);
+      // Column config is maximum of 10, lower 8 bits in REG_KP_GPIO_2, upper in REG_KP_GPIO_3
+      // Set first 8 columns
+      I2CManager.write(_I2CAddress, 2, REG_KP_GPIO_2, 0xFF);
+      // Turn on cols 9/10
+      I2CManager.write(_I2CAddress, 2, REG_KP_GPIO_3, 0x03);
+
+      // // Set all pins to Enable Debounce
+      I2CManager.write(_I2CAddress, 2, REG_DEBOUNCE_DIS_1, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_DEBOUNCE_DIS_2, 0x00);
+      I2CManager.write(_I2CAddress, 2, REG_DEBOUNCE_DIS_3, 0x00);
+
+      // Let's assume an 8x10 matrix for now, and configure 
+      _digitalPinBytes = (_nPins + 7) / 8;
+      if ((_digitalInputStates = (byte *)calloc(_digitalPinBytes, 1)) == NULL) {
+        DIAG(F("TCA8418 I2C: Unable to alloc %d bytes"), _digitalPinBytes);
+        return;
+      }
+
+    // Configure pin used for GPIO extender notification of change (if allocated)
+    // and configure TCA8418 to produce key event interrupts
+    if (_gpioInterruptPin >= 0) {
+      DIAG(F("TCA8418 I2C: interrupt pin configured on %d"), _gpioInterruptPin);
+      _gpioInterruptsEnabled = true;
+      _eventRefresh = _eventRefreshSlow; // Switch to slower manual refreshes in case the INT pin isn't connected!
+      pinMode(_gpioInterruptPin, INPUT_PULLUP);
+      I2CManager.write(_I2CAddress, 2, REG_CFG, REG_CFG_KE_IEN);
+      // Clear any pending interrupts
+      I2CManager.write(_I2CAddress, 2, REG_INT_STAT, REG_STAT_K_INT);
+    }
+
+#ifdef DIAG_IO
+      _display();
+#endif
+    }
+  }
+
+  int _read(VPIN vpin) override {
+    if (_deviceState == DEVSTATE_FAILED)
+      return 0;
+    int pin = vpin - _firstVpin;
+    bool result = _digitalInputStates[pin / 8] & (1 << (pin % 8));
+    return result;
+  }
+
+
+  // Main loop, collect both digital and analogue pin states continuously (faster sensor/input reads)
+  void _loop(unsigned long currentMicros) override {
+    if (_deviceState == DEVSTATE_FAILED) return;    // If device failed, return
+
+    // Request block is used for key event reads from the TCA8418, which are performed
+    // on a cyclic basis.
+
+    if (_readState != RDS_IDLE) {
+      if (_i2crb.isBusy()) return;                // If I2C operation still in progress, return
+
+      uint8_t status = _i2crb.status;
+      if (status == I2C_STATUS_OK) {             // If device request ok, read input data
+
+        // First check if we have any key events waiting
+        if (_readState == RDS_EVENT) {
+          if ((_numKeyEvents = (_inputBuffer[0] & 0x0F)) != 0) {
+            // We could read each key event waiting in a synchronous loop, which may prove preferable
+            // but for now, schedule an async read of the first key event in the queue
+            _commandBuffer[0] = REG_KEY_EVENT_A;
+            I2CManager.read(_I2CAddress, _inputBuffer, 1, _commandBuffer, 1, &_i2crb);  // non-blocking read
+            _readState = RDS_KEYCODE; // Shift to reading key events!
+          }
+          else // We found no key events waiting, return to IDLE
+            _readState = RDS_IDLE;
+        }
+         else {
+          // RDS_KEYCODE
+          uint8_t key = _inputBuffer[0] & 0x7F;
+          bool keyDown = _inputBuffer[0] & 0x80;
+          // Check for just keypad events
+          key--; // R0/C0 is key #1, so subtract 1 to create an array offset
+          // We only want to record key events we're configured for, as we have calloc'd an
+          // appropriately sized _digitalInputStates array!
+          if (key < _nPins) {
+            if (keyDown)
+              _digitalInputStates[key / 8] |= (1 << (key % 8));
+            else
+              _digitalInputStates[key / 8] &= ~(1 << (key % 8));
+          }
+          else
+            DIAG(F("TCA8418 I2C: key event %d discarded, outside Vpin range"), key);
+          _numKeyEvents--; // One less key event to get
+          if (_numKeyEvents != 0)
+          {
+            // DIAG(F("TCA8418 I2C: more keys in read event queue, # waiting is: %x"), _numKeyEvents);
+            // We could read each key event waiting in a synchronous loop, which may prove preferable
+            // but for now, schedule an async read of the first key event in the queue
+            _commandBuffer[0] = REG_KEY_EVENT_A;
+            I2CManager.read(_I2CAddress, _inputBuffer, 1, _commandBuffer, 1, &_i2crb); // non-blocking read
+          }
+          else {
+            // DIAG(F("TCA8418 I2C: no more keys in read event queue"));
+            // Clear any pending interrupts
+            I2CManager.write(_I2CAddress, 2, REG_INT_STAT, REG_STAT_K_INT);
+            _readState = RDS_IDLE; // Shift to IDLE
+            return;
+          }
+         }
+      } else
+        reportError(status, false);   // report eror but don't go offline.
+    }
+
+    // If we're not doing anything now, check to see if we have an interrupt pin configured and it is low,
+    // or if our timer has elapsed and we should check anyway in case the interrupt pin is disconnected.
+    if (_readState == RDS_IDLE) {
+      if ((_gpioInterruptsEnabled && !digitalRead(_gpioInterruptPin)) ||
+        ((currentMicros - _lastEventRead) > _eventRefresh))
+      {
+        _commandBuffer[0] = REG_KEY_LCK_EC;
+        I2CManager.read(_I2CAddress, _inputBuffer, 1, _commandBuffer, 1, &_i2crb);  // non-blocking read
+        _lastEventRead = currentMicros;
+        _readState = RDS_EVENT; // Shift to looking for key events!
+      }
+    }
+  }
+
+  // Display device information and status
+  void _display() override {
+    DIAG(F("TCA8418 I2C:%s Vpins %u-%u%S"),
+              _I2CAddress.toString(),
+              _firstVpin, (_firstVpin+_nPins-1),
+              _deviceState == DEVSTATE_FAILED ? F(" OFFLINE") : F(""));
+    if (_gpioInterruptsEnabled)
+      DIAG(F("TCA8418 I2C:Interrupt on pin %d"), _gpioInterruptPin);
+  }
+
+  // Helper function for error handling
+  void reportError(uint8_t status, bool fail=true) {
+    DIAG(F("TCA8418 I2C:%s Error:%d (%S)"), _I2CAddress.toString(), 
+      status, I2CManager.getErrorMessage(status));
+    if (fail)
+    _deviceState = DEVSTATE_FAILED;
+  }
+
+  enum tca8418_registers
+  {
+    // REG_RESERVED = 0x00
+    REG_CFG = 0x01,             // Configuration register
+    REG_INT_STAT = 0x02,        // Interrupt status
+    REG_KEY_LCK_EC = 0x03,      // Key lock and event counter
+    REG_KEY_EVENT_A = 0x04,     // Key event register A
+    REG_KEY_EVENT_B = 0x05,     // Key event register B
+    REG_KEY_EVENT_C = 0x06,     // Key event register C
+    REG_KEY_EVENT_D = 0x07,     // Key event register D
+    REG_KEY_EVENT_E = 0x08,     // Key event register E
+    REG_KEY_EVENT_F = 0x09,     // Key event register F
+    REG_KEY_EVENT_G = 0x0A,     // Key event register G
+    REG_KEY_EVENT_H = 0x0B,     // Key event register H
+    REG_KEY_EVENT_I = 0x0C,     // Key event register I
+    REG_KEY_EVENT_J = 0x0D,     // Key event register J
+    REG_KP_LCK_TIMER = 0x0E,    // Keypad lock1 to lock2 timer
+    REG_UNLOCK_1 = 0x0F,        // Unlock register 1
+    REG_UNLOCK_2 = 0x10,        // Unlock register 2
+    REG_GPIO_INT_STAT_1 = 0x11, // GPIO interrupt status 1
+    REG_GPIO_INT_STAT_2 = 0x12, // GPIO interrupt status 2
+    REG_GPIO_INT_STAT_3 = 0x13, // GPIO interrupt status 3
+    REG_GPIO_DAT_STAT_1 = 0x14, // GPIO data status 1
+    REG_GPIO_DAT_STAT_2 = 0x15, // GPIO data status 2
+    REG_GPIO_DAT_STAT_3 = 0x16, // GPIO data status 3
+    REG_GPIO_DAT_OUT_1 = 0x17,  // GPIO data out 1
+    REG_GPIO_DAT_OUT_2 = 0x18,  // GPIO data out 2
+    REG_GPIO_DAT_OUT_3 = 0x19,  // GPIO data out 3
+    REG_GPIO_INT_EN_1 = 0x1A,   // GPIO interrupt enable 1
+    REG_GPIO_INT_EN_2 = 0x1B,   // GPIO interrupt enable 2
+    REG_GPIO_INT_EN_3 = 0x1C,   // GPIO interrupt enable 3
+    REG_KP_GPIO_1 = 0x1D,       // Keypad/GPIO select 1
+    REG_KP_GPIO_2 = 0x1E,       // Keypad/GPIO select 2
+    REG_KP_GPIO_3 = 0x1F,       // Keypad/GPIO select 3
+    REG_GPI_EM_1 = 0x20,        // GPI event mode 1
+    REG_GPI_EM_2 = 0x21,        // GPI event mode 2
+    REG_GPI_EM_3 = 0x22,        // GPI event mode 3
+    REG_GPIO_DIR_1 = 0x23,      // GPIO data direction 1
+    REG_GPIO_DIR_2 = 0x24,      // GPIO data direction 2
+    REG_GPIO_DIR_3 = 0x25,      // GPIO data direction 3
+    REG_GPIO_INT_LVL_1 = 0x26,  // GPIO edge/level detect 1
+    REG_GPIO_INT_LVL_2 = 0x27,  // GPIO edge/level detect 2
+    REG_GPIO_INT_LVL_3 = 0x28,  // GPIO edge/level detect 3
+    REG_DEBOUNCE_DIS_1 = 0x29,  // Debounce disable 1
+    REG_DEBOUNCE_DIS_2 = 0x2A,  // Debounce disable 2
+    REG_DEBOUNCE_DIS_3 = 0x2B,  // Debounce disable 3
+    REG_GPIO_PULL_1 = 0x2C,     // GPIO pull-up disable 1
+    REG_GPIO_PULL_2 = 0x2D,     // GPIO pull-up disable 2
+    REG_GPIO_PULL_3 = 0x2E,     // GPIO pull-up disable 3
+    // REG_RESERVED = 0x2F
+  };
+
+  enum tca8418_config_reg_fields
+  {
+    //  Config Register #1 fields
+    REG_CFG_AI = 0x80,           // Auto-increment for read/write
+    REG_CFG_GPI_E_CGF = 0x40,    // Event mode config
+    REG_CFG_OVR_FLOW_M = 0x20,   // Overflow mode enable
+    REG_CFG_INT_CFG = 0x10,      // Interrupt config
+    REG_CFG_OVR_FLOW_IEN = 0x08, // Overflow interrupt enable
+    REG_CFG_K_LCK_IEN = 0x04,    // Keypad lock interrupt enable
+    REG_CFG_GPI_IEN = 0x02,      // GPI interrupt enable
+    REG_CFG_KE_IEN = 0x01,       // Key events interrupt enable
+  };
+
+  enum tca8418_int_status_fields
+  {
+    //  Interrupt Status Register #2 fields
+    REG_STAT_CAD_INT = 0x10,      // Ctrl-alt-del seq status
+    REG_STAT_OVR_FLOW_INT = 0x08, // Overflow interrupt status
+    REG_STAT_K_LCK_INT = 0x04,    // Key lock interrupt status
+    REG_STAT_GPI_INT = 0x02,      // GPI interrupt status
+    REG_STAT_K_INT = 0x01,        // Key events interrupt status
+  };
+
+  enum tca8418_lock_ec_fields
+  {
+    // Key Lock Event Count Register #3
+    REG_LCK_EC_K_LCK_EN = 0x40, // Key lock enable
+    REG_LCK_EC_LCK_2 = 0x20,    // Keypad lock status 2
+    REG_LCK_EC_LCK_1 = 0x10,    // Keypad lock status 1
+    REG_LCK_EC_KLEC_3 = 0x08,   // Key event count bit 3
+    REG_LCK_EC_KLEC_2 = 0x04,   // Key event count bit 2
+    REG_LCK_EC_KLEC_1 = 0x02,   // Key event count bit 1
+    REG_LCK_EC_KLEC_0 = 0x01,   // Key event count bit 0
+  };
+};
+
+#endif

IO_TM1638.cpp

@@ -0,0 +1,215 @@
+/*
+ *  © 2024, Chris Harlow. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/* Credit to https://github.com/dvarrel/TM1638 for the basic formulae.*/
+
+
+#include <Arduino.h>
+#include "IODevice.h"
+#include "DIAG.h"
+
+   
+const uint8_t HIGHFLASH _digits[16]={
+      0b00111111,0b00000110,0b01011011,0b01001111,
+      0b01100110,0b01101101,0b01111101,0b00000111,
+      0b01111111,0b01101111,0b01110111,0b01111100,
+      0b00111001,0b01011110,0b01111001,0b01110001
+    };
+
+  // Constructor
+   TM1638::TM1638(VPIN firstVpin, byte clk_pin,byte dio_pin,byte stb_pin){
+    _firstVpin = firstVpin;
+    _nPins = 8;
+    _clk_pin = clk_pin;
+    _stb_pin = stb_pin;
+    _dio_pin = dio_pin;
+    pinMode(clk_pin,OUTPUT);
+    pinMode(stb_pin,OUTPUT);
+    pinMode(dio_pin,OUTPUT);
+    _pulse = PULSE1_16;
+      
+    _buttons=0;
+    _leds=0;
+    _lastLoop=micros();
+    addDevice(this);
+   } 
+
+    
+  void TM1638::create(VPIN firstVpin, byte clk_pin,byte dio_pin,byte stb_pin) {
+    if (checkNoOverlap(firstVpin,8)) 
+     new TM1638(firstVpin, clk_pin,dio_pin,stb_pin); 
+  }
+
+  void TM1638::_begin()  {
+    displayClear();
+    test();
+    _display();
+  }
+  
+ 
+  void TM1638::_loop(unsigned long currentMicros)  {
+     if (currentMicros - _lastLoop > (1000000UL/LoopHz)) {
+         _buttons=getButtons();// Read the buttons
+         _lastLoop=currentMicros;   
+     } 
+  }
+           
+  void TM1638::_display()  {
+    DIAG(F("TM1638 Configured on Vpins:%u-%u"), _firstVpin, _firstVpin+_nPins-1);
+  }
+
+// digital read gets button state 
+int TM1638::_read(VPIN vpin)  {
+  byte pin=vpin - _firstVpin;
+  bool result=bitRead(_buttons,pin);
+  // DIAG(F("TM1638 read (%d) buttons %x = %d"),pin,_buttons,result);  
+  return result;
+}
+
+// digital write sets led state 
+void TM1638::_write(VPIN vpin, int value)  {
+  // TODO.. skip if no state change  
+  writeLed(vpin - _firstVpin + 1,value!=0);
+  }
+
+// Analog write sets digit displays 
+
+void TM1638::_writeAnalogue(VPIN vpin, int lowBytes, uint8_t mode, uint16_t highBytes)  {  
+   // mode is in DataFormat defined above.
+   byte formatLength=mode & 0x0F;  // last 4 bits 
+   byte formatType=mode & 0xF0;         //           
+   int8_t leftDigit=vpin-_firstVpin; // 0..7 from left
+   int8_t rightDigit=leftDigit+formatLength-1; // 0..7 from left
+   
+   // loading is done right to left startDigit first
+   int8_t startDigit=7-rightDigit; // reverse as 7 on left
+   int8_t lastDigit=7-leftDigit; // reverse as 7 on left
+   uint32_t value=highBytes;
+   value<<=16;
+   value |= (uint16_t)lowBytes;
+   
+   //DIAG(F("TM1638 fl=%d ft=%x sd=%d ld=%d v=%l vx=%X"),
+   // formatLength,formatType,startDigit,lastDigit,value,value);
+    while(startDigit<=lastDigit) {
+        switch (formatType) {
+            case _DF_DECIMAL:// decimal (leading zeros)
+                displayDig(startDigit,GETHIGHFLASH(_digits,(value%10))); 
+                value=value/10;
+                break; 
+            case _DF_HEX:// HEX (leading zeros)
+                displayDig(startDigit,GETHIGHFLASH(_digits,(value & 0x0F))); 
+                value>>=4;
+                break;  
+            case _DF_RAW:// Raw 7-segment pattern 
+                displayDig(startDigit,value & 0xFF); 
+                value>>=8;
+                break;
+            default:
+                DIAG(F("TM1368 invalid mode 0x%x"),mode);
+                return;
+            }
+    startDigit++;
+    } 
+}
+     
+uint8_t TM1638::getButtons(){
+  ArduinoPins::fastWriteDigital(_stb_pin, LOW);
+  writeData(INSTRUCTION_READ_KEY);
+  pinMode(_dio_pin, INPUT);
+  ArduinoPins::fastWriteDigital(_clk_pin, LOW);
+  uint8_t buttons=0;
+  for (uint8_t eachByte=0; eachByte<4;eachByte++) {
+    uint8_t value = 0;
+	  for (uint8_t eachBit = 0; eachBit < 8; eachBit++) {
+		  ArduinoPins::fastWriteDigital(_clk_pin, HIGH);
+			value |= ArduinoPins::fastReadDigital(_dio_pin) << eachBit;
+		  ArduinoPins::fastWriteDigital(_clk_pin, LOW);
+	  }
+    buttons |= value << eachByte; 
+    delayMicroseconds(1);
+  }
+  pinMode(_dio_pin, OUTPUT);
+  ArduinoPins::fastWriteDigital(_stb_pin, HIGH);
+  return buttons;
+}
+
+
+void TM1638::displayDig(uint8_t digitId, uint8_t pgfedcba){
+  if (digitId>7) return;
+  setDataInstruction(DISPLAY_TURN_ON | _pulse);
+  setDataInstruction(INSTRUCTION_WRITE_DATA| INSTRUCTION_ADDRESS_FIXED);
+  writeDataAt(FIRST_DISPLAY_ADDRESS+14-(digitId*2), pgfedcba);
+}
+
+void TM1638::displayClear(){
+  setDataInstruction(DISPLAY_TURN_ON | _pulse);
+  setDataInstruction(INSTRUCTION_WRITE_DATA | INSTRUCTION_ADDRESS_FIXED);
+  for (uint8_t i=0;i<15;i+=2){
+    writeDataAt(FIRST_DISPLAY_ADDRESS+i,0x00);
+  }
+}
+
+void TM1638::writeLed(uint8_t num,bool state){
+  if ((num<1) | (num>8)) return;
+  setDataInstruction(DISPLAY_TURN_ON | _pulse);
+  setDataInstruction(INSTRUCTION_WRITE_DATA | INSTRUCTION_ADDRESS_FIXED);
+  writeDataAt(FIRST_DISPLAY_ADDRESS + (num*2-1), state);
+}
+
+
+void TM1638::writeData(uint8_t data){
+	for (uint8_t i = 0; i < 8; i++)  {
+		ArduinoPins::fastWriteDigital(_dio_pin, data & 1);
+		data >>= 1;
+		ArduinoPins::fastWriteDigital(_clk_pin, HIGH);
+		ArduinoPins::fastWriteDigital(_clk_pin, LOW);		
+	}
+} 
+
+void TM1638::writeDataAt(uint8_t displayAddress, uint8_t data){
+    ArduinoPins::fastWriteDigital(_stb_pin, LOW);
+    writeData(displayAddress);
+    writeData(data);
+    ArduinoPins::fastWriteDigital(_stb_pin, HIGH);
+    delayMicroseconds(1);
+}
+
+void TM1638::setDataInstruction(uint8_t dataInstruction){
+  ArduinoPins::fastWriteDigital(_stb_pin, LOW);
+  writeData(dataInstruction);
+  ArduinoPins::fastWriteDigital(_stb_pin, HIGH);
+  delayMicroseconds(1);  
+}
+
+void TM1638::test(){
+  DIAG(F("TM1638 test"));
+  uint8_t val=0;
+  for(uint8_t i=0;i<5;i++){
+    setDataInstruction(DISPLAY_TURN_ON | _pulse);
+    setDataInstruction(INSTRUCTION_WRITE_DATA| INSTRUCTION_ADDRESS_AUTO);
+    ArduinoPins::fastWriteDigital(_stb_pin, LOW);
+    writeData(FIRST_DISPLAY_ADDRESS);
+    for(uint8_t i=0;i<16;i++)
+      writeData(val);
+    ArduinoPins::fastWriteDigital(_stb_pin, HIGH);
+    delay(1000);
+    val = ~val;
+  }
+
+}

IO_TM1638.h

@@ -0,0 +1,134 @@
+   /*
+ *  © 2024, Chris Harlow. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef IO_TM1638_h
+#define IO_TM1638_h
+#include <Arduino.h>
+#include "IODevice.h"
+#include "DIAG.h"
+
+class TM1638 : public IODevice {
+private: 
+      
+    uint8_t _buttons;
+    uint8_t _leds;
+    unsigned long _lastLoop;
+    static const int LoopHz=20; 
+
+    static const byte 
+    INSTRUCTION_WRITE_DATA=0x40,
+    INSTRUCTION_READ_KEY=0x42,
+    INSTRUCTION_ADDRESS_AUTO=0x40,
+    INSTRUCTION_ADDRESS_FIXED=0x44,
+    INSTRUCTION_NORMAL_MODE=0x40,
+    INSTRUCTION_TEST_MODE=0x48,
+
+    FIRST_DISPLAY_ADDRESS=0xC0,
+
+    DISPLAY_TURN_OFF=0x80,
+    DISPLAY_TURN_ON=0x88;
+
+        
+    uint8_t _clk_pin;
+    uint8_t _stb_pin;
+    uint8_t _dio_pin;
+    uint8_t _pulse;
+    bool _isOn;
+
+    
+  // Constructor
+   TM1638(VPIN firstVpin, byte clk_pin,byte dio_pin,byte stb_pin);
+
+public:
+  enum DigitFormat : byte {
+    // last 4 bits are length.
+    // DF_1.. DF_8 decimal 
+    DF_1=0x01,DF_2=0x02,DF_3=0x03,DF_4=0x04,
+    DF_5=0x05,DF_6=0x06,DF_7=0x07,DF_8=0x08,
+    // DF_1X.. DF_8X HEX 
+    DF_1X=0x11,DF_2X=0x12,DF_3X=0x13,DF_4X=0x14,
+    DF_5X=0x15,DF_6X=0x16,DF_7X=0x17,DF_8X=0x18,
+    // DF_1R .. DF_4R raw 7 segmnent data 
+    // only 4 because HAL analogWrite only passes 4 bytes 
+    DF_1R=0x21,DF_2R=0x22,DF_3R=0x23,DF_4R=0x24,
+    
+    //  bits of data conversion type  (ored with length) 
+    _DF_DECIMAL=0x00,// right adjusted decimal unsigned leading zeros
+    _DF_HEX=0x10,    // right adjusted hex leading zeros 
+    _DF_RAW=0x20 // bytes are raw 7-segment pattern (max length 4)
+  };
+
+  static void create(VPIN firstVpin, byte clk_pin,byte dio_pin,byte stb_pin);
+  
+  // Functions overridden in IODevice
+  void _begin();
+  void _loop(unsigned long currentMicros) override ;
+  void _writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t param2) override;
+  void _display() override ;
+  int _read(VPIN pin) override;
+  void _write(VPIN pin,int value) override;
+
+  // Device driving functions 
+  private:
+   enum pulse_t {
+      PULSE1_16,
+      PULSE2_16,
+      PULSE4_16,
+      PULSE10_16,
+      PULSE11_16,
+      PULSE12_16,
+      PULSE13_16,
+      PULSE14_16
+    };
+
+  /**
+    * @fn getButtons
+    * @return state of 8 buttons
+    */
+    uint8_t getButtons();
+
+    /**
+    * @fn writeLed
+    * @brief put led ON or OFF
+    * @param num num of led(1-8)
+    * @param state (true or false)
+    */
+    void writeLed(uint8_t num, bool state);
+    
+    
+    /**
+    * @fn displayDig
+    * @brief set 7 segment display + dot
+    * @param digitId num of digit(0-7)
+    * @param val value 8 bits
+    */
+    void displayDig(uint8_t digitId, uint8_t pgfedcba);
+
+    /**
+    * @fn displayClear
+    * @brief switch off all leds and segment display
+    */
+    void displayClear();
+    void test();
+    void writeData(uint8_t data);
+    void writeDataAt(uint8_t displayAddress, uint8_t data);
+    void setDisplayMode(uint8_t displayMode);
+    void setDataInstruction(uint8_t dataInstruction);
+};
+#endif

IO_TouchKeypad.h

@@ -0,0 +1,134 @@
+/*
+ *  © 2023, Neil McKechnie. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/* 
+ * Driver for capacitative touch-pad based on the TTP229-B chip with serial 
+ * (not I2C) output.  The touchpad has 16 separate pads in a 4x4 matrix, 
+ * numbered 1-16.  The communications with the pad are via a clock signal sent
+ * from the controller to the device, and a data signal sent back by the device.
+ * The pins clockPin and dataPin must be local pins, not external (GPIO Expander)
+ * pins.
+ * 
+ * To use, 
+ *    TouchKeypad::create(firstVpin, 16, clockPin, dataPin);
+ * 
+ * NOTE: Most of these keypads ship with only 8 pads enabled.  To enable all
+ * sixteen pads, locate the area of the board labelled P1 (four pairs of 
+ * holes labelled 1 to 4 from the left); solder a jumper link between the pair 
+ * labelled 3 (connected to pin TP2 on the chip).  When this link is connected,
+ * the pins OUT1 to OUT8 are not used but all sixteen touch pads are operational.
+ * 
+ * TODO: Allow a list of datapins to be provided so that multiple keypads can
+ * be read simultaneously by the one device driver and the one shared clock signal.
+ * As it stands, we can configure multiple driver instances, one for each keypad, 
+ * and it will work fine.  The clock will be driven to all devices but only one 
+ * driver will be reading the responses from its corresponding device at a time.
+ */
+
+#ifndef IO_TOUCHKEYPAD_H
+#define IO_TOUCHKEYPAD_H
+
+#include "IODevice.h"
+
+class TouchKeypad : public IODevice {
+private:
+  // Here we define the device-specific variables.  
+  uint16_t _inputStates = 0;
+  VPIN _clockPin;
+  VPIN _dataPin;
+
+public:
+  //  Static function to handle create calls.
+  static void create(VPIN firstVpin, int nPins, VPIN clockPin, VPIN dataPin) {
+    if (checkNoOverlap(firstVpin,nPins)) new TouchKeypad(firstVpin, nPins, clockPin, dataPin);
+  } 
+
+protected:
+  // Constructor. 
+  TouchKeypad(VPIN firstVpin, int nPins, VPIN clockPin, VPIN dataPin) {
+    _firstVpin = firstVpin;
+    _nPins = (nPins > 16) ? 16 : nPins;  // Maximum of 16 pads per device
+    _clockPin = clockPin;
+    _dataPin = dataPin;
+
+    addDevice(this);
+  }
+
+  // Device-specific initialisation
+  void _begin() override {
+#if defined(DIAG_IO)
+    _display();
+#endif
+    // Set clock pin as output, initially high, and data pin as input.  
+    // Enable pullup on the input so that the default (not connected) state is 
+    // 'keypad not pressed'.
+    ArduinoPins::fastWriteDigital(_clockPin, 1);
+    pinMode(_clockPin, OUTPUT);
+    pinMode(_dataPin, INPUT_PULLUP); // Force defined state when no connection
+  }
+  
+  // Device-specific read function.
+  int _read(VPIN vpin) {
+    if (vpin < _firstVpin || vpin >= _firstVpin + _nPins) return 0;
+
+    // Return a value for the specified vpin.
+    return _inputStates & (1<<(vpin-_firstVpin)) ? 1 : 0;
+  }
+
+  // Loop function to do background scanning of the keyboard.
+  // The TTP229 device requires clock pulses to be sent to it,
+  // and the data bits can be read on the rising edge of the clock.
+  // By default the clock and data are inverted (active-low).
+  // A gap of more  than 2ms is advised between successive read
+  // cycles, we wait for 100ms between reads of the keyboard as this
+  // provide a good enough response time.
+  // Maximum clock frequency is 512kHz, so put a 1us delay
+  // between clock transitions.
+  //
+  void _loop(unsigned long currentMicros) {
+
+    // Clock 16 bits from the device
+    uint16_t data = 0, maskBit = 0x01;
+    for (uint8_t pad=0; pad<16; pad++) {
+      ArduinoPins::fastWriteDigital(_clockPin, 0);
+      delayMicroseconds(1);
+      ArduinoPins::fastWriteDigital(_clockPin, 1);
+      data |= (ArduinoPins::fastReadDigital(_dataPin) ? 0 : maskBit);
+      maskBit <<= 1;
+      delayMicroseconds(1);
+    }
+    _inputStates = data;
+#ifdef DIAG_IO
+    static uint16_t lastData = 0;
+    if (data != lastData) DIAG(F("KeyPad: %x"), data);
+    lastData = data;
+#endif
+    delayUntil(currentMicros + 100000); // read every 100ms
+  }
+
+  // Display information about the device, and perhaps its current condition (e.g. active, disabled etc).
+  void _display() {
+    DIAG(F("TouchKeypad Configured on Vpins:%u-%u SCL=%d SDO=%d"), (int)_firstVpin, 
+      (int)_firstVpin+_nPins-1, _clockPin, _dataPin);
+  }
+
+
+};
+
+#endif // IO_TOUCHKEYPAD_H

IO_VL53L0X.h

@@ -42,14 +42,17 @@
  * If you have more than one module, then you will need to specify a digital VPIN (Arduino
  * digital output or I/O extender pin) which you connect to the module's XSHUT pin.  Now,
  * when the device driver starts, the XSHUT pin is set LOW to turn the module off.  Once 
- * all VL53L0X modules are turned off, the driver works through each module in turn by
- * setting XSHUT to HIGH to turn the module on,, then writing the module's desired I2C address.
+ * all VL53L0X modules are turned off, the driver works through each module in turn,
+ * setting XSHUT to HIGH to turn that module on, then writing that module's desired I2C address.
  * In this way, many VL53L0X modules can be connected to the one I2C bus, each one 
- * using a distinct I2C address.
+ * using a distinct I2C address.  The process is described in ST Microelectronics application
+ * note AN4846.
  * 
- * WARNING:  If the device's XSHUT pin is not connected, then it is very prone to noise, 
- * and the device may even reset when handled.  If you're not using XSHUT, then it's 
- * best to tie it to +5V.
+ * WARNING:  If the device's XSHUT pin is not connected, then it may be prone to noise, 
+ * and the device may reset spontaneously or when handled and the device will stop responding
+ * on its allocated address.  If you're not using XSHUT, then tie it to +5V via a resistor 
+ * (should be tied to +2.8V strictly). Some manufacturers (Adafruit and Polulu for example)
+ * include a pull-up on the module, but others don't.
  * 
  * The driver is configured as follows:
  * 
@@ -70,7 +73,8 @@
  *       lowThreshold is the distance at which the digital vpin state is set to 1 (in mm),
  *       highThreshold is the distance at which the digital vpin state is set to 0 (in mm),
  *   and xshutPin is the VPIN number corresponding to a digital output that is connected to the
- *       XSHUT terminal on the module.
+ *       XSHUT terminal on the module.  The digital output may be an Arduino pin or an
+ *       I/O extender pin.
  * 
  * Example:
  *   In mySetup function within mySetup.cpp:
@@ -93,7 +97,6 @@
 
 class VL53L0X : public IODevice {
 private: 
-  uint8_t _i2cAddress;
   uint16_t _ambient;
   uint16_t _distance;
   uint16_t _signal;
@@ -101,20 +104,23 @@ private:
   uint16_t _offThreshold;
   VPIN _xshutPin;
   bool _value;
-  uint8_t _nextState = 0;
+  uint8_t _nextState = STATE_INIT;
   I2CRB _rb;
   uint8_t _inBuffer[12];
   uint8_t _outBuffer[2];
+  static bool _addressConfigInProgress;
+
   // State machine states.
   enum : uint8_t {
-    STATE_INIT = 0,
-    STATE_CONFIGUREADDRESS = 1,
-    STATE_SKIP = 2,
-    STATE_CONFIGUREDEVICE = 3,
-    STATE_INITIATESCAN = 4,
-    STATE_CHECKSTATUS = 5,
-    STATE_GETRESULTS = 6,
-    STATE_DECODERESULTS = 7,
+    STATE_INIT,
+    STATE_RESTARTMODULE,
+    STATE_CONFIGUREADDRESS,
+    STATE_CONFIGUREDEVICE,
+    STATE_INITIATESCAN,
+    STATE_CHECKSTATUS,
+    STATE_GETRESULTS,
+    STATE_DECODERESULTS,
+    STATE_FAILED,
   };
 
   // Register addresses
@@ -127,98 +133,126 @@ private:
   };
   const uint8_t VL53L0X_I2C_DEFAULT_ADDRESS=0x29;
 
-public:
-  VL53L0X(VPIN firstVpin, int nPins, uint8_t i2cAddress, uint16_t onThreshold, uint16_t offThreshold, VPIN xshutPin = VPIN_NONE) {
+
+  public:
+  static void create(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint16_t onThreshold, uint16_t offThreshold, VPIN xshutPin = VPIN_NONE) {
+     if (checkNoOverlap(firstVpin, nPins,i2cAddress)) new VL53L0X(firstVpin, nPins, i2cAddress, onThreshold, offThreshold, xshutPin);
+  }
+
+protected:
+  VL53L0X(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint16_t onThreshold, uint16_t offThreshold, VPIN xshutPin = VPIN_NONE) {
     _firstVpin = firstVpin;
-    _nPins = min(nPins, 3);
-    _i2cAddress = i2cAddress;
+    _nPins = (nPins > 3) ? 3 : nPins;
+    _I2CAddress = i2cAddress;
     _onThreshold = onThreshold;
     _offThreshold = offThreshold;
     _xshutPin = xshutPin;
     _value = 0;
     addDevice(this);
   }
-  static void create(VPIN firstVpin, int nPins, uint8_t i2cAddress, uint16_t onThreshold, uint16_t offThreshold, VPIN xshutPin = VPIN_NONE) {
-    new VL53L0X(firstVpin, nPins, i2cAddress, onThreshold, offThreshold, xshutPin);
-  }
-
-protected:
   void _begin() override {
-    if (_xshutPin == VPIN_NONE) {
-      // Check if device is already responding on the nominated address.
-      if (I2CManager.exists(_i2cAddress)) {
-        // Yes, it's already on this address, so skip the address initialisation.
-        _nextState = STATE_CONFIGUREDEVICE;
-      } else {
-        _nextState = STATE_INIT;
-      }
-    }
+    // If there's only one device, then the XSHUT pin need not be connected.  However, 
+    //  the device will not respond on its default address if it has 
+    //  already been changed.  Therefore, we skip the address configuration if the 
+    //  desired address is already responding on the I2C bus.
+    _nextState = STATE_INIT;
+    _addressConfigInProgress = false;
   }
 
   void _loop(unsigned long currentMicros) override {
     uint8_t status;
     switch (_nextState) {
       case STATE_INIT:
-        // On first entry to loop, reset this module by pulling XSHUT low.  All modules
-        // will be reset in turn.
-        if (_xshutPin != VPIN_NONE) IODevice::write(_xshutPin, 0);
-        _nextState = STATE_CONFIGUREADDRESS;
+        if (I2CManager.exists(_I2CAddress)) {
+          // Device already present on the nominated address, so skip the address initialisation.
+          _nextState = STATE_CONFIGUREDEVICE;
+        } else {
+          // On first entry to loop, reset this module by pulling XSHUT low.  Each module
+          // will be addressed in turn, until all are in the reset state.
+          // If no XSHUT pin is configured, then only one device is supported.
+          if (_xshutPin != VPIN_NONE) IODevice::write(_xshutPin, 0);
+          _nextState = STATE_RESTARTMODULE;
+          delayUntil(currentMicros+10000);
+        }
+        break;
+      case STATE_RESTARTMODULE:
+        // On second entry, set XSHUT pin high to allow this module to restart.
+        // I've observed that the device tends to randomly reset if the XSHUT 
+        // pin is set high from a 5V arduino, even through a pullup resistor.  
+        // Assume that there will be a pull-up on the XSHUT pin to +2.8V as
+        // recommended in the device datasheet.  Then we only need to
+        // turn our output pin high-impedence (by making it an input) and the
+        // on-board pullup will do its job.
+        // Ensure XSHUT is set for only one module at a time by using a
+        // shared flag accessible to all device instances.
+        if (!_addressConfigInProgress) {
+          _addressConfigInProgress = true;
+          // Configure XSHUT pin (if connected) to bring the module out of sleep mode.
+          if (_xshutPin != VPIN_NONE) IODevice::configureInput(_xshutPin, false);
+          // Allow the module time to restart
+          delayUntil(currentMicros+10000);
+          _nextState = STATE_CONFIGUREADDRESS;
+        }
         break;
       case STATE_CONFIGUREADDRESS:
-        // On second entry, set XSHUT pin high to allow the module to restart.
-        // On the module, there is a diode in series with the XSHUT pin to 
-        // protect the low-voltage pin against +5V.
-        if (_xshutPin != VPIN_NONE) IODevice::write(_xshutPin, 1);
-        // Allow the module time to restart
-        delay(10);
         // Then write the desired I2C address to the device, while this is the only
         //  module responding to the default address.
-        I2CManager.write(VL53L0X_I2C_DEFAULT_ADDRESS, 2, VL53L0X_REG_I2C_SLAVE_DEVICE_ADDRESS, _i2cAddress);
-        _nextState = STATE_SKIP;
-        break;
-      case STATE_SKIP:
-        // Do nothing on the third entry.
+        {
+          #if defined(I2C_EXTENDED_ADDRESS)
+          // Add subbus reference for desired address to the device default address.
+          I2CAddress defaultAddress = {_I2CAddress, VL53L0X_I2C_DEFAULT_ADDRESS};
+          status = I2CManager.write(defaultAddress, 2, VL53L0X_REG_I2C_SLAVE_DEVICE_ADDRESS, _I2CAddress.deviceAddress());
+          #else
+          status = I2CManager.write(VL53L0X_I2C_DEFAULT_ADDRESS, 2, VL53L0X_REG_I2C_SLAVE_DEVICE_ADDRESS, _I2CAddress);
+          #endif
+          if (status != I2C_STATUS_OK) {
+            reportError(status);
+          }
+        }
+        delayUntil(currentMicros+10000);
         _nextState = STATE_CONFIGUREDEVICE;
         break;
       case STATE_CONFIGUREDEVICE:
-        // On next entry, check if device address has been set.
-        if (I2CManager.exists(_i2cAddress)) {
+        // Allow next VL53L0X device to be configured
+        _addressConfigInProgress = false;
+        // Now check if device address has been set.
+        if (I2CManager.exists(_I2CAddress)) {
           #ifdef DIAG_IO
           _display();
           #endif
           // Set 2.8V mode
-          write_reg(VL53L0X_CONFIG_PAD_SCL_SDA__EXTSUP_HV, 
+          status = write_reg(VL53L0X_CONFIG_PAD_SCL_SDA__EXTSUP_HV, 
             read_reg(VL53L0X_CONFIG_PAD_SCL_SDA__EXTSUP_HV) | 0x01);
+          if (status != I2C_STATUS_OK) {
+            reportError(status);
+          } else
+            _nextState = STATE_INITIATESCAN;
         } else {
-          DIAG(F("VL53L0X I2C:x%x device not responding"), _i2cAddress);
+          DIAG(F("VL53L0X I2C:%s device not responding"), _I2CAddress.toString());
           _deviceState = DEVSTATE_FAILED;
+          _nextState = STATE_FAILED;
         }
-        _nextState = STATE_INITIATESCAN;
         break;
       case STATE_INITIATESCAN:
         // Not scanning, so initiate a scan
         _outBuffer[0] = VL53L0X_REG_SYSRANGE_START;
         _outBuffer[1] = 0x01;
-        I2CManager.write(_i2cAddress, _outBuffer, 2, &_rb);
+        I2CManager.write(_I2CAddress, _outBuffer, 2, &_rb);
         _nextState = STATE_CHECKSTATUS;
         break;
       case STATE_CHECKSTATUS:
         status = _rb.status;
         if (status == I2C_STATUS_PENDING) return; // try next time
         if (status != I2C_STATUS_OK) {
-          DIAG(F("VL53L0X I2C:x%x Error:%d %S"), _i2cAddress, status, I2CManager.getErrorMessage(status));
-          _deviceState = DEVSTATE_FAILED;
-          _value = false;
+          reportError(status);
         } else
-          _nextState = 2;
+          _nextState = STATE_GETRESULTS;
         delayUntil(currentMicros + 95000); // wait for 95 ms before checking.
-        _nextState = STATE_GETRESULTS;
         break;
       case STATE_GETRESULTS:
         // Ranging completed.  Request results
         _outBuffer[0] = VL53L0X_REG_RESULT_RANGE_STATUS;
-        I2CManager.read(_i2cAddress, _inBuffer, 12, _outBuffer, 1, &_rb);
-        _nextState = 3;
+        I2CManager.read(_I2CAddress, _inBuffer, 12, _outBuffer, 1, &_rb);
         delayUntil(currentMicros + 5000); // Allow 5ms to get data
         _nextState = STATE_DECODERESULTS;
         break;
@@ -239,15 +273,28 @@ protected:
             else if (_distance > _offThreshold) 
               _value = false;
           }
+          // Completed. Restart scan on next loop entry.
+          _nextState = STATE_INITIATESCAN;
+        } else {
+          reportError(status);
         }
-        // Completed. Restart scan on next loop entry.
-        _nextState = STATE_INITIATESCAN;
+        break;
+      case STATE_FAILED:
+        // Do nothing.
+        delayUntil(currentMicros+1000000UL);
         break;
       default:
         break;
     }
   }
 
+  // Function to report a failed I2C operation.
+  void reportError(uint8_t status) {
+    DIAG(F("VL53L0X I2C:%s Error:%d %S"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status));
+    _deviceState = DEVSTATE_FAILED;
+    _value = false;
+  }
+
   // For analogue read, first pin returns distance, second pin is signal strength, and third is ambient level.
   int _readAnalogue(VPIN vpin) override {
     int pin = vpin - _firstVpin;
@@ -272,8 +319,8 @@ protected:
   }
 
   void _display() override {
-    DIAG(F("VL53L0X I2C:x%x Configured on Vpins:%d-%d On:%dmm Off:%dmm %S"),
-      _i2cAddress, _firstVpin, _firstVpin+_nPins-1, _onThreshold, _offThreshold,
+    DIAG(F("VL53L0X I2C:%s Configured on Vpins:%u-%u On:%dmm Off:%dmm %S"),
+      _I2CAddress.toString(), _firstVpin, _firstVpin+_nPins-1, _onThreshold, _offThreshold,
       (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F(""));
   }
   
@@ -287,13 +334,15 @@ private:
     uint8_t outBuffer[2];
     outBuffer[0] = reg;
     outBuffer[1] = data;
-    return I2CManager.write(_i2cAddress, outBuffer, 2);
+    return I2CManager.write(_I2CAddress, outBuffer, 2);
   }
   uint8_t read_reg(uint8_t reg) {
     // read byte from register and return value
-    I2CManager.read(_i2cAddress, _inBuffer, 1, &reg, 1);
+    I2CManager.read(_I2CAddress, _inBuffer, 1, &reg, 1);
     return _inBuffer[0];
   }
 };
 
+bool VL53L0X::_addressConfigInProgress = false;
+
 #endif // IO_VL53L0X_h

IO_duinoNodes.h

@@ -0,0 +1,173 @@
+/*
+ *  © 2022, Chris Harlow. All rights reserved.
+ *  Based on original by: Robin Simonds, Beagle Bay Inc
+ *  
+ *  This file is part of DCC-EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#ifndef IO_duinoNodes_h
+ #define IO_duinoNodes_h
+#include <Arduino.h>
+#include "defines.h"
+#include "IODevice.h"
+
+#define DN_PIN_MASK(bit) (0x80>>(bit%8))
+#define DN_GET_BIT(x) (_pinValues[(x)/8] & DN_PIN_MASK((x)) )
+#define DN_SET_BIT(x) _pinValues[(x)/8] |= DN_PIN_MASK((x))
+#define DN_CLR_BIT(x) _pinValues[(x)/8] &= ~DN_PIN_MASK((x))
+
+
+
+class IO_duinoNodes : public IODevice {
+
+public:
+  IO_duinoNodes(VPIN firstVpin, int nPins, 
+                byte clockPin, byte latchPin, byte dataPin, 
+                const byte* pinmap) :
+    IODevice(firstVpin, nPins) {
+ 
+   _latchPin=latchPin;
+    _clockPin=clockPin;
+    _dataPin=dataPin;
+    _pinMap=pinmap;
+    _nShiftBytes=(nPins+7)/8; // rounded up to multiples of 8 bits
+    _pinValues=(byte*) calloc(_nShiftBytes,1);  
+    // Connect to HAL so my _write, _read and _loop will be called as required.
+    IODevice::addDevice(this);  
+  }
+
+// Called by HAL to start handling this device
+  void _begin() override {
+     _deviceState = DEVSTATE_NORMAL;
+    pinMode(_latchPin,OUTPUT);
+    pinMode(_clockPin,OUTPUT);
+    pinMode(_dataPin,_pinMap?INPUT_PULLUP:OUTPUT);
+    _display();
+    if (!_pinMap) _loopOutput();
+  }
+
+// loop called by HAL supervisor 
+void _loop(unsigned long currentMicros) override {
+    if (_pinMap) _loopInput(currentMicros);
+    else if (_xmitPending) _loopOutput();
+}
+
+void _loopInput(unsigned long currentMicros)  {
+   
+   if (currentMicros-_prevMicros < POLL_MICROS) return; // Nothing to do
+    _prevMicros=currentMicros;
+   
+    //set latch to HIGH to freeze & store parallel data
+   ArduinoPins::fastWriteDigital(_latchPin, HIGH);
+   delayMicroseconds(1);
+   //set latch to LOW to enable the data to be transmitted serially
+   ArduinoPins::fastWriteDigital(_latchPin, LOW);
+
+  // stream in the bitmap using mapping order provided at constructor   
+  for (int xmitByte=0;xmitByte<_nShiftBytes; xmitByte++) {
+      byte newByte=0;
+      for (int xmitBit=0;xmitBit<8; xmitBit++) {
+        ArduinoPins::fastWriteDigital(_clockPin, LOW);
+        delayMicroseconds(1);
+        bool data = ArduinoPins::fastReadDigital(_dataPin);  
+        byte map=_pinMap[xmitBit];
+        if (data)  newByte |= map;
+            else   newByte &= ~map;
+        ArduinoPins::fastWriteDigital(_clockPin, HIGH); 
+        delayMicroseconds(1);   
+      }
+      _pinValues[xmitByte]=newByte;
+      // DIAG(F("DIN %x=%x"),xmitByte, newByte);
+    }
+  }
+
+void _loopOutput()  {
+    // stream out the bitmap (highest pin first)
+    _xmitPending=false; 
+    ArduinoPins::fastWriteDigital(_latchPin, LOW);
+    for (int xmitBit=_nShiftBytes*8 -1; xmitBit>=0; xmitBit--) {
+        ArduinoPins::fastWriteDigital(_dataPin,DN_GET_BIT(xmitBit));
+        ArduinoPins::fastWriteDigital(_clockPin,HIGH);
+        ArduinoPins::fastWriteDigital(_clockPin,LOW);
+    }  
+    ArduinoPins::fastWriteDigital(_latchPin, HIGH);
+  }
+
+  int _read(VPIN vpin) override {
+    int pin=vpin - _firstVpin;
+    bool b=DN_GET_BIT(pin);
+    return b?1:0;
+  }
+
+  void _write(VPIN vpin, int value) override {
+    int pin = vpin - _firstVpin;
+    bool oldval=DN_GET_BIT(pin);
+    bool newval=value!=0;
+    if (newval==oldval) return; // no change  
+    if (newval) DN_SET_BIT(pin);
+           else DN_CLR_BIT(pin);
+    _xmitPending=true;  // shift register will be sent on next _loop()
+  }
+
+  void _display() override {
+      DIAG(F("IO_duinoNodes %SPUT Configured on Vpins:%u-%u shift=%d"), 
+      _pinMap?F("IN"):F("OUT"),
+      (int)_firstVpin, 
+      (int)_firstVpin+_nPins-1, _nShiftBytes*8);
+  }
+
+private:
+  static const unsigned long POLL_MICROS=100000; // 10 / S
+  unsigned long _prevMicros; 
+  int  _nShiftBytes=0; 
+  VPIN _latchPin,_clockPin,_dataPin;
+  byte* _pinValues;
+  bool _xmitPending; // Only relevant in output mode
+  const byte* _pinMap;  // NULL in output mode 
+};
+
+class IO_DNIN8  {
+public:
+  static void create(VPIN firstVpin, int nPins, byte clockPin, byte latchPin, byte dataPin ) 
+  {
+      // input arrives as board pin 0,7,6,5,1,2,3,4 
+      static const byte pinmap[8]={0x80,0x01,0x02,0x04,0x40,0x20,0x10,0x08};
+      if (IODevice::checkNoOverlap(firstVpin,nPins))
+        new IO_duinoNodes( firstVpin,  nPins,  clockPin,  latchPin,   dataPin,pinmap);
+  }
+
+};
+
+class IO_DNIN8K  {
+public:
+  static void create(VPIN firstVpin, int nPins, byte clockPin, byte latchPin, byte dataPin ) 
+  {
+      // input arrives as board pin 0, 1, 2, 3, 4, 5, 6, 7
+      static const byte pinmap[8]={0x01,0x02,0x04,0x08,0x10,0x20,0x40,0x80}; 
+       if (IODevice::checkNoOverlap(firstVpin,nPins))
+        new IO_duinoNodes( firstVpin,  nPins, clockPin, latchPin, dataPin,pinmap);
+  }
+};
+
+class IO_DNOU8 {
+public:
+  static void create(VPIN firstVpin, int nPins, byte clockPin, byte latchPin, byte dataPin ) 
+  {
+        if (IODevice::checkNoOverlap(firstVpin,nPins))
+         new IO_duinoNodes( firstVpin,  nPins,  clockPin, latchPin,   dataPin,NULL);
+  }
+
+};
+#endif

IO_trainbrains.h

@@ -0,0 +1,98 @@
+/*
+ *  © 2023, Chris Harlow. All rights reserved.
+ *  © 2021, Neil McKechnie. All rights reserved.
+ *  
+ *  This file is part of DCC++EX API
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef io_trainbrains_h
+#define io_trainbrains_h
+
+#include "IO_GPIOBase.h"
+#include "FSH.h"
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////
+/*
+ * IODevice subclass for trainbrains 3-block occupancy detector.
+ * For details see http://trainbrains.eu
+ */
+ 
+ enum TrackUnoccupancy
+{
+    TRACK_UNOCCUPANCY_UNKNOWN = 0,
+    TRACK_OCCUPIED = 1,
+    TRACK_UNOCCUPIED = 2
+};
+
+class Trainbrains02 : public GPIOBase<uint16_t> {
+public:
+  static void create(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress) {
+    if (checkNoOverlap(vpin, nPins, i2cAddress)) new Trainbrains02(vpin, nPins, i2cAddress);
+  }
+
+private:  
+  // Constructor
+  Trainbrains02(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) 
+    : GPIOBase<uint16_t>((FSH *)F("Trainbrains02"), vpin, nPins, i2cAddress, interruptPin) 
+  {
+    requestBlock.setRequestParams(_I2CAddress, inputBuffer, sizeof(inputBuffer),
+      outputBuffer, sizeof(outputBuffer));
+    
+     outputBuffer[0] = (uint8_t)_I2CAddress; // strips away the mux part.
+     outputBuffer[1] =14;
+     outputBuffer[2] =1;
+     outputBuffer[3] =0;  // This is the channel updated at each poling call
+     outputBuffer[4] =0;
+     outputBuffer[5] =0;
+     outputBuffer[6] =0;
+     outputBuffer[7] =0;
+     outputBuffer[8] =0;
+     outputBuffer[9] =0;
+  }
+  
+  void _writeGpioPort() override {}
+
+  void _readGpioPort(bool immediate) override {
+    // cycle channel on device each time 
+    outputBuffer[3]=channelInProgress+1; // 1-origin 
+    channelInProgress++;
+    if(channelInProgress>=_nPins) channelInProgress=0; 
+    
+    if (immediate) {
+      _processCompletion(I2CManager.read(_I2CAddress, inputBuffer, sizeof(inputBuffer), 
+                                   outputBuffer, sizeof(outputBuffer)));
+    } else {
+      // Queue new request
+      requestBlock.wait(); // Wait for preceding operation to complete
+      // Issue new request to read GPIO register
+      I2CManager.queueRequest(&requestBlock);
+    }
+  }
+
+  // This function is invoked when an I/O operation on the requestBlock completes.
+  void _processCompletion(uint8_t status) override {
+    if (status != I2C_STATUS_OK) inputBuffer[6]=TRACK_UNOCCUPANCY_UNKNOWN;  
+    if (inputBuffer[6] == TRACK_UNOCCUPIED ) _portInputState |=  0x01 <<channelInProgress;
+    else _portInputState &=  ~(0x01 <<channelInProgress);
+  }
+
+  uint8_t channelInProgress=0; 
+  uint8_t outputBuffer[10];
+  uint8_t inputBuffer[10];
+  
+};
+
+#endif

KeywordHasher.h

@@ -0,0 +1,96 @@
+/*
+ *  © 2024 Vincent Hamp and Chris Harlow
+ *  All rights reserved.
+ *  
+ *  This file is part of CommandStation-EX
+ *
+ *  This 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.
+ *
+ *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+/* Reader be aware: 
+ This function implements the _hk data type so that a string keyword
+ is hashed to the same value as the DCCEXParser uses to hash incoming 
+ keywords. 
+ Thus  "MAIN"_hk  generates exactly the same run time vakue 
+ as   const int16_t HASH_KEYWORD_MAIN=11339  
+*/
+#ifndef KeywordHasher_h
+#define KeywordHasher_h
+
+#include <Arduino.h>
+constexpr uint16_t CompiletimeKeywordHasher(const char *  sv, uint16_t running=0) {
+    return (*sv==0) ? running : CompiletimeKeywordHasher(sv+1,
+          (*sv >= '0' && *sv <= '9') 
+            ? (10*running+*sv-'0')  // Numeric hash  
+            : ((running << 5) + running) ^ *sv
+            );  // 
+}
+
+constexpr int16_t operator""_hk(const char * keyword, size_t len) 
+{
+    return (int16_t) CompiletimeKeywordHasher(keyword,len*0);
+}
+
+/* Some historical values for testing:
+const int16_t HASH_KEYWORD_MAIN = 11339;
+const int16_t HASH_KEYWORD_SLOW = -17209;
+const int16_t HASH_KEYWORD_SPEED28 = -17064;
+const int16_t HASH_KEYWORD_SPEED128 = 25816;
+*/
+
+static_assert("MAIN"_hk == 11339,"Keyword hasher error");
+static_assert("SLOW"_hk == -17209,"Keyword hasher error");
+static_assert("SPEED28"_hk == -17064,"Keyword hasher error");
+static_assert("SPEED128"_hk == 25816,"Keyword hasher error");
+
+// Compile time converter from "abcd"_s7  to the 7 segment nearest equivalent
+
+constexpr uint8_t seg7Digits[]={
+      0b00111111,0b00000110,0b01011011,0b01001111, // 0..3
+      0b01100110,0b01101101,0b01111101,0b00000111, // 4..7
+      0b01111111,0b01101111 // 8..9
+    };
+    
+constexpr uint8_t seg7Letters[]={
+        0b01110111,0b01111100,0b00111001,0b01011110, // ABCD
+        0b01111001,0b01110001,0b00111101,0b01110110, // EFGH 
+        0b00000100,0b00011110,0b01110010,0b00111000,  //IJKL
+        0b01010101,0b01010100,0b01011100,0b01110011, // MNOP
+        0b10111111,0b01010000,0b01101101,0b01111000, // QRST
+        0b00111110,0b00011100,0b01101010,0b01001001,  //UVWX
+        0b01100110,0b01011011  //YZ
+    };
+constexpr uint8_t seg7Space=0b00000000;
+constexpr uint8_t seg7Minus=0b01000000;
+constexpr uint8_t seg7Equals=0b01001000;
+    
+
+constexpr uint32_t CompiletimeSeg7(const char *  sv, uint32_t running, size_t rlen) {
+    return (*sv==0 || rlen==0) ? running << (8*rlen) : CompiletimeSeg7(sv+1,
+          (*sv >= '0' && *sv <= '9') ? (running<<8) | seg7Digits[*sv-'0'] : 
+          (*sv >= 'A' && *sv <= 'Z') ? (running<<8) | seg7Letters[*sv-'A'] : 
+          (*sv >= 'a' && *sv <= 'z') ? (running<<8) | seg7Letters[*sv-'a'] : 
+          (*sv == '-') ? (running<<8) | seg7Minus : 
+          (*sv == '=') ? (running<<8) | seg7Equals : 
+                         (running<<8) | seg7Space,
+          rlen-1               
+        );  // 
+}
+
+constexpr uint32_t operator""_s7(const char * keyword, size_t len) 
+{
+    return  CompiletimeSeg7(keyword,0*len,4);
+}
+#endif

LCDDisplay.cpp

@@ -1,167 +0,0 @@
-/*
- *  © 2021, Chris Harlow, Neil McKechnie. All rights reserved.
- *
- *  This file is part of CommandStation-EX
- *
- *  This 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.
- *
- *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-// CAUTION: the device dependent parts of this class are created in the .ini
-// using LCD_Implementation.h
-
-/* The strategy for drawing the screen is as follows.
- *  1) There are up to eight rows of text to be displayed.
- *  2) Blank rows of text are ignored.
- *  3) If there are more non-blank rows than screen lines,
- *     then all of the rows are displayed, with the rest of the
- *     screen being blank.
- *  4) If there are fewer non-blank rows than screen lines,
- *     then a scrolling strategy is adopted so that, on each screen
- *     refresh, a different subset of the rows is presented.
- *  5) On each entry into loop2(), a single operation is sent to the 
- *     screen; this may be a position command or a character for
- *     display.  This spreads the onerous work of updating the screen
- *     and ensures that other loop() functions in the application are
- *     not held up significantly.  The exception to this is when 
- *     the loop2() function is called with force=true, where 
- *     a screen update is executed to completion.  This is normally
- *     only done during start-up.
- *  The scroll mode is selected by defining SCROLLMODE as 0, 1 or 2
- *  in the config.h.
- *  #define SCROLLMODE 0 is scroll continuous (fill screen if poss),
- *  #define SCROLLMODE 1 is by page (alternate between pages),
- *  #define SCROLLMODE 2 is by row (move up 1 row at a time).
-
- */
-
-#include "LCDDisplay.h"
-
-void LCDDisplay::clear() {
-  clearNative();
-  for (byte row = 0; row < MAX_LCD_ROWS; row++) rowBuffer[row][0] = '\0';
-  topRow = -1;  // loop2 will fill from row 0
-}
-
-void LCDDisplay::setRow(byte line) {
-  hotRow = line;
-  hotCol = 0;
-}
-
-size_t LCDDisplay::write(uint8_t b) {
-  if (hotRow >= MAX_LCD_ROWS || hotCol >= MAX_LCD_COLS) return -1;
-  rowBuffer[hotRow][hotCol] = b;
-  hotCol++;
-  rowBuffer[hotRow][hotCol] = 0;
-  return 1;
-}
-
-void LCDDisplay::loop() {
-  if (!lcdDisplay) return;
-  lcdDisplay->loop2(false);
-}
-
-LCDDisplay *LCDDisplay::loop2(bool force) {
-  if (!lcdDisplay) return NULL;
-
-  // If output device is busy, don't do anything on this loop
-  //  This avoids blocking while waiting for the device to complete.
-  if (isBusy()) return NULL;  
-
-  unsigned long currentMillis = millis();
-
-  if (!force) {
-    // See if we're in the time between updates
-    if ((currentMillis - lastScrollTime) < LCD_SCROLL_TIME)
-      return NULL;
-  } else {
-    // force full screen update from the beginning.
-    rowFirst = -1;
-    rowNext = 0;
-    bufferPointer = 0;
-    done = false;
-    slot = 0;
-  }
-
-  do {
-    if (bufferPointer == 0) {
-      // Find a line of data to write to the screen.
-      if (rowFirst < 0) rowFirst = rowNext;
-      skipBlankRows();
-      if (!done) {
-        // Non-blank line found, so copy it.
-        for (uint8_t i = 0; i < sizeof(buffer); i++)
-          buffer[i] = rowBuffer[rowNext][i];
-      } else
-        buffer[0] = '\0';  // Empty line
-      setRowNative(slot);  // Set position for display
-      charIndex = 0;
-      bufferPointer = &buffer[0];
-
-    } else {
-
-      // Write next character, or a space to erase current position.
-      char ch = *bufferPointer;
-      if (ch) {
-        writeNative(ch);
-        bufferPointer++;
-      } else
-        writeNative(' ');
-
-      if (++charIndex >= MAX_LCD_COLS) {
-        // Screen slot completed, move to next slot on screen
-        slot++;
-        bufferPointer = 0;
-        if (!done) {
-          moveToNextRow();
-          skipBlankRows();
-        }
-      }
-
-      if (slot >= lcdRows) {
-        // Last slot finished, reset ready for next screen update.
-#if SCROLLMODE==2
-        if (!done) {
-          // On next refresh, restart one row on from previous start.
-          rowNext = rowFirst;
-          moveToNextRow();
-          skipBlankRows();
-        }
-#endif
-        done = false;
-        slot = 0;
-        rowFirst = -1;
-        lastScrollTime = currentMillis;
-        return NULL;
-      }
-    }
-  } while (force);
-
-  return NULL;
-}
-
-void LCDDisplay::moveToNextRow() {
-  rowNext = (rowNext + 1) % MAX_LCD_ROWS;
-#if SCROLLMODE == 1
-  // Finished if we've looped back to row 0
-  if (rowNext == 0) done = true;
-#else
-  // Finished if we're back to the first one shown
-  if (rowNext == rowFirst) done = true;
-#endif
-}
-
-void LCDDisplay::skipBlankRows() {
-  while (!done && rowBuffer[rowNext][0] == 0)
-    moveToNextRow();
-}

LCDDisplay.h

@@ -1,81 +0,0 @@
-/*
- *  © 2021, Chris Harlow, Neil McKechnie. All rights reserved.
- *
- *  This file is part of CommandStation-EX
- *
- *  This 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.
- *
- *  It 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 CommandStation.  If not, see <https://www.gnu.org/licenses/>.
- */
-#ifndef LCDDisplay_h
-#define LCDDisplay_h
-#include <Arduino.h>
-#include "defines.h"
-#include "DisplayInterface.h"
-
-// Allow maximum message length to be overridden from config.h
-#if !defined(MAX_MSG_SIZE) 
-#define MAX_MSG_SIZE 20
-#endif
-
-// Set default scroll mode (overridable in config.h)
-#if !defined(SCROLLMODE) 
-#define SCROLLMODE 1
-#endif
-
-// This class is created in LCDisplay_Implementation.h
-
-class LCDDisplay : public DisplayInterface {
- public:
-  LCDDisplay() {};
-  static const int MAX_LCD_ROWS = 8;
-  static const int MAX_LCD_COLS = MAX_MSG_SIZE;
-  static const long LCD_SCROLL_TIME = 3000;  // 3 seconds
-
-  // Internally handled functions
-  static void loop();
-  LCDDisplay* loop2(bool force) override;
-  void setRow(byte line) override;
-  void clear() override;
-
-  size_t write(uint8_t b) override;
-
-protected:
-  uint8_t lcdRows;
-  uint8_t lcdCols;
-
- private:
-  void moveToNextRow();
-  void skipBlankRows();
-
-  // Relay functions to the live driver in the subclass
-  virtual void clearNative() = 0;
-  virtual void setRowNative(byte line) = 0;
-  virtual size_t writeNative(uint8_t b) = 0;
-  virtual bool isBusy() = 0;
-
-  unsigned long lastScrollTime = 0;
-  int8_t hotRow = 0;
-  int8_t hotCol = 0;
-  int8_t topRow = 0;
-  int8_t slot = 0;
-  int8_t rowFirst = -1;
-  int8_t rowNext = 0;
-  int8_t charIndex = 0;
-  char buffer[MAX_LCD_COLS + 1];
-  char* bufferPointer = 0;
-  bool done = false;
-
-  char rowBuffer[MAX_LCD_ROWS][MAX_LCD_COLS + 1];
-};
-
-#endif