More uint type fixes

Added disable logic

.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,9 @@ 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

.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"
-    }
-}

CommandDistributor.cpp

@@ -1,6 +1,9 @@
 /*
- *  © 2020,Gregor Baues,  Chris Harlow. All rights reserved.
- *  
+ *  © 2022 Harald Barth
+ *  © 2020-2021 Chris Harlow
+ *  © 2020 Gregor Baues
+ *  All rights reserved.
+ *
  *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
@@ -16,16 +19,221 @@
  *  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)
+// 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;
+}
+#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::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%d<;>%d\n"), 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 CD_HANDLE_RING
+  WiThrottle::markForBroadcast(sp->loco);
+#endif
+}
+
+void  CommandDistributor::broadcastPower() {
+  bool main=TrackManager::getMainPower()==POWERMODE::ON;
+  bool prog=TrackManager::getProgPower()==POWERMODE::ON;
+  bool join=TrackManager::isJoined();
+  const FSH * reason=F("");
+  char state='1';
+  if (main && prog && join) reason=F(" JOIN");
+  else if (main && prog);
+  else if (main) reason=F(" MAIN");
+  else if (prog) reason=F(" PROG");
+  else state='0';
+  broadcastReply(COMMAND_TYPE, F("<p%c%S>\n"),state,reason);
+#ifdef CD_HANDLE_RING
+  broadcastReply(WITHROTTLE_TYPE, F("PPA%c\n"), main?'1':'0');
+#endif
+  LCD(2,F("Power %S%S"),state=='1'?F("On"):F("Off"),reason);  
+}
+
+void CommandDistributor::broadcastText(const FSH * msg) {
+  broadcastReply(COMMAND_TYPE, F("<I %S>\n"),msg);
+#ifdef CD_HANDLE_RING
+  broadcastReply(WITHROTTLE_TYPE, F("Hm%S\n"), msg);
+#endif
+}
+
+void CommandDistributor::broadcastTrackState(const FSH* format,byte trackLetter,int16_t dcAddr) {
+  broadcastReply(COMMAND_TYPE, format,trackLetter,dcAddr);
 }

CommandDistributor.h

@@ -1,6 +1,9 @@
 /*
- *  © 2020,Gregor Baues,  Chris Harlow. All rights reserved.
- *  
+ *  © 2022 Harald Barth
+ *  © 2020-2021 Chris Harlow
+ *  © 2020 Gregor Baues
+ *  All rights reserved.
+ *
  *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
@@ -20,13 +23,38 @@
 #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);
 private:
-   static DCCEXParser * parser;
+  enum clientType: byte {NONE_TYPE,COMMAND_TYPE,WITHROTTLE_TYPE};
+  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 broadcastSensor(int16_t id, bool value);
+  static void broadcastTurnout(int16_t id, bool isClosed);
+  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 broadcastText(const FSH * msg);
+  static void broadcastTrackState(const FSH* format,byte trackLetter,int16_t dcAddr);
+  template<typename... Targs> static void broadcastReply(clientType type, Targs... msg);
+  static void forget(byte clientId);
+  
 };
 
 #endif

CommandStation-EX.ino

@@ -1,33 +1,37 @@
 ////////////////////////////////////////////////////////////////////////////////////
-//  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
+ *  All rights reserved.
+ *
  *  This file is part of CommandStation-EX
  *
  *  This is free software: you can redistribute it and/or modify
@@ -45,11 +49,21 @@
  */
 
 #include "DCCEX.h"
+#include "Display_Implementation.h"
 
-// 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
 
 void setup()
 {
@@ -57,59 +71,63 @@ 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")); 
-    }   
+// Initialise HAL layer before reading EEprom or setting up MotorDrivers 
+  IODevice::begin();
+
+  DISPLAY_START (
+    // This block is still executed for DIAGS if display not in use
+    LCD(0,F("DCC-EX v%S"),F(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);
 #endif // WIFI_ON
+#else
+  // ESP32 needs wifi on always
+  WifiESP::setup(WIFI_SSID, WIFI_PASSWORD, WIFI_HOSTNAME, IP_PORT, WIFI_CHANNEL);
+#endif // ARDUINO_ARCH_ESP32
 
 #if ETHERNET_ON
   EthernetInterface::setup();
 #endif // ETHERNET_ON
-
+  
+  // 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();
   // 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)
+  TrackManager::Setup(MOTOR_SHIELD_TYPE);
+
+  // Start RMFT aka EX-RAIL (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();
-  }
 
-  // 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.
+
+  // 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()
@@ -121,33 +139,41 @@ void loop()
   DCC::loop();
 
   // Responsibility 2: handle any incoming commands on USB connection
-  serialParser.loop(Serial);
+  SerialManager::loop();
 
-// Responsibility 3: Optionally handle any incoming WiFi traffic
+  // 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,48 @@
 #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 void begin(const FSH * motorShieldName);
   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 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 bool setFn(int cab, int16_t functionNumber, bool on);
+  static void changeFn(int cab, int16_t functionNumber);
   static int  getFn(int cab, int16_t functionNumber);
+  static uint32_t getFunctionMap(int cab);
   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 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
@@ -112,19 +85,11 @@ public:
   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;
@@ -132,45 +97,25 @@ private:
     byte groupFlags;
     unsigned long 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 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 +130,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,469 @@
+/*
+ *  © 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 int DCCACK::minAckPulseDuration = 2000; // micros
+unsigned int 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 int 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) {
+  ackManagerRejoin=TrackManager::isJoined();
+  if (ackManagerRejoin) {
+    // Change from JOIN must zero resets packet.
+    TrackManager::setJoin(false);
+    DCCWaveform::progTrack.clearResets();
+  }
+
+  progDriver=TrackManager::getProgDriver();
+  if (progDriver==NULL) {
+    TrackManager::setJoin(ackManagerRejoin);
+    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 %uus and %uus"),
+			  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=%uuS 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.   
+}
+
+
+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 ITSKIP:
+          if (!ackReceived) break;
+          // SKIP opcodes until SKIPTARGET found
+          while (opcode!=SKIPTARGET) {
+            ackManagerProg++;
+            opcode=GETFLASH(ackManagerProg);
+          }
+          break;
+     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);
+    }
+}
+
+
+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,156 @@
+/*
+ *  © 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
+  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 int i) {
+	minAckPulseDuration = i;
+    }
+    static inline void setMaxAckPulseDuration(unsigned int 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 int ackPulseDuration;  // micros
+    static unsigned long ackPulseStart; // micros
+
+    static unsigned int minAckPulseDuration ; // micros
+    static unsigned int 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

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,25 @@
 #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 "EXRAIL.h"
     
 #endif

DCCEXParser.cpp

@@ -1,6 +1,13 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
- *  © 2020, Harald Barth.
+ *  © 2022 Paul M Antoine
+ *  © 2021 Neil McKechnie
+ *  © 2021 Mike S
+ *  © 2021 Herb Morton
+ *  © 2020-2022 Harald Barth
+ *  © 2020-2021 M Steve Todd
+ *  © 2020-2021 Fred Decker
+ *  © 2020-2021 Chris Harlow
+ *  All rights reserved.
  *  
  *  This file is part of CommandStation-EX
  *
@@ -24,24 +31,25 @@
 #include "Turnouts.h"
 #include "Outputs.h"
 #include "Sensors.h"
-#include "freeMemory.h"
 #include "GITHUB_SHA.h"
 #include "version.h"
 #include "defines.h"
-
+#include "CommandDistributor.h"
 #include "EEStore.h"
 #include "DIAG.h"
-#include <avr/wdt.h>
+#include "TrackManager.h"
+#include "DCCTimer.h"
+#include "EXRAIL2.h"
+
+// This macro can't be created easily as a portable function because the
+// flashlist requires a far pointer for high flash access. 
+#define SENDFLASHLIST(stream,flashList)                 \
+    for (int16_t i=0;;i+=sizeof(flashList[0])) {                            \
+        int16_t value=GETHIGHFLASHW(flashList,i);       \
+        if (value==0) break;                            \
+        StringFormatter::send(stream,F(" %d"),value);   \
+    }                                   
 
-////////////////////////////////////////////////////////////////////////////////
-//
-// Figure out if we have enough memory for advanced features
-//
-#if defined(ARDUINO_AVR_UNO) || defined(ARDUINO_AVR_NANO)
-// nope
-#else
-#define HAS_ENOUGH_MEMORY
-#endif
 
 // These keywords are used in the <1> command. The number is what you get if you use the keyword as a parameter.
 // To discover new keyword numbers , use the <$ YOURKEYWORD> command
@@ -56,7 +64,9 @@ const int16_t HASH_KEYWORD_ON = 2657;
 const int16_t HASH_KEYWORD_DCC = 6436;
 const int16_t HASH_KEYWORD_SLOW = -17209;
 const int16_t HASH_KEYWORD_PROGBOOST = -6353;
+#ifndef DISABLE_EEPROM
 const int16_t HASH_KEYWORD_EEPROM = -7168;
+#endif
 const int16_t HASH_KEYWORD_LIMIT = 27413;
 const int16_t HASH_KEYWORD_MAX = 16244;
 const int16_t HASH_KEYWORD_MIN = 15978;
@@ -65,73 +75,38 @@ const int16_t HASH_KEYWORD_RETRY = 25704;
 const int16_t HASH_KEYWORD_SPEED28 = -17064;
 const int16_t HASH_KEYWORD_SPEED128 = 25816;
 const int16_t HASH_KEYWORD_SERVO=27709;
+const int16_t HASH_KEYWORD_TT=2688;
 const int16_t HASH_KEYWORD_VPIN=-415;
-const int16_t HASH_KEYWORD_C=67;
-const int16_t HASH_KEYWORD_T=84;
+const int16_t HASH_KEYWORD_A='A';
+const int16_t HASH_KEYWORD_C='C';
+const int16_t HASH_KEYWORD_G='G';
+const int16_t HASH_KEYWORD_I='I';
+const int16_t HASH_KEYWORD_R='R';
+const int16_t HASH_KEYWORD_T='T';
+const int16_t HASH_KEYWORD_X='X';
 const int16_t HASH_KEYWORD_LCN = 15137;
 const int16_t HASH_KEYWORD_HAL = 10853;
 const int16_t HASH_KEYWORD_SHOW = -21309;
 const int16_t HASH_KEYWORD_ANIN = -10424;
 const int16_t HASH_KEYWORD_ANOUT = -26399;
-#ifdef HAS_ENOUGH_MEMORY
 const int16_t HASH_KEYWORD_WIFI = -5583;
 const int16_t HASH_KEYWORD_ETHERNET = -30767;
 const int16_t HASH_KEYWORD_WIT = 31594;
-#endif
 
 int16_t DCCEXParser::stashP[MAX_COMMAND_PARAMS];
 bool DCCEXParser::stashBusy;
-
 Print *DCCEXParser::stashStream = NULL;
 RingStream *DCCEXParser::stashRingStream = NULL;
 byte DCCEXParser::stashTarget=0;
 
-// This is a JMRI command parser, one instance per incoming stream
+// This is a JMRI command parser.
 // It doesnt know how the string got here, nor how it gets back.
 // It knows nothing about hardware or tracks... it just parses strings and
 // calls the corresponding DCC api.
 // Non-DCC things like turnouts, pins and sensors are handled in additional JMRI interface classes.
 
-DCCEXParser::DCCEXParser() {}
-void DCCEXParser::flush()
-{
-    if (Diag::CMD)
-        DIAG(F("Buffer flush"));
-    bufferLength = 0;
-    inCommandPayload = false;
-}
 
-void DCCEXParser::loop(Stream &stream)
-{
-    while (stream.available())
-    {
-        if (bufferLength == MAX_BUFFER)
-        {
-            flush();
-        }
-        char ch = stream.read();
-        if (ch == '<')
-        {
-            inCommandPayload = true;
-            bufferLength = 0;
-            buffer[0] = '\0';
-        }
-        else if (ch == '>')
-        {
-            buffer[bufferLength] = '\0';
-            parse(&stream, buffer, NULL); // Parse this (No ringStream for serial)
-            inCommandPayload = false;
-            break;
-        }
-        else if (inCommandPayload)
-        {
-            buffer[bufferLength++] = ch;
-        }
-    }
-    Sensor::checkAll(&stream); // Update and print changes
-}
-
-int16_t DCCEXParser::splitValues(int16_t result[MAX_COMMAND_PARAMS], const byte *cmd)
+int16_t DCCEXParser::splitValues(int16_t result[MAX_COMMAND_PARAMS], const byte *cmd, bool usehex)
 {
     byte state = 1;
     byte parameterCount = 0;
@@ -169,11 +144,16 @@ int16_t DCCEXParser::splitValues(int16_t result[MAX_COMMAND_PARAMS], const byte
         case 3: // building a parameter
             if (hot >= '0' && hot <= '9')
             {
-                runningValue = 10 * runningValue + (hot - '0');
+                runningValue = (usehex?16:10) * runningValue + (hot - '0');
                 break;
             }
             if (hot >= 'a' && hot <= 'z') hot=hot-'a'+'A'; // uppercase a..z
-            if (hot >= 'A' && hot <= 'Z')
+            if (usehex && hot>='A' && hot<='F') {
+                // treat A..F as hex not keyword
+                runningValue = 16 * runningValue + (hot - 'A' + 10);
+                break;
+            }
+            if (hot=='_' || (hot >= 'A' && hot <= 'Z'))
             {
                 // Since JMRI got modified to send keywords in some rare cases, we need this
                 // Super Kluge to turn keywords into a hash value that can be recognised later
@@ -190,69 +170,12 @@ int16_t DCCEXParser::splitValues(int16_t result[MAX_COMMAND_PARAMS], const byte
     return parameterCount;
 }
 
-int16_t DCCEXParser::splitHexValues(int16_t result[MAX_COMMAND_PARAMS], const byte *cmd)
-{
-    byte state = 1;
-    byte parameterCount = 0;
-    int16_t runningValue = 0;
-    const byte *remainingCmd = cmd + 1; // skips the opcode
-    
-    // clear all parameters in case not enough found
-    for (int16_t i = 0; i < MAX_COMMAND_PARAMS; i++)
-        result[i] = 0;
-
-    while (parameterCount < MAX_COMMAND_PARAMS)
-    {
-        byte hot = *remainingCmd;
-
-        switch (state)
-        {
-
-        case 1: // skipping spaces before a param
-            if (hot == ' ')
-                break;
-            if (hot == '\0' || hot == '>')
-                return parameterCount;
-            state = 2;
-            continue;
-
-        case 2: // checking first hex digit
-            runningValue = 0;
-            state = 3;
-            continue;
-
-        case 3: // building a parameter
-            if (hot >= '0' && hot <= '9')
-            {
-                runningValue = 16 * runningValue + (hot - '0');
-                break;
-            }
-            if (hot >= 'A' && hot <= 'F')
-            {
-                runningValue = 16 * runningValue + 10 + (hot - 'A');
-                break;
-            }
-            if (hot >= 'a' && hot <= 'f')
-            {
-                runningValue = 16 * runningValue + 10 + (hot - 'a');
-                break;
-            }
-            if (hot==' ' || hot=='>' || hot=='\0') { 
-               result[parameterCount] = runningValue;
-               parameterCount++;
-               state = 1;
-               continue;
-            }
-            return -1; // invalid hex digit
-        }
-        remainingCmd++;
-    }
-    return parameterCount;
-}
-
-FILTER_CALLBACK DCCEXParser::filterCallback = 0;
+extern __attribute__((weak))  void myFilter(Print * stream, byte & opcode, byte & paramCount, int16_t p[]);
+FILTER_CALLBACK DCCEXParser::filterCallback = myFilter;
 FILTER_CALLBACK DCCEXParser::filterRMFTCallback = 0;
 AT_COMMAND_CALLBACK DCCEXParser::atCommandCallback = 0;
+
+// deprecated
 void DCCEXParser::setFilter(FILTER_CALLBACK filter)
 {
     filterCallback = filter;
@@ -268,25 +191,42 @@ void DCCEXParser::setAtCommandCallback(AT_COMMAND_CALLBACK callback)
 
 // Parse an F() string 
 void DCCEXParser::parse(const FSH * cmd) {
-      int size=strlen_P((char *)cmd)+1; 
+      DIAG(F("SETUP(\"%S\")"),cmd);
+      int size=STRLEN_P((char *)cmd)+1; 
       char buffer[size];
-      strcpy_P(buffer,(char *)cmd);
-      parse(&Serial,(byte *)buffer,NULL);
+      STRCPY_P(buffer,(char *)cmd);
+      parse(&USB_SERIAL,(byte *)buffer,NULL);
 }
 
 // See documentation on DCC class for info on this section
 
-void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
+void DCCEXParser::parse(Print *stream,  byte *com,  RingStream *ringStream) {
+  // This function can get stings of the form "<C OMM AND>" or "C OMM AND"
+  // found is true first after the leading "<" has been passed
+  bool found = (com[0] != '<');
+  for (byte *c=com; c[0] != '\0'; c++) {
+    if (found) {
+      parseOne(stream, c,  ringStream);
+      found=false;
+    }
+    if (c[0] == '<')
+      found = true;
+  }
+}
+
+void DCCEXParser::parseOne(Print *stream, byte *com, RingStream * ringStream)
 {
+#ifndef DISABLE_EEPROM
     (void)EEPROM; // tell compiler not to warn this is unused
+#endif
     if (Diag::CMD)
         DIAG(F("PARSING:%s"), com);
     int16_t p[MAX_COMMAND_PARAMS];
     while (com[0] == '<' || com[0] == ' ')
         com++; // strip off any number of < or spaces
-    byte params = splitValues(p, com);
     byte opcode = com[0];
-
+    byte params = splitValues(p, com, opcode=='M' || opcode=='P');
+    
     if (filterCallback)
         filterCallback(stream, opcode, params, p);
     if (filterRMFTCallback && opcode!='\0')
@@ -299,10 +239,23 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
         return; // filterCallback asked us to ignore
     case 't':   // THROTTLE <t [REGISTER] CAB SPEED DIRECTION>
     {
+        if (params==1) {  // <t cab>  display state
+        
+        int16_t slot=DCC::lookupSpeedTable(p[0],false);
+        if (slot>=0) {
+            DCC::LOCO * sp=&DCC::speedTable[slot];
+            StringFormatter::send(stream,F("<l %d %d %d %l>\n"),
+			sp->loco,slot,sp->speedCode,sp->functions);
+            }
+        else // send dummy state speed 0 fwd no functions. 
+            StringFormatter::send(stream,F("<l %d -1 128 0>\n"),p[0]);
+        return; 
+        }
+        
         int16_t cab;
         int16_t tspeed;
         int16_t direction;
-
+        
         if (params == 4)
         { // <t REGISTER CAB SPEED DIRECTION>
             cab = p[1];
@@ -334,10 +287,9 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
             break; // invalid direction code
 
         DCC::setThrottle(cab, tspeed, direction);
-        if (params == 4)
+        if (params == 4) // send obsolete format T response
             StringFormatter::send(stream, F("<T %d %d %d>\n"), p[0], p[2], p[3]);
-        else
-            StringFormatter::send(stream, F("<O>\n"));
+        // speed change will be broadcast anyway in new <l > format
         return;
     }
     case 'f': // FUNCTION <f CAB BYTE1 [BYTE2]>
@@ -345,33 +297,44 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
             return;
         break;
 
-    case 'a': // ACCESSORY <a ADDRESS SUBADDRESS ACTIVATE> or <a LINEARADDRESS ACTIVATE>
+    case 'a': // ACCESSORY <a ADDRESS SUBADDRESS ACTIVATE [ONOFF]> or <a LINEARADDRESS ACTIVATE>
         { 
           int address;
           byte subaddress;
           byte activep;
+          byte onoff;
           if (params==2) { // <a LINEARADDRESS ACTIVATE>
               address=(p[0] - 1) / 4 + 1;
               subaddress=(p[0] - 1)  % 4;
-              activep=1;        
+              activep=1;
+              onoff=2; // send both
           }
           else if (params==3) { // <a ADDRESS SUBADDRESS ACTIVATE>
               address=p[0];
               subaddress=p[1];
-              activep=2;        
+              activep=2;
+              onoff=2; // send both
+          }
+          else if (params==4) { // <a ADDRESS SUBADDRESS ACTIVATE ONOFF>
+              address=p[0];
+              subaddress=p[1];
+              activep=2;
+	      if ((p[3] < 0) || (p[3] > 1))        // invalid onoff    0|1
+		break;
+              onoff=p[3];
           }
           else break; // invalid no of parameters
           
           if (
-             ((address & 0x01FF) != address)      // invalid address (limit 9 bits ) 
-          || ((subaddress & 0x03) != subaddress)  // invalid subaddress (limit 2 bits ) 
-          || ((p[activep]  & 0x01) != p[activep]) // invalid activate 0|1
-          ) break; 
+	      ((address & 0x01FF) != address)      // invalid address (limit 9 bits)
+           || ((subaddress & 0x03) != subaddress)  // invalid subaddress (limit 2 bits)
+           || (p[activep] > 1) || (p[activep] < 0) // invalid activate 0|1
+	      ) break;
           // Honour the configuration option (config.h) which allows the <a> command to be reversed
-#ifdef DCC_ACCESSORY_RCN_213
-          DCC::setAccessory(address, subaddress,p[activep]==0);
+#ifdef DCC_ACCESSORY_COMMAND_REVERSE
+          DCC::setAccessory(address, subaddress,p[activep]==0,onoff);
 #else
-          DCC::setAccessory(address, subaddress,p[activep]==1);
+          DCC::setAccessory(address, subaddress,p[activep]==1,onoff);
 #endif
         }
         return;
@@ -381,6 +344,20 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
             return;
         break;
 
+    case 'z':  // direct pin manipulation
+        if (p[0]==0) break; 
+        if (params==1) {  // <z vpin | -vpin> 
+            if (p[0]>0) IODevice::write(p[0],HIGH);
+            else IODevice::write(-p[0],LOW);
+            return;
+        }
+        if (params>=2 && params<=4) { // <z vpin ana;og profile duration> 
+            // unused params default to 0           
+            IODevice::writeAnalogue(p[0],p[1],p[2],p[3]);
+            return;
+        }
+        break; 
+
     case 'Z': // OUTPUT <Z ...>
         if (parseZ(stream, params, p))
             return;
@@ -401,9 +378,10 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
 
     case 'M': // WRITE TRANSPARENT DCC PACKET MAIN <M REG X1 ... X9>
     case 'P': // WRITE TRANSPARENT DCC PACKET PROG <P REG X1 ... X9>
-        // Re-parse the command using a hex-only splitter
-        params=splitHexValues(p,com)-1; // drop REG
-        if (params<1) break;  
+        // NOTE: this command was parsed in HEX instead of decimal
+        params--; // drop REG
+        if (params<1) break;
+	if (params > MAX_PACKET_SIZE) break;
         {
           byte packet[params];
           for (int i=0;i<params;i++) {
@@ -419,7 +397,9 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
                 break;
         if (params == 1) // <W id> Write new loco id (clearing consist and managing short/long)
             DCC::setLocoId(p[0],callback_Wloco);
-        else // WRITE CV ON PROG <W CV VALUE [CALLBACKNUM] [CALLBACKSUB]>
+        else if (params == 4)  // WRITE CV ON PROG <W CV VALUE [CALLBACKNUM] [CALLBACKSUB]>
+            DCC::writeCVByte(p[0], p[1], callback_W4);
+        else  // WRITE CV ON PROG <W CV VALUE>
             DCC::writeCVByte(p[0], p[1], callback_W);
         return;
 
@@ -447,6 +427,13 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
         return;
 
     case 'R': // READ CV ON PROG
+        if (params == 1)
+        { // <R CV> -- uses verify callback
+            if (!stashCallback(stream, p, ringStream))
+                break;
+            DCC::verifyCVByte(p[0], 0, callback_Vbyte);
+            return;
+        }
         if (params == 3)
         { // <R CV CALLBACKNUM CALLBACKSUB>
             if (!stashCallback(stream, p, ringStream))
@@ -463,68 +450,76 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
         }
         break;
 
-    case '1': // POWERON <1   [MAIN|PROG]>
-    case '0': // POWEROFF <0 [MAIN | PROG] >
-        if (params > 1)
-            break;
+    case '1': // POWERON <1   [MAIN|PROG|JOIN]>
         {
-            POWERMODE mode = opcode == '1' ? POWERMODE::ON : POWERMODE::OFF;
-            DCC::setProgTrackSyncMain(false); // Only <1 JOIN> will set this on, all others set it off
-            if (params == 0 ||
-		(MotorDriver::commonFaultPin && p[0] != HASH_KEYWORD_JOIN)) // commonFaultPin prevents individual track handling
-            {
-                DCCWaveform::mainTrack.setPowerMode(mode);
-                DCCWaveform::progTrack.setPowerMode(mode);
-		if (mode == POWERMODE::OFF)
-		  DCC::setProgTrackBoost(false);  // Prog track boost mode will not outlive prog track off
-                StringFormatter::send(stream, F("<p%c>\n"), opcode);
-		        LCD(2, F("p%c"), opcode);
-                return;
-            }
-            switch (p[0])
-            {
-            case HASH_KEYWORD_MAIN:
-                DCCWaveform::mainTrack.setPowerMode(mode);
-                StringFormatter::send(stream, F("<p%c MAIN>\n"), opcode);
-	            LCD(2, F("p%c MAIN"), opcode);
-                return;
-
-            case HASH_KEYWORD_PROG:
-                DCCWaveform::progTrack.setPowerMode(mode);
-		if (mode == POWERMODE::OFF)
-		  DCC::setProgTrackBoost(false);  // Prog track boost mode will not outlive prog track off
-                StringFormatter::send(stream, F("<p%c PROG>\n"), opcode);
-		        LCD(2, F("p%c PROG"), opcode);
-                return;
-            case HASH_KEYWORD_JOIN:
-                DCCWaveform::mainTrack.setPowerMode(mode);
-                DCCWaveform::progTrack.setPowerMode(mode);
-                if (mode == POWERMODE::ON)
-                {
-                    DCC::setProgTrackSyncMain(true);
-                    StringFormatter::send(stream, F("<p1 JOIN>\n"), opcode);
-		            LCD(2, F("p1 JOIN"));
-                }
-                else
-		        {
-                    StringFormatter::send(stream, F("<p0>\n"));
-		            LCD(2, F("p0"));
-	    	    }
-                return;
-            }
-            break;
+        bool main=false;
+        bool prog=false;
+        bool join=false;
+        if (params > 1) break;
+        if (params==0 || MotorDriver::commonFaultPin) { // <1> or tracks can not be handled individually
+            main=true;
+            prog=true;
         }
+	if (params==1) {
+	  if (p[0] == HASH_KEYWORD_JOIN) {  // <1 JOIN>
+            main=true;
+            prog=true;
+            join=true;
+	  }
+	  else if (p[0]==HASH_KEYWORD_MAIN) { // <1 MAIN>
+            main=true;
+	  }
+	  else if (p[0]==HASH_KEYWORD_PROG) { // <1 PROG>
+            prog=true;
+	  }
+	  else break; // will reply <X>
+	}
+        if (main) TrackManager::setMainPower(POWERMODE::ON);
+        if (prog) TrackManager::setProgPower(POWERMODE::ON);
+        TrackManager::setJoin(join);
+
+        CommandDistributor::broadcastPower();
         return;
+        }
+
+    case '0': // POWEROFF <0 [MAIN | PROG] >
+        {
+        bool main=false;
+        bool prog=false;
+        if (params > 1) break;
+        if (params==0 || MotorDriver::commonFaultPin) { // <0> or tracks can not be handled individually
+	  main=true;
+	  prog=true;
+        }
+	if (params==1) {
+	  if (p[0]==HASH_KEYWORD_MAIN) { // <0 MAIN>
+	    main=true;
+	  }
+	  else if (p[0]==HASH_KEYWORD_PROG) { // <0 PROG>
+	    prog=true;
+	  }
+	  else break; // will reply <X>
+	}
+
+        if (main) TrackManager::setMainPower(POWERMODE::OFF);
+        if (prog) {
+            TrackManager::progTrackBoosted=false;  // Prog track boost mode will not outlive prog track off
+            TrackManager::setProgPower(POWERMODE::OFF);
+        }
+        TrackManager::setJoin(false);
+
+        CommandDistributor::broadcastPower();
+        return;
+        }
 
     case '!': // ESTOP ALL  <!>
-        DCC::setThrottle(0,1,1); // this broadcasts speed 1(estop) and sets all reminders to speed 1. 
+        DCC::setThrottle(0,1,1); // this broadcasts speed 1(estop) and sets all reminders to speed 1.
         return;
 
     case 'c': // SEND METER RESPONSES <c>
-        //                               <c MeterName value C/V unit min max res warn>
-        StringFormatter::send(stream, F("<c CurrentMAIN %d C Milli 0 %d 1 %d>\n"), DCCWaveform::mainTrack.getCurrentmA(), 
-            DCCWaveform::mainTrack.getMaxmA(), DCCWaveform::mainTrack.getTripmA());
-        StringFormatter::send(stream, F("<a %d>\n"), DCCWaveform::mainTrack.get1024Current()); //'a' message deprecated, remove once JMRI 4.22 is available
+        // No longer useful because of multiple tracks See <JG> and <JI>
+        if (params>0) break;
+        TrackManager::reportObsoleteCurrent(stream);
         return;
 
     case 'Q': // SENSORS <Q>
@@ -532,14 +527,13 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
         return;
 
     case 's': // <s>
-        StringFormatter::send(stream, F("<p%d>\n"), DCCWaveform::mainTrack.getPowerMode() == POWERMODE::ON);
         StringFormatter::send(stream, F("<iDCC-EX V-%S / %S / %S G-%S>\n"), F(VERSION), F(ARDUINO_TYPE), DCC::getMotorShieldName(), F(GITHUB_SHA));
+        CommandDistributor::broadcastPower(); // <s> is the only "get power status" command we have
         Turnout::printAll(stream); //send all Turnout states
-        Output::printAll(stream);  //send all Output  states
         Sensor::printAll(stream);  //send all Sensor  states
-        // TODO Send stats of  speed reminders table
         return;       
 
+#ifndef DISABLE_EEPROM
     case 'E': // STORE EPROM <E>
         EEStore::store();
         StringFormatter::send(stream, F("<e %d %d %d>\n"), EEStore::eeStore->data.nTurnouts, EEStore::eeStore->data.nSensors, EEStore::eeStore->data.nOutputs);
@@ -549,7 +543,7 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
         EEStore::clear();
         StringFormatter::send(stream, F("<O>\n"));
         return;
-
+#endif
     case ' ': // < >
         StringFormatter::send(stream, F("\n"));
         return;
@@ -559,6 +553,11 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
             return;
         return;
 
+    case '=': // <= Track manager control  >
+        if (TrackManager::parseJ(stream, params, p))
+            return;
+        break;
+
     case '#': // NUMBER OF LOCOSLOTS <#>
         StringFormatter::send(stream, F("<# %d>\n"), MAX_LOCOS);
         return;
@@ -570,19 +569,108 @@ void DCCEXParser::parse(Print *stream, byte *com, RingStream * ringStream)
         return;
 
     case 'F': // New command to call the new Loco Function API <F cab func 1|0>
+        if(params!=3) break; 
         if (Diag::CMD)
             DIAG(F("Setting loco %d F%d %S"), p[0], p[1], p[2] ? F("ON") : F("OFF"));
-        DCC::setFn(p[0], p[1], p[2] == 1);
-        return;
+        if (DCC::setFn(p[0], p[1], p[2] == 1)) return;
+	break;
 
+#if WIFI_ON
     case '+': // Complex Wifi interface command (not usual parse)
-        if (atCommandCallback) {
-          DCCWaveform::mainTrack.setPowerMode(POWERMODE::OFF);
-          DCCWaveform::progTrack.setPowerMode(POWERMODE::OFF);
-          atCommandCallback(com);
+        if (atCommandCallback && !ringStream) {
+          TrackManager::setPower(POWERMODE::OFF);
+          atCommandCallback((HardwareSerial *)stream,com);
           return;
         }
         break;
+#endif 
+
+    case 'J' : // throttle info access
+        {
+            if ((params<1) | (params>3)) break; // <J>
+            //if ((params<1) | (params>2)) break; // <J>
+            int16_t id=(params==2)?p[1]:0;
+            switch(p[0]) {
+                case HASH_KEYWORD_C: // <JC mmmm nn> sets time and speed
+                    if (params==1) { // <JC> returns latest time
+                        int16_t x = CommandDistributor::retClockTime();
+                        StringFormatter::send(stream, F("<jC %d>\n"), x);
+                        return;
+                    }
+                    CommandDistributor::setClockTime(p[1], p[2], 1);
+                    return;
+                
+                case HASH_KEYWORD_G: // <JG> current gauge limits
+                    if (params>1) break;
+                    TrackManager::reportGauges(stream);   // <g limit...limit>     
+                    return;
+                
+                case HASH_KEYWORD_I: // <JI> current values
+                    if (params>1) break;
+                    TrackManager::reportCurrent(stream);   // <g limit...limit>     
+                    return;
+
+                case HASH_KEYWORD_A: // <JA> returns automations/routes
+                    StringFormatter::send(stream, F("<jA"));
+                    if (params==1) {// <JA>
+#ifdef EXRAIL_ACTIVE
+                        SENDFLASHLIST(stream,RMFT2::routeIdList)
+                        SENDFLASHLIST(stream,RMFT2::automationIdList)
+#endif
+                    }
+                    else {  // <JA id>
+                        StringFormatter::send(stream,F(" %d %c \"%S\""), 
+                                        id, 
+#ifdef EXRAIL_ACTIVE
+                                        RMFT2::getRouteType(id), // A/R
+                                        RMFT2::getRouteDescription(id)
+#else  
+                                        'X',F("")
+#endif                                        
+                                        );
+                    }
+                    StringFormatter::send(stream, F(">\n"));      
+                    return; 
+            case HASH_KEYWORD_R: // <JR> returns rosters 
+                StringFormatter::send(stream, F("<jR"));
+#ifdef EXRAIL_ACTIVE
+                if (params==1) {
+                    SENDFLASHLIST(stream,RMFT2::rosterIdList)
+                }
+                else StringFormatter::send(stream,F(" %d \"%S\" \"%S\""), 
+                    id, RMFT2::getRosterName(id), RMFT2::getRosterFunctions(id));
+#endif          
+                StringFormatter::send(stream, F(">\n"));      
+                return; 
+            case HASH_KEYWORD_T: // <JT> returns turnout list 
+                StringFormatter::send(stream, F("<jT"));
+                if (params==1) { // <JT>
+                    for ( Turnout * t=Turnout::first(); t; t=t->next()) { 
+                        if (t->isHidden()) continue;          
+                        StringFormatter::send(stream, F(" %d"),t->getId());
+                    }
+                }
+                else { // <JT id>
+                    Turnout * t=Turnout::get(id);
+                    if (!t || t->isHidden()) StringFormatter::send(stream, F(" %d X"),id);
+                    else {
+		      const FSH *tdesc = NULL;
+#ifdef EXRAIL_ACTIVE
+		      tdesc = RMFT2::getTurnoutDescription(id);
+#endif
+		      if (tdesc == NULL)
+			tdesc = F("");
+		      StringFormatter::send(stream, F(" %d %c \"%S\""),
+					    id,t->isThrown()?'T':'C',
+					    tdesc);
+		    }
+                }
+                StringFormatter::send(stream, F(">\n"));
+                return;
+            default: break;    
+            }  // switch(p[1])
+        break; // case J
+        }
 
     default: //anything else will diagnose and drop out to <X>
         DIAG(F("Opcode=%c params=%d"), opcode, params);
@@ -644,43 +732,39 @@ bool DCCEXParser::parseZ(Print *stream, int16_t params, int16_t p[])
 //===================================
 bool DCCEXParser::parsef(Print *stream, int16_t params, int16_t p[])
 {
-    // JMRI sends this info in DCC message format but it's not exactly
-    //      convenient for other processing
-    if (params == 2)
-    {
-        byte instructionField = p[1] & 0xE0;   // 1110 0000
-        if (instructionField == 0x80)          // 1000 0000 Function group 1
-        {
-	    // Shuffle bits from order F0 F4 F3 F2 F1 to F4 F3 F2 F1 F0 
-            byte normalized = (p[1] << 1 & 0x1e) | (p[1] >> 4 & 0x01);
-            funcmap(p[0], normalized, 0, 4);
-        }
-        else if (instructionField == 0xA0)     // 1010 0000 Function group 2
-        {
-	    if (p[1] & 0x10)                   // 0001 0000 Bit selects F5toF8 / F9toF12
-		funcmap(p[0], p[1], 5, 8);
-	    else
-		funcmap(p[0], p[1], 9, 12);
-        }
-    }
-    if (params == 3)
-    {
-        if (p[1] == 222)
-            funcmap(p[0], p[2], 13, 20);
-        else if (p[1] == 223)
-            funcmap(p[0], p[2], 21, 28);
-    }
-    (void)stream; // NO RESPONSE
-    return true;
+  // JMRI sends this info in DCC message format but it's not exactly
+  // convenient for other processing
+  if (params == 2) {
+    byte instructionField = p[1] & 0xE0;   // 1110 0000
+    if (instructionField == 0x80) {        // 1000 0000 Function group 1
+      // Shuffle bits from order F0 F4 F3 F2 F1 to F4 F3 F2 F1 F0
+      byte normalized = (p[1] << 1 & 0x1e) | (p[1] >> 4 & 0x01);
+      return (funcmap(p[0], normalized, 0, 4));
+    } else if (instructionField == 0xA0) { // 1010 0000 Function group 2
+      if (p[1] & 0x10)                     // 0001 0000 Bit selects F5toF8 / F9toF12
+	return (funcmap(p[0], p[1], 5, 8));
+      else
+	return (funcmap(p[0], p[1], 9, 12));
+    } 
+  }
+  if (params == 3) {
+    if (p[1] == 222) {
+      return (funcmap(p[0], p[2], 13, 20));
+    } else if (p[1] == 223) {
+      return (funcmap(p[0], p[2], 21, 28));
+    } 
+  }
+  (void)stream; // NO RESPONSE
+  return false;
 }
 
-void DCCEXParser::funcmap(int16_t cab, byte value, byte fstart, byte fstop)
+bool DCCEXParser::funcmap(int16_t cab, byte value, byte fstart, byte fstop)
 {
-    for (int16_t i = fstart; i <= fstop; i++)
-    {
-        DCC::setFn(cab, i, value & 1);
-        value >>= 1;
-    }
+  for (int16_t i = fstart; i <= fstop; i++) {
+    if (! DCC::setFn(cab, i, value & 1)) return false;
+    value >>= 1;
+  }
+  return true;
 }
 
 //===================================
@@ -689,15 +773,7 @@ bool DCCEXParser::parseT(Print *stream, int16_t params, int16_t p[])
     switch (params)
     {
     case 0: // <T>  list turnout definitions
-    {
-        bool gotOne = false;
-        for (Turnout *tt = Turnout::first(); tt != NULL; tt = tt->next())
-        {
-            gotOne = true;
-            tt->print(stream);
-        }
-        return gotOne; // will <X> if none found
-    }
+        return Turnout::printAll(stream); // will <X> if none found
 
     case 1: // <T id>  delete turnout
         if (!Turnout::remove(p[0]))
@@ -718,14 +794,19 @@ bool DCCEXParser::parseT(Print *stream, int16_t params, int16_t p[])
             case HASH_KEYWORD_T:
               state= false;
               break;
-            default:
-              return false;  // Invalid parameter
+            case HASH_KEYWORD_X:
+	    {
+              Turnout *tt = Turnout::get(p[0]);
+              if (tt) {
+                tt->print(stream);
+                return true;
+              }
+              return false;
+	    }
+            default: // Invalid parameter
+	      return false;
           }
           if (!Turnout::setClosed(p[0], state)) return false;
-
-          // Send acknowledgement to caller if the command was not received over Serial
-          // (acknowledgement messages on Serial are sent by the Turnout class).
-          if (stream != &Serial) Turnout::printState(p[0], stream);
           return true;
         }
 
@@ -808,23 +889,23 @@ bool DCCEXParser::parseD(Print *stream, int16_t params, int16_t p[])
         return true;
 
     case HASH_KEYWORD_RAM: // <D RAM>
-        StringFormatter::send(stream, F("Free memory=%d\n"), minimumFreeMemory());
+        StringFormatter::send(stream, F("Free memory=%d\n"), DCCTimer::getMinimumFreeMemory());
         break;
 
     case HASH_KEYWORD_ACK: // <D ACK ON/OFF> <D ACK [LIMIT|MIN|MAX|RETRY] Value>
 	if (params >= 3) {
 	    if (p[1] == HASH_KEYWORD_LIMIT) {
-	      DCCWaveform::progTrack.setAckLimit(p[2]);
+	      DCCACK::setAckLimit(p[2]);
 	      LCD(1, F("Ack Limit=%dmA"), p[2]);  // <D ACK LIMIT 42>
 	    } else if (p[1] == HASH_KEYWORD_MIN) {
-	      DCCWaveform::progTrack.setMinAckPulseDuration(p[2]);
-	      LCD(0, F("Ack Min=%dus"), p[2]);  //   <D ACK MIN 1500>
+	      DCCACK::setMinAckPulseDuration(p[2]);
+	      LCD(0, F("Ack Min=%uus"), p[2]);  //   <D ACK MIN 1500>
 	    } else if (p[1] == HASH_KEYWORD_MAX) {
-	      DCCWaveform::progTrack.setMaxAckPulseDuration(p[2]);
-	      LCD(0, F("Ack Max=%dus"), p[2]);  //   <D ACK MAX 9000>
+	      DCCACK::setMaxAckPulseDuration(p[2]);
+	      LCD(0, F("Ack Max=%uus"), p[2]);  //   <D ACK MAX 9000>
 	    } else if (p[1] == HASH_KEYWORD_RETRY) {
 	      if (p[2] >255) p[2]=3;
-	      LCD(0, F("Ack Retry=%d Sum=%d"), p[2], DCC::setAckRetry(p[2]));  //   <D ACK RETRY 2>
+	      LCD(0, F("Ack Retry=%d Sum=%d"), p[2], DCCACK::setAckRetry(p[2]));  //   <D ACK RETRY 2>
 	    }
 	} else {
 	  StringFormatter::send(stream, F("Ack diag %S\n"), onOff ? F("on") : F("off"));
@@ -855,20 +936,20 @@ bool DCCEXParser::parseD(Print *stream, int16_t params, int16_t p[])
 #endif
 
     case HASH_KEYWORD_PROGBOOST:
-        DCC::setProgTrackBoost(true);
-	      return true;
+        TrackManager::progTrackBoosted=true;
+	    return true;
 
     case HASH_KEYWORD_RESET:
-        {
-          wdt_enable( WDTO_15MS); // set Arduino watchdog timer for 15ms 
-          delay(50);            // wait for the prescaller time to expire          
-          break; // and <X> if we didnt restart 
-        }
-        
+        DCCTimer::reset();
+        break; // and <X> if we didnt restart 
+    
+
+#ifndef DISABLE_EEPROM
     case HASH_KEYWORD_EEPROM: // <D EEPROM NumEntries>
 	if (params >= 2)
 	    EEStore::dump(p[1]);
 	return true;
+#endif
 
     case HASH_KEYWORD_SPEED28:
         DCC::setGlobalSpeedsteps(28);
@@ -886,16 +967,22 @@ bool DCCEXParser::parseD(Print *stream, int16_t params, int16_t p[])
         break;
 
     case HASH_KEYWORD_ANIN:   // <D ANIN vpin>  Display analogue input value
-        DIAG(F("VPIN=%d value=%d"), p[1], IODevice::readAnalogue(p[1]));
+        DIAG(F("VPIN=%u value=%d"), p[1], IODevice::readAnalogue(p[1]));
         break;
 
-#if !defined(IO_MINIMAL_HAL)
+#if !defined(IO_NO_HAL)
     case HASH_KEYWORD_HAL: 
         if (p[1] == HASH_KEYWORD_SHOW) 
           IODevice::DumpAll();
+        else if (p[1] == HASH_KEYWORD_RESET)
+          IODevice::reset();
         break;
 #endif
 
+    case HASH_KEYWORD_TT:     // <D TT vpin steps activity>
+        IODevice::writeAnalogue(p[1], p[2], params>3 ? p[3] : 0);
+        break;
+
     default: // invalid/unknown
         break;
     }
@@ -931,7 +1018,14 @@ void DCCEXParser::commitAsyncReplyStream() {
 void DCCEXParser::callback_W(int16_t result)
 {
     StringFormatter::send(getAsyncReplyStream(),
-          F("<r%d|%d|%d %d>\n"), stashP[2], stashP[3], stashP[0], result == 1 ? stashP[1] : -1);
+          F("<r %d %d>\n"), stashP[0], result == 1 ? stashP[1] : -1);
+    commitAsyncReplyStream();
+}
+
+void DCCEXParser::callback_W4(int16_t result)
+{
+    StringFormatter::send(getAsyncReplyStream(),
+	  F("<r%d|%d|%d %d>\n"), stashP[2], stashP[3], stashP[0], result == 1 ? stashP[1] : -1);
     commitAsyncReplyStream();
 }
 
@@ -958,10 +1052,21 @@ void DCCEXParser::callback_R(int16_t result)
     commitAsyncReplyStream();
 }
 
-void DCCEXParser::callback_Rloco(int16_t result)
-{
-    StringFormatter::send(getAsyncReplyStream(), F("<r %d>\n"), result);
-    commitAsyncReplyStream();
+void DCCEXParser::callback_Rloco(int16_t result) {
+  const FSH * detail;
+  if (result<=0) {
+    detail=F("<r %d>\n");
+  } else {
+    bool longAddr=result & LONG_ADDR_MARKER;        //long addr
+    if (longAddr)
+      result = result^LONG_ADDR_MARKER;
+    if (longAddr && result <= HIGHEST_SHORT_ADDR)
+      detail=F("<r LONG %d UNSUPPORTED>\n");
+    else
+      detail=F("<r %d>\n");
+  }
+  StringFormatter::send(getAsyncReplyStream(), detail, result);
+  commitAsyncReplyStream();
 }
 
 void DCCEXParser::callback_Wloco(int16_t result)

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
  *
@@ -23,15 +26,14 @@
 #include "RingStream.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);
@@ -40,17 +42,13 @@ struct DCCEXParser
    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], const 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 parseD(Print * stream,  int16_t params, int16_t p[]);
 
      static Print * getAsyncReplyStream();
      static void commitAsyncReplyStream();
@@ -61,8 +59,9 @@ 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);
@@ -72,7 +71,8 @@ struct DCCEXParser
     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 bool funcmap(int16_t cab, byte value, byte fstart, byte fstop);
+    static void sendFlashList(Print * stream,const int16_t flashList[]);
 
 };
 

DCCRMT.cpp

@@ -0,0 +1,235 @@
+/*
+ *  © 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)
+#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"
+
+// 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;
+  if (isMain) {
+    ch = 0;
+    plen = PREAMBLE_BITS_MAIN;
+  } else {
+    ch = 2;
+    plen = PREAMBLE_BITS_PROG;
+  }
+    
+  // 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 = 2; // With longest DCC packet 11 inc checksum (future expansion)
+                            // number of bits needed is 22preamble + start +
+                            // 11*9 + extrazero + EOT = 124
+                            // 2 mem block of 64 RMT items should be enough
+
+  ESP_ERROR_CHECK(rmt_config(&config));
+  addPin(pins.invpin, true);
+  /*
+  // test: config another gpio pin
+  gpio_num_t gpioNum = (gpio_num_t)(pin-1);
+  PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[gpioNum], PIN_FUNC_GPIO);
+  gpio_set_direction(gpioNum, GPIO_MODE_OUTPUT);
+  gpio_matrix_out(gpioNum, RMT_SIG_OUT0_IDX, 0, 0);
+  */
+  
+  // 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;
+  dataReady = true;
+  dataRepeat = repeatCount+1;         // repeatCount of 0 means send once
+  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)         // 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,66 @@
+/*
+ *  © 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 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 Paul M. Antoine
+ *  © 2021 Mike S
+ *  © 2021-2022 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,72 @@ 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();
+// 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 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:
+  // init does add the pin to the list of scanned pins (if this
+  // platform's implementation scans pins) and returns the first
+  // read value. It is 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();
+  // begin is called for any setup that must be done before
+  // scan can be called.
+  static void begin();
+private:
+  // On platforms that scan, it is called from waveform ISR
+  // only on a regular basis.
+  static void scan();
+  // bit array of used pins (max 16)
+  static uint16_t usedpins;
+  // cached analog values (malloc:ed to actual number of ADC channels)
+  static int *analogvals;
+  // ids to scan (new way)
+  static byte *idarr;
+  // friend so that we can call scan() and begin()
+  friend class DCCWaveform;
+  };
 #endif

DCCTimerAVR.cpp

@@ -0,0 +1,234 @@
+/*
+ *  © 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 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"
+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
+#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();
+  }
+
+// 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() {
+  wdt_enable( WDTO_15MS); // set Arduino watchdog timer for 15ms 
+  delay(50);            // wait for the prescaller time to expire
+
+}
+
+#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;
+int * ADCee::analogvals = NULL;
+byte *ADCee::idarr = 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;
+  byte n;
+  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));
+    for (n=0 ; n < NUM_ADC_INPUTS; n++) // set unreasonable value at startup as marker
+      analogvals[n] = -32768;           // 16 bit int min value
+    idarr = (byte *)calloc(NUM_ADC_INPUTS+1, sizeof(byte));  // +1 for terminator value
+    for (n=0 ; n <= NUM_ADC_INPUTS; n++)
+      idarr[n] = 255;                   // set 255 as end of array marker
+  }
+  analogvals[id] = value; // store before enable by idarr[n]
+  for (n=0 ; n <= NUM_ADC_INPUTS; n++) {
+    if (idarr[n] == 255) {
+      idarr[n] = id;
+      break;
+    }
+  }
+  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) {
+  (void)fromISR; // AVR does ignore this arg
+  uint8_t id = pin - A0;
+  int a;
+  // we do not need to check (analogvals == NULL)
+  // because usedpins would still be 0 in that case
+  noInterrupts();
+  a = analogvals[id];
+  interrupts();
+  return a;
+}
+/*
+ * Scan function that is called from interrupt
+ */
+#pragma GCC push_options
+#pragma GCC optimize ("-O3")
+void ADCee::scan() {
+  static byte num = 0;       // index into id array
+  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[idarr[num]] = (high << 8) | low;
+    waiting = false;
+  }
+  if (!waiting) {
+    // cycle around in-use analogue pins
+    num++;
+    if (idarr[num] == 255)
+      num = 0;
+    // start new ADC aquire on id
+#if defined(ADCSRB) && defined(MUX5)
+    if (ADCusesHighPort) {     // if we ever have started to use high pins)
+      if (idarr[num] > 7)              // if we use a high ADC pin
+	bitSet(ADCSRB, MUX5);  // set MUX5 bit
+      else
+	bitClear(ADCSRB, MUX5);
+    }
+#endif
+    ADMUX = (1 << REFS0) | (idarr[num] & 0x07); // select AVCC as reference and set MUX
+    bitSet(ADCSRA, ADSC);               // start conversion
+    waiting = true;
+  }
+}
+#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,178 @@
+/*
+ *  © 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
+#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();
+}
+int ADCee::init(uint8_t pin) {
+  pinMode(pin, ANALOG);
+  adc1_config_width(ADC_WIDTH_BIT_12);
+  adc1_config_channel_atten(pinToADC1Channel(pin),ADC_ATTEN_DB_11);
+  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 //ESP32
+

DCCTimerMEGAAVR.cpp

@@ -0,0 +1,155 @@
+/*
+ *  © 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();
+  }
+
+  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){}
+}
+
+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,277 @@
+/*
+ *  © 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();
+}
+
+// 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) {};
+}
+
+#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,371 @@
+/*
+ *  © 2023 Neil McKechnie
+ *  © 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 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"
+
+#if defined(ARDUINO_NUCLEO_F411RE)
+// Nucleo-64 boards don't have Serial1 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 Serial1 defined by default
+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.
+#elif defined(ARDUINO_NUCLEO_F412ZG) || defined(ARDUINO_NUCLEO_F429ZI) || defined(ARDUINO_NUCLEO_F446ZE)
+// Nucleo-144 boards don't have Serial1 defined by default
+HardwareSerial Serial1(PG9, PG14);  // Rx=PG9, Tx=PG14 -- D0, D1 - F412ZG/F446ZE
+#else
+#warning Serial1 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;
+// Let's use STM32's timer #11 until disabused of this notion
+// Timer #11 is used for "servo" library, but as DCC-EX is not using
+// this libary, we should be free and clear.
+HardwareTimer timer(TIM11);
+
+// Timer IRQ handler
+void Timer11_Handler() {
+  interruptHandler();
+}
+
+void DCCTimer::begin(INTERRUPT_CALLBACK callback) {
+  interruptHandler=callback;
+  noInterrupts();
+
+  // adc_set_sample_rate(ADC_SAMPLETIME_480CYCLES);
+  timer.pause();
+  timer.setPrescaleFactor(1);
+//  timer.setOverflow(CLOCK_CYCLES * 2);
+  timer.setOverflow(DCC_SIGNAL_TIME, MICROSEC_FORMAT);
+  timer.attachInterrupt(Timer11_Handler);
+  timer.refresh();
+  timer.resume();
+
+  interrupts();
+}
+
+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 *)0x1FFF7A10;
+  volatile uint32_t *serno2 = (volatile uint32_t *)0x1FFF7A14;
+  // volatile uint32_t *serno3 = (volatile uint32_t *)0x1FFF7A18;
+
+  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) {};
+}
+
+#define NUM_ADC_INPUTS NUM_ANALOG_INPUTS
+
+// TODO: may need to use uint32_t on STMF4xx variants with > 16 analog inputs!
+uint16_t ADCee::usedpins = 0;
+int * ADCee::analogvals = NULL;
+uint32_t * analogchans = NULL;
+bool adc1configured = false;
+
+int16_t ADCee::ADCmax() {
+  return 4095;
+}
+
+int ADCee::init(uint8_t pin) {
+  uint8_t id = pin - A0;
+  int value = 0;
+  PinName stmpin = digitalPin[analogInputPin[id]];
+  uint32_t stmgpio = stmpin / 16; // 16-bits per GPIO port group on STM32
+  uint32_t adcchan =  STM_PIN_CHANNEL(pinmap_function(stmpin, PinMap_ADC)); // find ADC channel (only valid for ADC1!)
+  GPIO_TypeDef * gpioBase;
+
+  // Port config - find which port we're on and power it up
+  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;
+  }
+
+  // Set pin mux mode to analog input
+  gpioBase->MODER |= (0b011 << (stmpin << 1)); // Set pin mux to analog mode
+
+  // Set the sampling rate for that analog input
+  if (adcchan < 10)
+    ADC1->SMPR2 |= (0b111 << (adcchan * 3)); // Channel sampling rate 480 cycles
+  else
+    ADC1->SMPR1 |= (0b111 << ((adcchan - 10) * 3)); // Channel sampling rate 480 cycles
+
+  // Read the inital ADC value for this analog input
+  ADC1->SQR3 = adcchan;           // 1st conversion in regular sequence
+  ADC1->CR2 |= (1 << 30);         // Start 1st conversion SWSTART
+  while(!(ADC1->SR & (1 << 1)));  // Wait until conversion is complete
+  value = ADC1->DR;               // Read value from register
+
+  if (analogvals == NULL)
+  {
+    analogvals = (int *)calloc(NUM_ADC_INPUTS+1, sizeof(int));
+    analogchans = (uint32_t *)calloc(NUM_ADC_INPUTS+1, sizeof(uint32_t));
+  }
+  analogvals[id] = value;     // Store sampled value
+  analogchans[id] = adcchan;  // Keep track of which ADC channel is used for reading this pin
+  usedpins |= (1 << id);      // This pin is now ready
+
+  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 - A0;
+  // 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;
+
+  if (waiting) {
+    // look if we have a result
+    if (!(ADC1->SR & (1 << 1)))
+      return; // no result, continue to wait
+    // found value
+    analogvals[id] = ADC1->DR;
+    // 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
+        ADC1->SQR3 = analogchans[id]; //1st conversion in regular sequence
+        ADC1->CR2 |= (1 << 30); //Start 1st conversion SWSTART
+	      // 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();
+  //ADC1 config sequence
+  // TODO: currently defaults to ADC1, may need more to handle other members of STM32F4xx family
+  RCC->APB2ENR |= (1 << 8); //Enable ADC1 clock (Bit8) 
+  // 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
+  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
+  interrupts();
+}
+#endif

DCCTimerTEENSY.cpp

@@ -0,0 +1,171 @@
+/*
+ *  © 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);
+  }
+
+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;
+}
+
+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,43 +21,52 @@
  *  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") );
+// 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};
+
+const byte idlePacket[] = {0xFF, 0x00, 0xFF};
+const byte resetPacket[] = {0x00, 0x00, 0x00};
+
+
+// For each state of the wave  nextState=stateTransform[currentState] 
+const WAVE_STATE stateTransform[]={
+   /* WAVE_START   -> */ WAVE_PENDING,
+   /* WAVE_MID_1   -> */ WAVE_START,
+   /* WAVE_HIGH_0  -> */ WAVE_MID_0,
+   /* WAVE_MID_0   -> */ WAVE_LOW_0,
+   /* WAVE_LOW_0   -> */ WAVE_START,
+   /* WAVE_PENDING (should not happen) -> */ WAVE_PENDING};
+
+// For each state of the wave, signal pin is HIGH or LOW   
+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(bool ackManagerActive) {
-  mainTrack.checkPowerOverload(false);
-  progTrack.checkPowerOverload(ackManagerActive);
+void DCCWaveform::loop() {
+ // empty placemarker in case ESP32 needs something here 
 }
 
 #pragma GCC push_options
@@ -62,24 +75,26 @@ 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];
+  byte sigProg=TrackManager::progTrackSyncMain? sigMain : signalTransform[progTrack.state];
   
   // Set the signal state for both tracks
-  mainTrack.motorDriver->setSignal(sigMain);
-  progTrack.motorDriver->setSignal(sigProg);
-  
+  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 if (progTrack.ackPending) progTrack.checkAck();
+  else DCCACK::checkAck(progTrack.getResets());
 
 }
-#pragma GCC push_options
+#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.
@@ -87,9 +102,6 @@ void DCCWaveform::interruptHandler() {
 // 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;
@@ -101,105 +113,10 @@ DCCWaveform::DCCWaveform( byte preambleBits, bool isMain) {
   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; 
 }
 
 
-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[]={
-   /* WAVE_START   -> */ WAVE_PENDING,
-   /* WAVE_MID_1   -> */ WAVE_START,
-   /* WAVE_HIGH_0  -> */ WAVE_MID_0,
-   /* WAVE_MID_0   -> */ WAVE_LOW_0,
-   /* WAVE_LOW_0   -> */ WAVE_START,
-   /* WAVE_PENDING (should not happen) -> */ WAVE_PENDING};
 
-// For each state of the wave, signal pin is HIGH or LOW   
-const bool DCCWaveform::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};
-        
 #pragma GCC push_options
 #pragma GCC optimize ("-O3")
 void DCCWaveform::interrupt2() {
@@ -212,7 +129,7 @@ void DCCWaveform::interrupt2() {
     remainingPreambles--;
     // 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); 
+    DCCTimer::updateMinimumFreeMemoryISR(22); 
     return;
   }
 
@@ -245,21 +162,20 @@ void DCCWaveform::interrupt2() {
         transmitLength = pendingLength;
         transmitRepeats = pendingRepeats;
         packetPending = false;
-        sentResetsSincePacket=0;
+        clearResets();
       }
       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++;
+        if (getResets() < 250) sentResetsSincePacket++; // only place to increment (private!)
       }
     }
   }  
 }
 #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 +191,90 @@ 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::getPacketPending() {
+  return packetPending;
 }
+#endif
 
-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
+#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;
 }
-
-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; 
+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 */
     }
-      
-    int current=motorDriver->getCurrentRaw();
-    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;
+  }
+  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);
     }
-    
-    // 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 
+  }
 }
-#pragma GCC pop_options
+
+void DCCWaveform::schedulePacket(const byte buffer[], byte byteCount, byte repeats) {
+  if (byteCount > MAX_PACKET_SIZE) return; // allow for chksum
+  
+  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;
+  // The resets will be zero not only now but as well repeats packets into the future
+  clearResets(repeats+1);
+  {
+    int ret;
+    do {
+      if(isMainTrack) {
+	if (rmtMainChannel != NULL)
+	  ret = rmtMainChannel->RMTfillData(pendingPacket, pendingLength, pendingRepeats);
+      } else {
+	if (rmtProgChannel != NULL)
+	  ret = rmtProgChannel->RMTfillData(pendingPacket, pendingLength, pendingRepeats);
+      }
+    } while(ret > 0);
+  }
+}
+
+bool DCCWaveform::getPacketPending() {
+  if(isMainTrack) {
+    if (rmtMainChannel == NULL)
+      return true;
+    return rmtMainChannel->busy();
+  } else {
+    if (rmtProgChannel == NULL)
+      return true;
+    return rmtProgChannel->busy();
+  }
+}
+void IRAM_ATTR DCCWaveform::loop() {
+  DCCACK::checkAck(progTrack.getResets());
+}
+#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-2021 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,70 @@
 #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.
 
+
 // 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};
 
-
 // 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);
+    bool getPacketPending();
+    
+  private:
+#ifndef ARDUINO_ARCH_ESP32
     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:
-    
-// 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];
-  
+#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 +101,9 @@ class DCCWaveform {
     byte pendingPacket[MAX_PACKET_SIZE+1]; // +1 for checksum
     byte pendingLength;
     byte pendingRepeats;
-    int  lastCurrent;
-    static int progTripValue;
-    int maxmA;
-    int tripmA;
-    
-    // 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,219 @@
+/*
+ *  © 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;
+          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

@@ -16,15 +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/>.
  */
-#ifndef LCDDisplay_h
-#define LCDDisplay_h
+#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
+#if !defined(MAX_MSG_SIZE)
+#define MAX_MSG_SIZE 20 
 #endif
 
 // Set default scroll mode (overridable in config.h)
@@ -32,50 +32,46 @@
 #define SCROLLMODE 1
 #endif
 
-// This class is created in LCDisplay_Implementation.h
+// This class is created in Display_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
+class Display : public DisplayInterface {
+public:
+  Display(DisplayDevice *deviceDriver);
+  static const int MAX_CHARACTER_ROWS = 8;
+  static const int MAX_CHARACTER_COLS = MAX_MSG_SIZE;
+  static const long DISPLAY_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;
+private:
+  DisplayDevice *_deviceDriver;
 
   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];
+  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 done = false;
+  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();
 
-  char rowBuffer[MAX_LCD_ROWS][MAX_LCD_COLS + 1];
 };
 
 #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,34 @@
 
 #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) {}
 
+#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

ESP32-fixes.cpp

@@ -0,0 +1,61 @@
+/*
+ *  © 2022 Harald Barth
+ *  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/>.
+ */
+#ifdef ARDUINO_ARCH_ESP32
+#include <Arduino.h>
+#include "ESP32-fixes.h"
+
+#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 DCCEXanalogWriteFrequency(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 DCCEXanalogWrite(uint8_t pin, int value) {
+  if (pin < SOC_GPIO_PIN_COUNT) {
+    if (pin_to_channel[pin] == 0) {
+      if (!cnt_channel) {
+          log_e("No more PWM channels available! All %u already used", LEDC_CHANNELS);
+          return;
+      }
+      pin_to_channel[pin] = --cnt_channel;
+      ledcAttachPin(pin, cnt_channel);
+      ledcSetup(cnt_channel, 1000, 8);
+    } else {
+      ledcAttachPin(pin, pin_to_channel[pin]);
+    }
+    ledcWrite(pin_to_channel[pin], value);
+  }
+}
+#endif

ESP32-fixes.h

@@ -1,8 +1,8 @@
 /*
- *  © 2020, Harald Barth
- *  © 2021, Neil McKechnie
+ *  © 2022 Harald Barth
+ *  All rights reserved.
  *  
- *  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 +17,10 @@
  *  You should have received a copy of the GNU General Public License
  *  along with CommandStation.  If not, see <https://www.gnu.org/licenses/>.
  */
-
-#ifndef freeMemory_h
-#define freeMemory_h
-void updateMinimumFreeMemory(unsigned char extraBytes=0);
-int minimumFreeMemory();
+#ifdef ARDUINO_ARCH_ESP32
+#pragma once
+#include <Arduino.h>
+void DCCEXanalogWriteFrequency(uint8_t pin, uint32_t frequency);
+void DCCEXanalogWrite(uint8_t pin, int value);
 #endif
+

EXRAIL.h

@@ -1,8 +1,8 @@
-#ifndef RMFT_H
-#define RMFT_H
+#ifndef EXRAIL_H
+#define EXRAIL_H
 
-#if defined(RMFT_ACTIVE)
- #include "RMFT2.h"
+#if defined(EXRAIL_ACTIVE)
+ #include "EXRAIL2.h"
 
   class RMFT {
     public:
@@ -10,7 +10,7 @@
       static void inline loop() {RMFT2::loop();}
   };
 
-  #include "RMFTMacros.h"
+  #include "EXRAILMacros.h"
   
 #else 
   // Dummy RMFT 

EXRAIL2.h

@@ -0,0 +1,207 @@
+/*
+ *  © 2021 Neil McKechnie
+ *  © 2020-2022 Chris Harlow
+ *  © 2023 Harald Barth
+ *  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"
+   
+// 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_FWD,OPCODE_REV,OPCODE_SPEED,OPCODE_INVERT_DIRECTION,
+             OPCODE_RESERVE,OPCODE_FREE,
+             OPCODE_AT,OPCODE_AFTER,OPCODE_AUTOSTART,
+             OPCODE_ATGTE,OPCODE_ATLT,
+             OPCODE_ATTIMEOUT1,OPCODE_ATTIMEOUT2,
+             OPCODE_LATCH,OPCODE_UNLATCH,OPCODE_SET,OPCODE_RESET,
+             OPCODE_ENDIF,OPCODE_ELSE,
+             OPCODE_DELAY,OPCODE_DELAYMINS,OPCODE_DELAYMS,OPCODE_RANDWAIT,
+             OPCODE_FON,OPCODE_FOFF,OPCODE_XFON,OPCODE_XFOFF,
+             OPCODE_RED,OPCODE_GREEN,OPCODE_AMBER,OPCODE_DRIVE,
+             OPCODE_SERVO,OPCODE_SIGNAL,OPCODE_TURNOUT,OPCODE_WAITFOR,
+             OPCODE_PAD,OPCODE_FOLLOW,OPCODE_CALL,OPCODE_RETURN,
+             OPCODE_JOIN,OPCODE_UNJOIN,OPCODE_READ_LOCO1,OPCODE_READ_LOCO2,OPCODE_POM,
+             OPCODE_START,OPCODE_SETLOCO,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_ONACTIVATE,OPCODE_ONDEACTIVATE,
+             OPCODE_ROSTER,OPCODE_KILLALL,
+             OPCODE_ROUTE,OPCODE_AUTOMATION,OPCODE_SEQUENCE,
+             OPCODE_ENDTASK,OPCODE_ENDEXRAIL,
+             OPCODE_SET_TRACK,
+             OPCODE_ONRED,OPCODE_ONAMBER,OPCODE_ONGREEN,
+             OPCODE_ONCHANGE,
+             OPCODE_ONCLOCKTIME,
+             OPCODE_ONTIME,
+
+             // 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
+             };
+
+// 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_serial,thrunge_parse,
+  thrunge_serial1, thrunge_serial2, thrunge_serial3,
+  thrunge_serial4, thrunge_serial5, thrunge_serial6,
+  thrunge_lcn, 
+  thrunge_lcd,  // Must be last!!
+  };
+
+
+ 
+  // 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 add(int16_t lookup, int16_t result);
+    int16_t find(int16_t value);
+  private:
+     int16_t m_size;
+     int16_t m_loaded;
+     int16_t * m_lookupArray;
+     int16_t * m_resultArray;     
+};
+
+ 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 const int16_t SERVO_SIGNAL_FLAG=0x4000;
+    static const int16_t ACTIVE_HIGH_SIGNAL_FLAG=0x2000;
+    static const int16_t DCC_SIGNAL_FLAG=0x1000;
+    static const int16_t SIGNAL_ID_MASK=0x0FFF;
+ // 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);
+    
+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 bool isSignal(int16_t id,char rag); 
+    static int16_t getSignalSlot(int16_t id);
+    static void setTurnoutHiddenState(Turnout * t);
+    static LookList* LookListLoader(OPCODE op1,
+                      OPCODE op2=OPCODE_ENDEXRAIL,OPCODE op3=OPCODE_ENDEXRAIL);
+    static void handleEvent(const FSH* reason,LookList* handlers, int16_t id);
+    static uint16_t getOperand(int progCounter,byte n);
+    static RMFT2 * loopTask;
+    static RMFT2 * pausingTask;
+    void delayMe(long millisecs);
+    void driveLoco(byte speedo);
+    bool readSensor(uint16_t sensorId);
+    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  HIGHFLASH  byte RouteCode[];
+   static const  HIGHFLASH  int16_t SignalDefinitions[];
+   static byte flags[MAX_FLAGS];
+   static LookList * sequenceLookup;
+   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;
+    
+  // 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
+    };
+    bool timeoutFlag;
+    byte  taskId;
+    
+    uint16_t loco;
+    bool forward;
+    bool invert;
+    byte speedo;
+    int onEventStartPosition;
+    byte stackDepth;
+    int callStack[MAX_STACK_DEPTH];
+};
+#endif

EXRAIL2MacroReset.h

@@ -0,0 +1,264 @@
+/*
+ *  © 2020-2022 Chris Harlow. All rights reserved.
+ *  © 2023 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/>.
+ */
+
+// 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 ALIAS
+#undef AMBER
+#undef ANOUT
+#undef AT
+#undef ATGTE
+#undef ATLT
+#undef ATTIMEOUT
+#undef AUTOMATION 
+#undef AUTOSTART
+#undef BROADCAST
+#undef CALL 
+#undef CLOSE 
+#undef DCC_SIGNAL
+#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 FADE
+#undef FOFF
+#undef FOLLOW 
+#undef FON 
+#undef FORGET
+#undef FREE 
+#undef FWD 
+#undef GREEN
+#undef HAL
+#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 IFRE
+#undef INVERT_DIRECTION 
+#undef JOIN 
+#undef KILLALL
+#undef LATCH 
+#undef LCD 
+#undef SCREEN
+#undef LCN 
+#undef MOVETT
+#undef ONACTIVATE
+#undef ONACTIVATEL
+#undef ONAMBER
+#undef ONDEACTIVATE
+#undef ONDEACTIVATEL 
+#undef ONCLOSE
+#undef ONTIME
+#undef ONCLOCKTIME
+#undef ONGREEN
+#undef ONRED
+#undef ONTHROW 
+#undef ONCHANGE
+#undef PARSE
+#undef PAUSE
+#undef PIN_TURNOUT 
+#undef PRINT
+#undef POM
+#undef POWEROFF
+#undef POWERON
+#undef READ_LOCO 
+#undef RED 
+#undef RESERVE 
+#undef RESET 
+#undef RESUME 
+#undef RETURN 
+#undef REV
+#undef ROSTER 
+#undef ROUTE
+#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 SETLOCO 
+#undef SIGNAL 
+#undef SIGNALH 
+#undef SPEED 
+#undef START 
+#undef STOP 
+#undef THROW  
+#undef TURNOUT 
+#undef UNJOIN
+#undef UNLATCH 
+#undef VIRTUAL_SIGNAL
+#undef VIRTUAL_TURNOUT
+#undef WAITFOR
+#undef XFOFF
+#undef XFON
+
+#ifndef RMFT2_UNDEF_ONLY
+#define ACTIVATE(addr,subaddr)
+#define ACTIVATEL(addr)
+#define AFTER(sensor_id)
+#define ALIAS(name,value...)
+#define AMBER(signal_id)
+#define ANOUT(vpin,value,param1,param2)
+#define AT(sensor_id)
+#define ATGTE(sensor_id,value) 
+#define ATLT(sensor_id,value) 
+#define ATTIMEOUT(sensor_id,timeout_ms)
+#define AUTOMATION(id,description) 
+#define AUTOSTART
+#define BROADCAST(msg)
+#define CALL(route) 
+#define CLOSE(id) 
+#define DCC_SIGNAL(id,add,subaddr)
+#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 FADE(pin,value,ms)
+#define FOFF(func)
+#define FOLLOW(route) 
+#define FON(func)
+#define FORGET
+#define FREE(blockid) 
+#define FWD(speed) 
+#define GREEN(signal_id)
+#define HAL(haltype,params...)
+#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 IFRE(sensor_id,value)
+#define INVERT_DIRECTION 
+#define JOIN 
+#define KILLALL
+#define LATCH(sensor_id) 
+#define LCD(row,msg)
+#define SCREEN(display,row,msg)
+#define LCN(msg) 
+#define MOVETT(id,steps,activity)
+#define ONACTIVATE(addr,subaddr)
+#define ONACTIVATEL(linear)
+#define ONAMBER(signal_id) 
+#define ONTIME(value)
+#define ONCLOCKTIME(hours,mins)
+#define ONDEACTIVATE(addr,subaddr)
+#define ONDEACTIVATEL(linear) 
+#define ONCLOSE(turnout_id)
+#define ONGREEN(signal_id) 
+#define ONRED(signal_id) 
+#define ONTHROW(turnout_id) 
+#define ONCHANGE(sensor_id)
+#define PAUSE
+#define PIN_TURNOUT(id,pin,description...) 
+#define PRINT(msg) 
+#define PARSE(msg)
+#define POM(cv,value)
+#define POWEROFF
+#define POWERON
+#define READ_LOCO 
+#define RED(signal_id) 
+#define RESERVE(blockid) 
+#define RESET(pin) 
+#define RESUME 
+#define RETURN 
+#define REV(speed) 
+#define ROUTE(id,description)
+#define ROSTER(cab,name,funcmap...)
+#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) 
+#define SET_TRACK(track,mode)
+#define SETLOCO(loco) 
+#define SIGNAL(redpin,amberpin,greenpin) 
+#define SIGNALH(redpin,amberpin,greenpin) 
+#define SPEED(speed) 
+#define START(route) 
+#define STOP 
+#define THROW(id)  
+#define TURNOUT(id,addr,subaddr,description...) 
+#define UNJOIN 
+#define UNLATCH(sensor_id) 
+#define VIRTUAL_SIGNAL(id) 
+#define VIRTUAL_TURNOUT(id,description...) 
+#define WAITFOR(pin)
+#define XFOFF(cab,func)
+#define XFON(cab,func)
+#endif

EXRAILMacros.h

@@ -0,0 +1,385 @@
+/*
+ *  © 2021 Neil McKechnie
+ *  © 2020-2022 Chris Harlow
+ *  © 2023 Harald Barth
+ *  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 turnout description as HIDDEN 
+#define HIDDEN "\x01"
+
+// helper macro to strip leading zeros off time inputs
+// (10#mins)%100)
+#define STRIP_ZERO(value) 10##value%100
+
+// Pass 1 Implements aliases 
+#include "EXRAIL2MacroReset.h"
+#undef ALIAS
+#define ALIAS(name,value...) const int name= 1##value##0 ==10 ? -__COUNTER__  : value##0/10; 
+#include "myAutomation.h"
+
+// Pass 1h Implements HAL macro by creating exrailHalSetup function 
+#include "EXRAIL2MacroReset.h"
+#undef HAL
+#define HAL(haltype,params...)  haltype::create(params);
+void exrailHalSetup() {
+   #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"
+    0}; 
+// 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"
+    0}; 
+
+// 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 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;\
+      } 
+
+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 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 6: Roster IDs (count)
+#include "EXRAIL2MacroReset.h"
+#undef ROSTER
+#define ROSTER(cabid,name,funcmap...) +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"
+   0};
+
+// 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 F("");
+} 
+
+// Pass 8 Signal definitions
+#include "EXRAIL2MacroReset.h"
+#undef SIGNAL
+#define SIGNAL(redpin,amberpin,greenpin) redpin,redpin,amberpin,greenpin, 
+#undef SIGNALH
+#define SIGNALH(redpin,amberpin,greenpin) redpin | RMFT2::ACTIVE_HIGH_SIGNAL_FLAG,redpin,amberpin,greenpin, 
+#undef SERVO_SIGNAL
+#define SERVO_SIGNAL(vpin,redval,amberval,greenval) vpin | RMFT2::SERVO_SIGNAL_FLAG,redval,amberval,greenval, 
+#undef DCC_SIGNAL
+#define DCC_SIGNAL(id,addr,subaddr) id | RMFT2::DCC_SIGNAL_FLAG,addr,subaddr,0,
+#undef VIRTUAL_SIGNAL
+#define VIRTUAL_SIGNAL(id) id,0,0,0,
+
+const  HIGHFLASH  int16_t RMFT2::SignalDefinitions[] = {
+    #include "myAutomation.h"
+    0,0,0,0 };
+
+// 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) OPCODE_AT,V(sensor_id),OPCODE_AFTER,V(sensor_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 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 BROADCAST(msg) PRINT(msg)
+#define CALL(route) OPCODE_CALL,V(route),
+#define CLOSE(id)  OPCODE_CLOSE,V(id),
+#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 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 
+#define FADE(pin,value,ms) OPCODE_SERVO,V(pin),OPCODE_PAD,V(value),OPCODE_PAD,V(PCA9685::ProfileType::UseDuration|PCA9685::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 FWD(speed) OPCODE_FWD,V(speed),
+#define GREEN(signal_id) OPCODE_GREEN,V(signal_id),
+#define HAL(haltype,params...)
+#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,
+#define IFRE(sensor_id,value) OPCODE_IFRE,V(sensor_id),OPCODE_PAD,V(value),
+#define INVERT_DIRECTION OPCODE_INVERT_DIRECTION,0,0,
+#define JOIN OPCODE_JOIN,0,0,
+#define KILLALL OPCODE_KILLALL,0,0,
+#define LATCH(sensor_id) OPCODE_LATCH,V(sensor_id),
+#define LCD(id,msg) PRINT(msg)
+#define SCREEN(display,id,msg) PRINT(msg)
+#define LCN(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 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 ONTIME(value) OPCODE_ONTIME,V(value),  
+#define ONCLOCKTIME(hours,mins) OPCODE_ONTIME,V((STRIP_ZERO(hours)*60)+STRIP_ZERO(mins)),
+#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),
+#define ONTHROW(turnout_id) OPCODE_ONTHROW,V(turnout_id),
+#define ONCHANGE(sensor_id) OPCODE_ONCHANGE,V(sensor_id),
+#define PAUSE OPCODE_PAUSE,0,0,
+#define PIN_TURNOUT(id,pin,description...) OPCODE_PINTURNOUT,V(id),OPCODE_PAD,V(pin), 
+#define POM(cv,value) OPCODE_POM,V(cv),OPCODE_PAD,V(value),
+#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) OPCODE_RESET,V(pin),
+#define RESUME OPCODE_RESUME,0,0,
+#define RETURN OPCODE_RETURN,0,0,
+#define REV(speed) OPCODE_REV,V(speed),
+#define ROSTER(cabid,name,funcmap...)
+#define ROUTE(id, description)  OPCODE_ROUTE, V(id), 
+#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) OPCODE_SET,V(pin),
+#define SET_TRACK(track,mode)  OPCODE_SET_TRACK,V(TRACK_MODE_##mode  <<8 | TRACK_NUMBER_##track),
+#define SETLOCO(loco) OPCODE_SETLOCO,V(loco),
+#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 STOP OPCODE_SPEED,V(0), 
+#define THROW(id)  OPCODE_THROW,V(id),
+#define TURNOUT(id,addr,subaddr,description...) OPCODE_TURNOUT,V(id),OPCODE_PAD,V(addr),OPCODE_PAD,V(subaddr),
+#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 WAITFOR(pin) OPCODE_WAITFOR,V(pin),
+#define XFOFF(cab,func) OPCODE_XFOFF,V(cab),OPCODE_PAD,V(func),
+#define XFON(cab,func) OPCODE_XFON,V(cab),OPCODE_PAD,V(func),
+
+// Build RouteCode
+const int StringMacroTracker2=__COUNTER__;
+const  HIGHFLASH  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

EthernetInterface.cpp

@@ -1,5 +1,10 @@
 /*
- *  © 2020,Gregor Baues,  Chris Harlow. All rights reserved.
+ *  © 2022 Bruno Sanches
+ *  © 2021 Fred Decker
+ *  © 2020-2022 Harald Barth
+ *  © 2020-2021 Chris Harlow
+ *  © 2020 Gregor Baues
+ *  All rights reserved.
  *  
  *  This file is part of DCC-EX/CommandStation-EX
  *
@@ -22,6 +27,7 @@
 #include "EthernetInterface.h"
 #include "DIAG.h"
 #include "CommandDistributor.h"
+#include "WiThrottle.h"
 #include "DCCTimer.h"
 
 EthernetInterface * EthernetInterface::singleton=NULL;
@@ -31,8 +37,13 @@ EthernetInterface * EthernetInterface::singleton=NULL;
  */
 void EthernetInterface::setup()
 {
-    singleton=new EthernetInterface();
-    if (!singleton->connected) singleton=NULL; 
+  if (singleton!=NULL) {
+    DIAG(F("Prog Error!"));
+    return;
+  }
+  if ((singleton=new EthernetInterface()))
+    return;
+  DIAG(F("Ethernet not initialized"));
 };
 
 
@@ -57,37 +68,33 @@ EthernetInterface::EthernetInterface()
         return;
     } 
     #endif
-    DIAG(F("begin OK."));
-     if (Ethernet.hardwareStatus() == EthernetNoHardware) {
-      DIAG(F("Ethernet shield not found"));
-      return;
+    if (Ethernet.hardwareStatus() == EthernetNoHardware) {
+      DIAG(F("Ethernet shield not found or W5100"));
     }
   
     unsigned long startmilli = millis();
-    while ((millis() - startmilli) < 5500) // Loop to give time to check for cable connection
-    {
+    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);
     }
+    // now we either do have link of we have a W5100
+    // where we do not know if we have link. That's
+    // the reason to now run checkLink.
+    // CheckLinks sets up outboundRing if it does
+    // not exist yet as well.
+    checkLink();
+}
 
-    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);     
+/**
+ * @brief Cleanup any resources
+ * 
+ * @return none
+ */
+EthernetInterface::~EthernetInterface() {
+  delete server;
+  delete outboundRing;
 }
 
 /**
@@ -96,33 +103,73 @@ EthernetInterface::EthernetInterface()
  */
 void EthernetInterface::loop()
 {
-    if (!singleton) return;
+    if (!singleton || (!singleton->checkLink()))
+      return;
     
-    switch (Ethernet.maintain())
-    {
+    switch (Ethernet.maintain()) {
     case 1:
         //renewed fail
         DIAG(F("Ethernet Error: renewed fail"));
         singleton=NULL;
         return;
-
     case 3:
         //rebind fail
         DIAG(F("Ethernet Error: rebind fail"));
         singleton=NULL;
         return;
-
     default:
         //nothing happened
         break;
     }
-
    singleton->loop2();
-
 }
 
- void EthernetInterface::loop2()
-{
+/**
+ * @brief Checks ethernet link cable status and detects when it connects / disconnects
+ * 
+ * @return true when cable is connected, false otherwise
+ */
+bool EthernetInterface::checkLink() {
+  if (Ethernet.linkStatus() != LinkOFF) { // check for not linkOFF instead of linkON as the W5100 does return LinkUnknown
+    //if we are not connected yet, setup a new server
+    if(!connected) {
+      DIAG(F("Ethernet cable connected"));
+      connected=true;
+      #ifdef IP_ADDRESS
+      Ethernet.setLocalIP(IP_ADDRESS);      // for static IP, set it again
+      #endif
+      IPAddress ip = Ethernet.localIP();    // look what IP was obtained (dynamic or static)
+      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);
+      // only create a outboundRing it none exists, this may happen if the cable
+      // gets disconnected and connected again
+      if(!outboundRing)
+	outboundRing=new RingStream(OUTBOUND_RING_SIZE);
+    }
+    return true;
+  } else { // connected
+    DIAG(F("Ethernet cable disconnected"));
+    connected=false;
+    //clean up any client
+    for (byte socket = 0; socket < MAX_SOCK_NUM; socket++) {
+      if(clients[socket].connected())
+	clients[socket].stop();
+    }
+    // tear down server
+    delete server;
+    server = nullptr;
+    LCD(4,F("IP: None"));
+  }
+  return false;
+}
+
+void EthernetInterface::loop2() {
+    if (!outboundRing) { // no idea to call loop2() if we can't handle outgoing data in it
+      if (Diag::ETHERNET) DIAG(F("No outboundRing"));
+      return;
+    }
     // get client from the server
     EthernetClient client = server->accept();
 
@@ -158,9 +205,7 @@ void EthernetInterface::loop()
             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. 
           }
         }
@@ -170,13 +215,18 @@ void EthernetInterface::loop()
    for (int socket = 0; socket<MAX_SOCK_NUM; socket++) {
      if (clients[socket] && !clients[socket].connected()) {
       clients[socket].stop();
+      CommandDistributor::forget(socket);          
       if (Diag::ETHERNET)  DIAG(F("Ethernet: disconnect %d "), socket);             
      }
     }
+
+    WiThrottle::loop(outboundRing);
     
     // handle at most 1 outbound transmission 
     int socketOut=outboundRing->read();
-    if (socketOut>=0) {
+    if (socketOut >= MAX_SOCK_NUM) {
+      DIAG(F("Ethernet outboundRing socket=%d error"), socketOut);
+    } else 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());

EthernetInterface.h

@@ -1,5 +1,10 @@
 /*
- *  © 2020,Gregor Baues,  Chris Harlow. All rights reserved.
+ *  © 2021 Neil McKechnie
+ *  © 2021 Mike S
+ *  © 2021 Fred Decker
+ *  © 2020-2021 Chris Harlow
+ *  © 2020 Gregor Baues
+ *  All rights reserved.
  *  
  *  This file is part of DCC-EX/CommandStation-EX
  *
@@ -23,10 +28,10 @@
 #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>   
@@ -51,15 +56,16 @@ class EthernetInterface {
      static void loop();
    
  private:
-     static EthernetInterface * singleton;
-     bool connected;
-     EthernetInterface();
-     void loop2();
-    EthernetServer * server;
+    static EthernetInterface * singleton;
+    bool connected;
+    EthernetInterface();
+    ~EthernetInterface();
+    void loop2();
+    bool checkLink();
+    EthernetServer * server = NULL;
     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;
-  
+    RingStream * outboundRing = NULL;
 };
 
 #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,60 @@
  *  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
+
+#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 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)
+#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 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))
+#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 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 STRCPY_P strcpy
+#define STRCMP_P strcmp
+#define STRNCPY_P strncpy
+#define STRNCMP_P strncmp
+#define STRLEN_P strlen
 #endif
 #endif

GITHUB_SHA.h

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

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,128 @@
 #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 >= 0x20 && address <= 0x26)
+    return F("GPIO Expander");
+  else if (address == 0x27)
+    return F("GPIO Expander or LCD Display");
+  else if (address == 0x29)
+    return F("Time-of-flight sensor");
+  else if (address >= 0x3c && address <= 0x3d)
+    return F("OLED Display");
+  else if (address >= 0x48 && address <= 0x4f)
+    return F("Analogue Inputs or PWM");
+  else if (address >= 0x40 && address <= 0x4f)
+    return F("PWM");
+  else if (address >= 0x50 && address <= 0x5f) 
+    return F("EEPROM"); 
+  else if (address == 0x68) 
+    return F("Real-time clock"); 
+  else if (address >= 0x70 && address <= 0x77)
+    return F("I2C Mux");
+  else
+    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);
+    unsigned long 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 +162,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 +203,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 +212,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 +221,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 +232,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 +263,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 +277,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 +319,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 +330,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 +339,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.
+  unsigned long _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,57 @@ 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;
+    unsigned long startTime = 0;
+    uint8_t muxPhase = 0;
+    uint8_t muxAddress = 0;
+    uint8_t muxData[1];
+    uint8_t deviceAddress;
+    const uint8_t *sendBuffer;
+    uint8_t *receiveBuffer;
+
+    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();
     }
   }
 }
@@ -78,8 +174,7 @@ void I2CManagerClass::startTransaction() {
 void I2CManagerClass::queueRequest(I2CRB *req) {
   req->status = I2C_STATUS_PENDING;
   req->nextRequest = NULL;
-
-  ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
+  ATOMIC_BLOCK() {
     if (!queueTail) 
       queueHead = queueTail = req;  // Only item on queue
     else
@@ -92,7 +187,7 @@ 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 +198,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 +211,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 +221,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) { 
+      unsigned long elapsed = micros() - startTime;
+      if (elapsed > _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 +285,7 @@ void I2CManagerClass::loop() {
 #if !defined(I2C_USE_INTERRUPTS)
   handleInterrupt();
 #endif
+  // Call function to monitor for stuck I2C operations.
   checkForTimeout();
 }
 
@@ -177,38 +300,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) {
+    // 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 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

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,312 @@
+/*
+ *  © 2022-23 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 <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_ARCH_STM32)
+void I2C1_IRQHandler() {
+  I2CManager.handleInterrupt();
+}
+#endif
+
+// Assume I2C1 for now - default I2C bus on Nucleo-F411RE and likely Nucleo-64 variants
+I2C_TypeDef *s = I2C1;
+#define I2C_IRQn  I2C1_EV_IRQn
+#define I2C_BUSFREQ 16
+
+// 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
+
+/***************************************************************************
+ *  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 62.5ns clock period
+  uint16_t t_rise;
+  uint32_t ccr_freq;
+  if (i2cClockSpeed < 200000L) {
+    // i2cClockSpeed = 100000L;
+    t_rise = 0x11;  // (1000ns /62.5ns) + 1;
+  }
+  else if (i2cClockSpeed < 800000L)
+  {
+    i2cClockSpeed = 400000L;
+    t_rise = 0x06;  // (300ns / 62.5ns) + 1;
+    // } else if (i2cClockSpeed < 1200000L) {
+    //   i2cClockSpeed = 1000000L;
+    //   t_rise = 120;
+  }
+  else
+  {
+    i2cClockSpeed = 100000L;
+    t_rise = 0x11;  // (1000ns /62.5ns) + 1;
+  }
+
+  // Enable the I2C master mode
+  s->CR1 &= ~(I2C_CR1_PE);  // Enable I2C
+  // Software reset the I2C peripheral
+  // s->CR1 |= I2C_CR1_SWRST;  // reset the I2C
+  // Release reset
+  // s->CR1 &= ~(I2C_CR1_SWRST);  // Normal operation
+
+  // Calculate baudrate - using a rise time appropriate for the speed
+  ccr_freq = I2C_BUSFREQ * 1000000 / i2cClockSpeed / 2;
+
+  // Bit 15: I2C Master mode, 0=standard, 1=Fast Mode
+  // Bit 14: Duty, fast mode duty cycle
+  // Bit 11-0: FREQR = 16MHz => TPCLK1 = 62.5ns, so CCR divisor must be 0x50 (80 * 62.5ns = 5000ns)
+  s->CCR = (uint16_t)ccr_freq;
+
+  // Configure the rise time register
+  s->TRISE = t_rise;  // 1000 ns / 62.5 ns = 16 + 1
+
+  // Enable the I2C master mode
+  s->CR1 |= I2C_CR1_PE;  // Enable I2C
+}
+
+/***************************************************************************
+ *  Initialise I2C registers.
+ ***************************************************************************/
+void I2CManagerClass::I2C_init()
+{
+  //Setting up the clocks
+  RCC->APB1ENR |= (1<<21);  // Enable I2C CLOCK
+  RCC->AHB1ENR |= (1<<1);   // Enable GPIOB CLOCK for PB8/PB9
+  // Standard I2C pins are SCL on PB8 and SDA on PB9
+  // Bits (17:16)= 1:0 --> Alternate Function for Pin PB8;
+  // Bits (19:18)= 1:0 --> Alternate Function for Pin 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 |= (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] |= (4<<0) | (4<<4);           // PB8 on low nibble, PB9 on next nibble up
+
+  // Software reset the I2C peripheral
+  s->CR1 |= I2C_CR1_SWRST;  // reset the I2C
+  s->CR1 &= ~(I2C_CR1_SWRST);  // Normal operation
+
+  // Program the peripheral input clock in CR2 Register in order to generate correct timings
+  s->CR2 |= I2C_BUSFREQ;  // PCLK1 FREQUENCY in MHz
+
+#if defined(I2C_USE_INTERRUPTS)
+  // Setting NVIC
+  NVIC_SetPriority(I2C_IRQn, 1);  // Match default priorities
+  NVIC_EnableIRQ(I2C_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 |= 0x0700;   // Enable Buffer, Event and Error interrupts
+  s->CR2 |= 0x0300;   // Enable Event and Error interrupts
+#endif
+
+  // 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: FREQR = 16MHz => TPCLK1 = 62.5ns, so CCR divisor must be 0x50 (80 * 62.5ns = 5000ns)
+  s->CCR = 0x0050;
+
+  // Configure the rise time register - max allowed in 1000ns
+  s->TRISE = 0x0011; // 1000 ns / 62.5 ns = 16 + 1
+
+  // Enable the I2C master mode
+  s->CR1 |= I2C_CR1_PE;  // Enable I2C
+  // Setting bus idle mode and wait for sync
+}
+
+/***************************************************************************
+ *  Initiate a start bit for transmission.
+ ***************************************************************************/
+void I2CManagerClass::I2C_sendStart() {
+
+  // Set counters here in case this is a retry.
+  rxCount = txCount = 0;
+  uint8_t temp;
+
+  // 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 for read operation
+    s->CR1 |= I2C_CR1_ACK;  // Enable the ACK
+    s->CR1 |= I2C_CR1_START;  // Generate START
+    // Send address with read flag (1) or'd in
+    s->DR = (deviceAddress << 1) | 1;  //  send the address
+    while (!(s->SR1 && I2C_SR1_ADDR));  // wait for ADDR bit to set
+    // Special case for 1 byte reads!
+    if (bytesToReceive == 1)
+    {
+      s->CR1 &= ~I2C_CR1_ACK;            // clear the ACK bit 
+		  temp = I2C1->SR1 | I2C1->SR2;  // read SR1 and SR2 to clear the ADDR bit.... EV6 condition
+		  s->CR1 |= I2C_CR1_STOP;              // Stop I2C
+    }
+    else
+      temp = s->SR1 | s->SR2;        // read SR1 and SR2 to clear the ADDR bit
+  }
+  else {
+    // Send start for write operation
+    s->CR1 |= I2C_CR1_ACK;  // Enable the ACK
+    s->CR1 |= I2C_CR1_START;  // Generate START
+    // Send address with write flag (0) or'd in
+    s->DR = (deviceAddress << 1) | 0;  //  send the address
+    while (!(s->SR1 && I2C_SR1_ADDR));  // wait for ADDR bit to set
+    temp = s->SR1 | s->SR2;  // read SR1 and SR2 to clear the ADDR bit
+  }
+}
+
+/***************************************************************************
+ *  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 (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->SR1 && I2C_SR1_ARLO) {
+    // Arbitration lost, restart
+    I2C_sendStart();   // Reinitiate request
+  } else if (s->SR1 && I2C_SR1_BERR) {
+    // Bus error
+    completionStatus = I2C_STATUS_BUS_ERROR;
+    state = I2C_STATE_COMPLETED;
+  } else if (s->SR1 && I2C_SR1_TXE) {
+    // Master write completed
+    if (s->SR1 && (1<<10)) {
+      // Nacked, send stop.
+      I2C_sendStop();
+      completionStatus = I2C_STATUS_NEGATIVE_ACKNOWLEDGE;
+      state = I2C_STATE_COMPLETED;
+    } else if (bytesToSend) {
+      // Acked, so send next byte
+      s->DR = 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 {
+      // Check both TxE/BTF == 1 before generating stop
+      while (!(s->SR1 && I2C_SR1_TXE));    // Check TxE
+      while (!(s->SR1 && I2C_SR1_BTF));    // Check BTF
+      // No more data to send/receive. Initiate a STOP condition and finish
+      I2C_sendStop();
+      state = I2C_STATE_COMPLETED;
+    }
+  } else if (s->SR1 && I2C_SR1_RXNE) {
+    // Master read completed without errors
+    if (bytesToReceive == 1) {
+//      s->I2CM.CTRLB.bit.ACKACT = 1;  // NAK final byte
+      I2C_sendStop();  // send stop
+      receiveBuffer[rxCount++] = s->DR;  // Store received byte
+      bytesToReceive = 0;
+      state = I2C_STATE_COMPLETED;
+    } else if (bytesToReceive) {
+//      s->I2CM.CTRLB.bit.ACKACT = 0;  // ACK all but final byte
+      receiveBuffer[rxCount++] = s->DR;  // Store received byte
+      bytesToReceive--;
+    }
+  }
+}
+
+#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

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)) void exrailHalSetup();
+
 //==================================================================================================================
 // Static methods
 //------------------------------------------------------------------------------------------------------------------
@@ -41,22 +48,58 @@
 // 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. 
+  if (exrailHalSetup)
+    exrailHalSetup();
+
+  // Predefine two PCA9685 modules 0x40-0x41 if no conflicts
+  // Allocates 32 pins 100-131
+  if (checkNoOverlap(100, 16, 0x40)) {
+    PCA9685::create(100, 16, 0x40);
+  } else {
+    DIAG(F("Default PCA9685 at I2C 0x40 disabled due to configured user device"));
+  }
+  if (checkNoOverlap(116, 16, 0x41)) {
+    PCA9685::create(116, 16, 0x41);
+  } else {
+    DIAG(F("Default PCA9685 at I2C 0x41 disabled due to configured user device"));
+  }
+  
+  // Predefine two MCP23017 module 0x20/0x21 if no conflicts
+  // Allocates 32 pins 164-195
+  if (checkNoOverlap(164, 16, 0x20)) {
+    MCP23017::create(164, 16, 0x20);
+  } else {
+    DIAG(F("Default MCP23017 at I2C 0x20 disabled due to configured user device"));
+  }
+  if (checkNoOverlap(180, 16, 0x21)) {
+    MCP23017::create(180, 16, 0x21);
+  } else {
+    DIAG(F("Default MCP23017 at I2C 0x21 disabled due to configured user device"));
+  }
+}
+
+// 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 +131,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 +151,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
 }
 
@@ -139,7 +185,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 +194,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,7 +243,7 @@ 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
 }
 
@@ -179,7 +262,7 @@ 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
 }
 
@@ -200,25 +283,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 +316,50 @@ 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.
+bool IODevice::checkNoOverlap(VPIN firstPin, uint8_t nPins, I2CAddress i2cAddress) {
+#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) {
+          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) {
+      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 +367,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 +383,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 +406,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 +515,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 +538,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);
 }
 
 /////////////////////////////////////////////////////////////////////////////////////////////////////

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
@@ -93,6 +94,8 @@ public:
     CONFIGURE_INPUT = 1,
     CONFIGURE_SERVO = 2,
     CONFIGURE_OUTPUT = 3,
+    CONFIGURE_ANALOGOUTPUT = 4,
+    CONFIGURE_ANALOGINPUT = 5,
   } ConfigTypeEnum;
 
   typedef enum : uint8_t {
@@ -110,6 +113,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[]);
 
@@ -143,6 +150,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();
@@ -160,24 +168,12 @@ 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);
 
- // 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) {
@@ -185,7 +181,7 @@ protected:
   };
 
   // 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;
   };
 
@@ -201,6 +197,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 +243,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 +276,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 +288,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 +301,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 +319,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 +337,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 +360,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 +374,7 @@ private:
   // Device-specific read functions.
   int _read(VPIN vpin) override;
   int _readAnalogue(VPIN vpin) override;
+  int _configureAnalogIn(VPIN vpin) override;
   void _display() override;
 
 
@@ -363,9 +384,164 @@ private:
 };
 
 /////////////////////////////////////////////////////////////////////////////////////////////////////
+/*
+ * 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 _writeAnalogue(VPIN vpin, int value, uint8_t activity, uint16_t duration) override;
+  void _display() override;
+  uint8_t _stepperStatus;
+};
+
+/////////////////////////////////////////////////////////////////////////////////////////////////////
+
+
+// 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_duinoNodes.h"
+#include "IO_EXIOExpander.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

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,22 @@ 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,125 @@
+/*
+ *  © 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.
+  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,400 @@
+/*
+ *  © 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_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 myHal.cpp:
+* (Note the device driver is included by default)
+*
+* void halSetup() {
+*   // EXIOExpander::create(vpin, num_vpins, i2c_address);
+*   EXIOExpander::create(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
+          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);
+            _digitalInputStates = (byte*) calloc(_digitalPinBytes, 1);
+            _digitalPinBytes = digitalBytesNeeded;
+          }
+          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);
+            _analoguePinBytes = analogueBytesNeeded;
+          }
+        } 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 (status == I2C_STATUS_OK) {
+        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 (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 (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;
+  uint8_t* _analogueInputStates;
+  uint8_t* _analogueInputBuffer;  // 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 buffers (may be longer than needed)
+  uint8_t* _analoguePinMap;
+  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_EXTurntable.h

@@ -0,0 +1,121 @@
+/*
+ *  © 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/Turntable-EX) and contains the stepper motor logic.
+*
+* This device driver sends a step position to Turntable-EX 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.
+*/
+
+#ifndef IO_EXTurntable_h
+#define IO_EXTurntable_h
+
+#include "IODevice.h"
+#include "I2CManager.h"
+#include "DIAG.h"
+
+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;
+  addDevice(this);
+}
+
+// Initialisation of EXTurntable
+void EXTurntable::_begin() {
+  I2CManager.begin();
+  I2CManager.setClock(1000000);
+  if (I2CManager.exists(_I2CAddress)) {
+#ifdef DIAG_IO
+    _display();
+#endif
+  } else {
+    _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];
+  // DIAG(F("Turntable-EX returned status: %d"), _stepperStatus);
+  delayUntil(currentMicros + 500000);  // Wait 500ms before checking again, turntables turn slowly
+}
+
+// Read returns status as obtained in our loop.
+// Return false if our status value is invalid.
+int EXTurntable::_read(VPIN vpin) {
+  if (_deviceState == DEVSTATE_FAILED) return 0;
+  // DIAG(F("_read status: %d"), _stepperStatus);
+  if (_stepperStatus > 1) {
+    return false;
+  } else {
+    return _stepperStatus;
+  }
+}
+
+// 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;
+  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);
+#endif
+  _stepperStatus = 1;     // Tell the device driver Turntable-EX is busy
+  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_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

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,262 @@
+/*
+ *  © 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);
+
+    _displayDriver->clearNative();
+
+    // 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);
+
+    // 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_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;
   }

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;
   }

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; 
   }

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,127 @@
+/*
+ *  © 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
+*
+* Further to this, feedback can 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.
+*
+* 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:
+  // Constructor
+  RotaryEncoder(VPIN firstVpin, int nPins, I2CAddress i2cAddress){
+    _firstVpin = firstVpin;
+    _nPins = nPins;
+    _I2CAddress = i2cAddress;
+    addDevice(this);
+  }
+  static void create(VPIN firstVpin, int nPins, I2CAddress i2cAddress) {
+    if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new RotaryEncoder(firstVpin, nPins, i2cAddress);
+  }
+
+private:
+  // Initiate the device
+  void _begin() {
+    I2CManager.begin();
+    if (I2CManager.exists(_I2CAddress)) {
+      byte _getVersion[1] = {RE_VER};
+      I2CManager.read(_I2CAddress, _versionBuffer, 3, _getVersion, 1);
+      _majorVer = _versionBuffer[0];
+      _minorVer = _versionBuffer[1];
+      _patchVer = _versionBuffer[2];
+      _buffer[0] = RE_OP;
+      I2CManager.write(_I2CAddress, _buffer, 1);
+#ifdef DIAG_IO
+      _display();
+#endif
+    } else {
+        _deviceState = DEVSTATE_FAILED;
+    }
+  }
+
+  void _loop(unsigned long currentMicros) override {
+    I2CManager.read(_I2CAddress, _buffer, 1);
+    _position = _buffer[0];
+    // This here needs to have a change check, ie. position is a different value.
+  #if defined(EXRAIL_ACTIVE)
+      if (_position != _previousPosition) {
+        _previousPosition = _position;
+        RMFT2::changeEvent(_firstVpin,1);
+      } else {
+        RMFT2::changeEvent(_firstVpin,0);
+      }
+  #endif
+    delayUntil(currentMicros + 100000);
+  }
+
+  // Device specific read function
+  int _readAnalogue(VPIN vpin) override {
+    if (_deviceState == DEVSTATE_FAILED) return 0;
+    return _position;
+  }
+
+  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);
+    }
+  }
+  
+  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 _buffer[1];
+  uint8_t _majorVer = 0;
+  uint8_t _minorVer = 0;
+  uint8_t _patchVer = 0;
+
+  enum {
+    RE_VER = 0xA0,   // Flag to retrieve rotary encoder version from the device
+    RE_OP = 0xA1,    // Flag for normal operation
+  };
+
+};
+
+#endif

IO_Servo.cpp

@@ -0,0 +1,33 @@
+/*
+ *  © 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_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

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();
-}

LCN.cpp

@@ -43,14 +43,18 @@ void LCN::loop() {
   
   while (stream->available()) {
     int ch = stream->read();
-    if (ch >= 0 && ch <= '9') {  // accumulate id value
+    if (ch >= '0' && ch <= '9') {  // accumulate id value
       id = 10 * id + ch - '0';
     }
     else if (ch == 't' || ch == 'T') { // Turnout opcodes
       if (Diag::LCN) DIAG(F("LCN IN %d%c"),id,(char)ch);
       if (!Turnout::exists(id)) LCNTurnout::create(id);
       Turnout::setClosedStateOnly(id,ch=='t');
-      Turnout::turnoutlistHash++; // signals ED update of turnout data
+      id = 0;
+    }
+    else if (ch == 'y' || ch == 'Y') { // Turnout opcodes
+      if (Diag::LCN) DIAG(F("LCN IN %d%c"),id,(char)ch);
+      Turnout::setClosed(id,ch=='y');
       id = 0;
     }
     else if (ch == 'S' || ch == 's') {

LCN.h

@@ -1,5 +1,7 @@
 /*
- *  (c) 2021 Fred Decker.  All rights reserved.
+ *  © 2021 Harald Barth
+ *  © 2021 Fred Decker
+ *  All rights reserved.
  *  
  *  This file is part of CommandStation-EX
  *

LiquidCrystal_I2C.cpp

@@ -41,27 +41,28 @@
 // can't assume that its in that state when a sketch starts (and the
 // LiquidCrystal constructor is called).
 
-LiquidCrystal_I2C::LiquidCrystal_I2C(uint8_t lcd_Addr, uint8_t lcd_cols,
+LiquidCrystal_I2C::LiquidCrystal_I2C(I2CAddress lcd_Addr, uint8_t lcd_cols,
                                      uint8_t lcd_rows) {
   _Addr = lcd_Addr;
-  lcdRows = lcd_rows;
-  lcdCols = lcd_cols;
-
+  lcdRows = lcd_rows;  // Number of character rows (typically 2 or 4).
+  lcdCols = lcd_cols;  // Number of character columns (typically 16 or 20)
   _backlightval = 0;
+ }
+
+bool LiquidCrystal_I2C::begin() {
 
   I2CManager.begin();
   I2CManager.setClock(100000L);    // PCF8574 is spec'd to 100kHz.
 
-  if (I2CManager.exists(lcd_Addr)) {
-    DIAG(F("%dx%d LCD configured on I2C:x%x"), (int)lcd_cols, (int)lcd_rows, (int)lcd_Addr);
+  if (I2CManager.exists(_Addr)) {
+    DIAG(F("%dx%d LCD configured on I2C:%s"), (int)lcdCols, (int)lcdRows, _Addr.toString());
     _displayfunction = LCD_4BITMODE | LCD_1LINE | LCD_5x8DOTS;
-    begin();
     backlight();
-    lcdDisplay = this;
+  } else {
+    DIAG(F("LCD not found on I2C:%s"), _Addr.toString());
+    return false;
   }
-}
 
-void LiquidCrystal_I2C::begin() {
   if (lcdRows > 1) {
     _displayfunction |= LCD_2LINE;
   }
@@ -79,15 +80,15 @@ void LiquidCrystal_I2C::begin() {
 
   // we start in 8bit mode, try to set 4 bit mode
   write4bits(0x03);
-  delayMicroseconds(4500);  // wait min 4.1ms
+  delayMicroseconds(5000);  // wait min 4.1ms
 
   // second try
   write4bits(0x03);
-  delayMicroseconds(4500);  // wait min 4.1ms
+  delayMicroseconds(5000);  // wait min 4.1ms
 
   // third go!
   write4bits(0x03);
-  delayMicroseconds(150);
+  delayMicroseconds(5000);
 
   // finally, set to 4-bit interface
   write4bits(0x02);
@@ -99,26 +100,23 @@ void LiquidCrystal_I2C::begin() {
   _displaycontrol = LCD_DISPLAYON | LCD_CURSOROFF | LCD_BLINKOFF;
   display();
 
-  // clear it off
-  clear();
-
   // Initialize to default text direction (for roman languages)
   _displaymode = LCD_ENTRYLEFT | LCD_ENTRYSHIFTDECREMENT;
 
   // set the entry mode
   command(LCD_ENTRYMODESET | _displaymode);
 
-  setRowNative(0);
+  return true;
 }
 
 /********** high level commands, for the user! */
 void LiquidCrystal_I2C::clearNative() {
   command(LCD_CLEARDISPLAY);  // clear display, set cursor position to zero
-  delayMicroseconds(2000);    // this command takes 1.52ms
+  delayMicroseconds(2000);    // this command takes 1.52ms but allow plenty
 }
 
 void LiquidCrystal_I2C::setRowNative(byte row) {
-  int row_offsets[] = {0x00, 0x40, 0x14, 0x54};
+  uint8_t row_offsets[] = {0x00, 0x40, 0x14, 0x54};
   if (row >= lcdRows) {
     row = lcdRows - 1;  // we count rows starting w/0
   }
@@ -146,6 +144,10 @@ size_t LiquidCrystal_I2C::writeNative(uint8_t value) {
   return 1;
 }
 
+bool LiquidCrystal_I2C::isBusy() { 
+  return rb.isBusy();
+}
+
 /*********** mid level commands, for sending data/cmds */
 
 inline void LiquidCrystal_I2C::command(uint8_t value) { 
@@ -192,11 +194,12 @@ void LiquidCrystal_I2C::send(uint8_t value, uint8_t mode) {
   uint8_t lownib = ((value & 0x0f) << BACKPACK_DATA_BITS) | mode;
   // Send both nibbles
   uint8_t len = 0;
+  rb.wait();
   outputBuffer[len++] = highnib|En;
   outputBuffer[len++] = highnib;
   outputBuffer[len++] = lownib|En;
   outputBuffer[len++] = lownib;
-  I2CManager.write(_Addr, outputBuffer, len);  // Write command synchronously
+  I2CManager.write(_Addr, outputBuffer, len, &rb);  // Write command asynchronously
 }
 
 // write 4 data bits to the HD44780 LCD controller.
@@ -206,14 +209,16 @@ void LiquidCrystal_I2C::write4bits(uint8_t value) {
   // I2C clock cycle time of 2.5us at 400kHz. Data is clocked in to the
   // HD44780 on the trailing edge of the Enable pin.
   uint8_t len = 0;
+  rb.wait();
   outputBuffer[len++] = _data|En;
   outputBuffer[len++] = _data;
-  I2CManager.write(_Addr, outputBuffer, len);  // Write command synchronously
+  I2CManager.write(_Addr, outputBuffer, len, &rb);  // Write command asynchronously
 }
 
 // write a byte to the PCF8574 I2C interface.  We don't need to set
 // the enable pin for this.
 void LiquidCrystal_I2C::expanderWrite(uint8_t value) {
+  rb.wait();
   outputBuffer[0] = value | _backlightval;
-  I2CManager.write(_Addr, outputBuffer, 1);  // Write command synchronously
+  I2CManager.write(_Addr, outputBuffer, 1, &rb);  // Write command asynchronously
 }

LiquidCrystal_I2C.h

@@ -22,7 +22,7 @@
 #define LiquidCrystal_I2C_h
 
 #include <Arduino.h>
-#include "LCDDisplay.h"
+#include "Display.h"
 #include "I2CManager.h"
 
 // commands
@@ -62,33 +62,38 @@
 #define Rw (1 << BACKPACK_Rw_BIT)  // Read/Write bit
 #define Rs (1 << BACKPACK_Rs_BIT)  // Register select bit
 
-class LiquidCrystal_I2C : public LCDDisplay {
+class LiquidCrystal_I2C : public DisplayDevice {
 public:
-  LiquidCrystal_I2C(uint8_t lcd_Addr,uint8_t lcd_cols,uint8_t lcd_rows);
-  void begin();
+  LiquidCrystal_I2C(I2CAddress lcd_Addr,uint8_t lcd_cols,uint8_t lcd_rows);
+  bool begin() override;
   void clearNative() override;
   void setRowNative(byte line) override;
   size_t writeNative(uint8_t c) override;
+  // I/O is synchronous, so if this is called we're not busy!
+  bool isBusy() override; 
   
   void display();
   void noBacklight();
   void backlight();
   
   void command(uint8_t);
+  uint16_t getNumCols() { return lcdCols; }
+  uint16_t getNumRows() { return lcdRows; }
+
 
 private:
   void send(uint8_t, uint8_t);
   void write4bits(uint8_t);
   void expanderWrite(uint8_t);
-  uint8_t _Addr;
+  uint8_t lcdCols=0, lcdRows=0;
+  I2CAddress _Addr;
   uint8_t _displayfunction;
   uint8_t _displaycontrol;
   uint8_t _displaymode;
-  uint8_t _backlightval;
+  uint8_t _backlightval = 0;
 
   uint8_t outputBuffer[4];
-  // I/O is synchronous, so if this is called we're not busy!
-  bool isBusy() override { return false; } 
+  I2CRB rb;
 };
 
 #endif

MotorDriver.cpp

@@ -1,7 +1,12 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
+ *  © 2022 Paul M Antoine
+ *  © 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
@@ -18,32 +23,75 @@
  */
 #include <Arduino.h>
 #include "MotorDriver.h"
+#include "DCCWaveform.h"
 #include "DCCTimer.h"
 #include "DIAG.h"
 
-#define setHIGH(fastpin)  *fastpin.inout |= fastpin.maskHIGH
-#define setLOW(fastpin)   *fastpin.inout &= fastpin.maskLOW
-#define isHIGH(fastpin)   (*fastpin.inout & fastpin.maskHIGH)
-#define isLOW(fastpin)    (!isHIGH(fastpin))
+#if defined(ARDUINO_ARCH_ESP32)
+#include "ESP32-fixes.h"
+#endif
 
-bool MotorDriver::usePWM=false;
 bool MotorDriver::commonFaultPin=false;
-       
-MotorDriver::MotorDriver(byte power_pin, byte signal_pin, byte signal_pin2, int8_t brake_pin,
+
+volatile portreg_t shadowPORTA;
+volatile portreg_t shadowPORTB;
+volatile portreg_t shadowPORTC;
+
+MotorDriver::MotorDriver(int16_t power_pin, byte signal_pin, byte signal_pin2, int8_t brake_pin,
                          byte current_pin, float sense_factor, unsigned int trip_milliamps, byte fault_pin) {
   powerPin=power_pin;
-  getFastPin(F("POWER"),powerPin,fastPowerPin);
-  pinMode(powerPin, OUTPUT);
+  invertPower=power_pin < 0;
+  if (invertPower) {
+    powerPin = 0-power_pin;
+    IODevice::write(powerPin,HIGH);// set to OUTPUT and off
+  } else {
+    powerPin = power_pin;
+    IODevice::write(powerPin,LOW);// set to OUTPUT and off
+  }
   
   signalPin=signal_pin;
   getFastPin(F("SIG"),signalPin,fastSignalPin);
   pinMode(signalPin, OUTPUT);
-  
+
+  fastSignalPin.shadowinout = NULL;
+  if (HAVE_PORTA(fastSignalPin.inout == &PORTA)) {
+    DIAG(F("Found PORTA pin %d"),signalPin);
+    fastSignalPin.shadowinout = fastSignalPin.inout;
+    fastSignalPin.inout = &shadowPORTA;
+  }
+  if (HAVE_PORTB(fastSignalPin.inout == &PORTB)) {
+    DIAG(F("Found PORTB pin %d"),signalPin);
+    fastSignalPin.shadowinout = fastSignalPin.inout;
+    fastSignalPin.inout = &shadowPORTB;
+  }
+  if (HAVE_PORTC(fastSignalPin.inout == &PORTC)) {
+    DIAG(F("Found PORTC pin %d"),signalPin);
+    fastSignalPin.shadowinout = fastSignalPin.inout;
+    fastSignalPin.inout = &shadowPORTC;
+  }
+
   signalPin2=signal_pin2;
   if (signalPin2!=UNUSED_PIN) {
     dualSignal=true;
     getFastPin(F("SIG2"),signalPin2,fastSignalPin2);
     pinMode(signalPin2, OUTPUT);
+
+    fastSignalPin2.shadowinout = NULL;
+    if (HAVE_PORTA(fastSignalPin2.inout == &PORTA)) {
+      DIAG(F("Found PORTA pin %d"),signalPin2);
+      fastSignalPin2.shadowinout = fastSignalPin2.inout;
+      fastSignalPin2.inout = &shadowPORTA;
+    }
+    if (HAVE_PORTB(fastSignalPin2.inout == &PORTB)) {
+      DIAG(F("Found PORTB pin %d"),signalPin2);
+      fastSignalPin2.shadowinout = fastSignalPin2.inout;
+      fastSignalPin2.inout = &shadowPORTB;
+    }
+    if (HAVE_PORTC(fastSignalPin2.inout == &PORTC)) {
+      DIAG(F("Found PORTC pin %d"),signalPin2);
+      fastSignalPin2.shadowinout = fastSignalPin2.inout;
+      fastSignalPin2.inout = &shadowPORTC;
+    }
   }
   else dualSignal=false; 
   
@@ -52,16 +100,15 @@ MotorDriver::MotorDriver(byte power_pin, byte signal_pin, byte signal_pin2, int8
     invertBrake=brake_pin < 0;
     brakePin=invertBrake ? 0-brake_pin : brake_pin;
     getFastPin(F("BRAKE"),brakePin,fastBrakePin);
+    // if brake is used for railcom  cutout we need to do PORTX register trick here as well
     pinMode(brakePin, OUTPUT);
-    setBrake(false);
+    setBrake(true);  // start with brake on in case we hace DC stuff going on
   }
   else brakePin=UNUSED_PIN;
   
   currentPin=current_pin;
-  if (currentPin!=UNUSED_PIN) {
-    pinMode(currentPin, INPUT);
-    senseOffset=analogRead(currentPin); // value of sensor at zero current
-  }
+  if (currentPin!=UNUSED_PIN) ADCee::init(currentPin);
+  senseOffset=0; // value can not be obtained until waveform is activated
 
   faultPin=fault_pin;
   if (faultPin != UNUSED_PIN) {
@@ -69,15 +116,39 @@ MotorDriver::MotorDriver(byte power_pin, byte signal_pin, byte signal_pin2, int8
     pinMode(faultPin, INPUT);
   }
 
-  senseFactor=sense_factor;
+  // This conversion performed at compile time so the remainder of the code never needs
+  // float calculations or libraray code. 
+  senseFactorInternal=sense_factor * senseScale; 
   tripMilliamps=trip_milliamps;
-  rawCurrentTripValue=(int)(trip_milliamps / sense_factor);
-  
+  rawCurrentTripValue=mA2raw(trip_milliamps);
+
+  if (rawCurrentTripValue + senseOffset > ADCee::ADCmax()) {
+    // This would mean that the values obtained from the ADC never
+    // can reach the trip value. So independent of the current, the
+    // short circuit protection would never trip. So we adjust the
+    // trip value so that it is tiggered when the ADC reports it's
+    // maximum value instead.
+
+    //    DIAG(F("Changing short detection value from %d to %d mA"),
+    // raw2mA(rawCurrentTripValue), raw2mA(ADCee::ADCmax()-senseOffset));
+    rawCurrentTripValue=ADCee::ADCmax()-senseOffset;
+  }
+
   if (currentPin==UNUSED_PIN) 
-    DIAG(F("MotorDriver ** WARNING ** No current or short detection"));  
-  else  
-    DIAG(F("MotorDriver currentPin=A%d, senseOffset=%d, rawCurentTripValue(relative to offset)=%d"),
-    currentPin-A0, senseOffset,rawCurrentTripValue);
+    DIAG(F("** WARNING ** No current or short detection"));
+  else  {
+    DIAG(F("Track %c, TripValue=%d"), trackLetter, rawCurrentTripValue);
+
+    // self testing diagnostic for the non-float converters... may be removed when happy
+    //  DIAG(F("senseFactorInternal=%d raw2mA(1000)=%d mA2Raw(1000)=%d"),
+    //   senseFactorInternal, raw2mA(1000),mA2raw(1000));
+  }
+
+  // prepare values for current detection
+  sampleDelay = 0;
+  lastSampleTaken = millis();
+  progTripValue = mA2raw(TRIP_CURRENT_PROG); 
+
 }
 
 bool MotorDriver::isPWMCapable() {
@@ -85,15 +156,23 @@ bool MotorDriver::isPWMCapable() {
 }
 
 
-void MotorDriver::setPower(bool on) {
+void MotorDriver::setPower(POWERMODE mode) {
+  bool on=mode==POWERMODE::ON;
   if (on) {
-    // toggle brake before turning power on - resets overcurrent error
-    // on the Pololu board if brake is wired to ^D2.
-    setBrake(true);
-    setBrake(false);
-    setHIGH(fastPowerPin);
+    // when switching a track On, we need to check the crrentOffset with the pin OFF
+    if (powerMode==POWERMODE::OFF && currentPin!=UNUSED_PIN) {
+        senseOffset = ADCee::read(currentPin);
+        DIAG(F("Track %c sensOffset=%d"),trackLetter,senseOffset);
+    }
+
+    IODevice::write(powerPin,invertPower ? LOW : HIGH);
+    if (isProgTrack)
+      DCCWaveform::progTrack.clearResets();
   }
-  else setLOW(fastPowerPin);
+  else {
+      IODevice::write(powerPin,invertPower ? HIGH : LOW);
+  }
+  powerMode=mode; 
 }
 
 // setBrake applies brake if on == true. So to get
@@ -104,80 +183,164 @@ void MotorDriver::setPower(bool on) {
 // (HIGH == release brake) and setBrake does
 // compensate for that.
 //
-void MotorDriver::setBrake(bool on) {
+void MotorDriver::setBrake(bool on, bool interruptContext) {
   if (brakePin == UNUSED_PIN) return;
-  if (on ^ invertBrake) setHIGH(fastBrakePin);
-  else setLOW(fastBrakePin);
+  if (!interruptContext) {noInterrupts();}
+  if (on ^ invertBrake)
+    setHIGH(fastBrakePin);
+  else
+    setLOW(fastBrakePin);
+  if (!interruptContext) {interrupts();}
 }
 
-void MotorDriver::setSignal( bool high) {
-   if (usePWM) {
-    DCCTimer::setPWM(signalPin,high);
-   }
-   else {
-     if (high) {
-        setHIGH(fastSignalPin);
-        if (dualSignal) setLOW(fastSignalPin2);
-     }
-     else {
-        setLOW(fastSignalPin);
-        if (dualSignal) setHIGH(fastSignalPin2);
-     }
-   }
-}
-
-#if defined(ARDUINO_TEENSY32) || defined(ARDUINO_TEENSY35)|| defined(ARDUINO_TEENSY36)
-volatile unsigned int overflow_count=0;
-#endif
-
 bool MotorDriver::canMeasureCurrent() {
   return currentPin!=UNUSED_PIN;
 }
 /*
  * Return the current reading as pin reading 0 to 1023. If the fault
  * pin is activated return a negative current to show active fault pin.
- * As there is no -0, create a little and return -1 in that case.
+ * As there is no -0, cheat a little and return -1 in that case.
  * 
  * senseOffset handles the case where a shield returns values above or below 
  * a central value depending on direction.
+ *
+ * Bool fromISR should be adjusted dependent how function is called
  */
-int MotorDriver::getCurrentRaw() {
+int MotorDriver::getCurrentRaw(bool fromISR) {
+  (void)fromISR;
   if (currentPin==UNUSED_PIN) return 0; 
   int current;
-#if defined(ARDUINO_TEENSY40) || defined(ARDUINO_TEENSY41)
-  bool irq = disableInterrupts();
-  current = analogRead(currentPin)-senseOffset;
-  enableInterrupts(irq);
-#elif defined(ARDUINO_TEENSY32) || defined(ARDUINO_TEENSY35)|| defined(ARDUINO_TEENSY36)
-  unsigned char sreg_backup;
-  sreg_backup = SREG;   /* save interrupt enable/disable state */
-  cli();
-  current = analogRead(currentPin)-senseOffset;
-  overflow_count = 0;
-  SREG = sreg_backup;    /* restore interrupt state */
-#else
-  current = analogRead(currentPin)-senseOffset;
-#endif
+  current = ADCee::read(currentPin, fromISR)-senseOffset;
   if (current<0) current=0-current;
-  if ((faultPin != UNUSED_PIN)  && isLOW(fastFaultPin) && isHIGH(fastPowerPin))
+  if ((faultPin != UNUSED_PIN)  && isLOW(fastFaultPin) && powerMode==POWERMODE::ON)
       return (current == 0 ? -1 : -current);
   return current;
-  // IMPORTANT:  This function can be called in Interrupt() time within the 56uS timer
-  //             The default analogRead takes ~100uS which is catastrphic
-  //             so DCCTimer has set the sample time to be much faster.  
+   
+}
+
+#ifdef ANALOG_READ_INTERRUPT
+/*
+ * This should only be called in interrupt context
+ * Copies current value from HW to cached value in
+ * Motordriver.
+ */
+#pragma GCC push_options
+#pragma GCC optimize ("-O3")
+bool MotorDriver::sampleCurrentFromHW() {
+  byte low, high;
+  //if (!bit_is_set(ADCSRA, ADIF))
+  if (bit_is_set(ADCSRA, ADSC))
+    return false;
+  //  if ((ADMUX & mask) != (currentPin - A0))
+  //    return false;
+  low = ADCL; //must read low before high
+  high = ADCH;
+  bitSet(ADCSRA, ADIF);
+  sampleCurrent = (high << 8) | low;
+  sampleCurrentTimestamp = millis();
+  return true;
+}
+void MotorDriver::startCurrentFromHW() {
+#if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)
+  const byte mask = 7;
+#else
+  const byte mask = 31;
+#endif
+  ADMUX=(1<<REFS0)|((currentPin-A0) & mask); //select AVCC as reference and set MUX
+  bitSet(ADCSRA,ADSC); // start conversion
+}
+#pragma GCC pop_options
+#endif //ANALOG_READ_INTERRUPT
+
+#if defined(ARDUINO_ARCH_ESP32)
+uint16_t taurustones[28] = { 165, 175, 196, 220,
+			     247, 262, 294, 330,
+			     349, 392, 440, 494,
+			     523, 587, 659, 698,
+			     494, 440, 392, 249,
+			     330, 284, 262, 247,
+			     220, 196, 175, 165 };
+#endif
+void MotorDriver::setDCSignal(byte speedcode) {
+  if (brakePin == UNUSED_PIN)
+    return;
+#if defined(ARDUINO_AVR_UNO)
+  TCCR2B = (TCCR2B & B11111000) | B00000110; // set divisor on timer 2 to result in (approx) 122.55Hz
+#endif
+#if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)
+  TCCR2B = (TCCR2B & B11111000) | B00000110; // set divisor on timer 2 to result in (approx) 122.55Hz
+  TCCR4B = (TCCR4B & B11111000) | B00000100; // same for timer 4 but maxcount and thus divisor differs
+#endif
+  // spedcoode is a dcc speed & direction
+  byte tSpeed=speedcode & 0x7F; // DCC Speed with 0,1 stop and speed steps 2 to 127
+  byte tDir=speedcode & 0x80;
+  byte brake;
+#if defined(ARDUINO_ARCH_ESP32)
+  {
+    int f = 131;
+    if (tSpeed > 2) {
+      if (tSpeed <= 58) {
+	f = taurustones[ (tSpeed-2)/2 ] ;
+      }
+    }
+    DCCEXanalogWriteFrequency(brakePin, f); // set DC PWM frequency to 100Hz XXX May move to setup
+  }
+#endif
+  if (tSpeed <= 1) brake = 255;
+  else if (tSpeed >= 127) brake = 0;
+  else  brake = 2 * (128-tSpeed);
+  if (invertBrake)
+    brake=255-brake;
+#if defined(ARDUINO_ARCH_ESP32)
+  DCCEXanalogWrite(brakePin,brake);
+#else
+  analogWrite(brakePin,brake);
+#endif
+  //DIAG(F("DCSignal %d"), speedcode);
+  if (HAVE_PORTA(fastSignalPin.shadowinout == &PORTA)) {
+    noInterrupts();
+    HAVE_PORTA(shadowPORTA=PORTA);
+    setSignal(tDir);
+    HAVE_PORTA(PORTA=shadowPORTA);
+    interrupts();
+  } else if (HAVE_PORTB(fastSignalPin.shadowinout == &PORTB)) {
+    noInterrupts();
+    HAVE_PORTB(shadowPORTB=PORTB);
+    setSignal(tDir);
+    HAVE_PORTB(PORTB=shadowPORTB);
+    interrupts();
+  } else if (HAVE_PORTC(fastSignalPin.shadowinout == &PORTC)) {
+    noInterrupts();
+    HAVE_PORTC(shadowPORTC=PORTC);
+    setSignal(tDir);
+    HAVE_PORTC(PORTC=shadowPORTC);
+    interrupts();
+  } else {
+    noInterrupts();
+    setSignal(tDir);
+    interrupts();
+  }
 }
 
 unsigned int MotorDriver::raw2mA( int raw) {
-  return (unsigned int)(raw * senseFactor);
+  //DIAG(F("%d = %d * %d / %d"), (int32_t)raw * senseFactorInternal / senseScale, raw, senseFactorInternal, senseScale);
+  return (int32_t)raw * senseFactorInternal / senseScale;
 }
-int MotorDriver::mA2raw( unsigned int mA) {
-  return (int)(mA / senseFactor);
+unsigned int MotorDriver::mA2raw( unsigned int mA) {
+  //DIAG(F("%d = %d * %d / %d"), (int32_t)mA * senseScale / senseFactorInternal, mA, senseScale, senseFactorInternal);
+  return (int32_t)mA * senseScale / senseFactorInternal;
 }
 
 void  MotorDriver::getFastPin(const FSH* type,int pin, bool input, FASTPIN & result) {
     // DIAG(F("MotorDriver %S Pin=%d,"),type,pin);
-    (void) type; // avoid compiler warning if diag not used above. 
+    (void) type; // avoid compiler warning if diag not used above.
+#if defined(ARDUINO_ARCH_SAMD)
+    PortGroup *port = digitalPinToPort(pin);
+#elif defined(ARDUINO_ARCH_STM32)
+    GPIO_TypeDef *port = digitalPinToPort(pin);
+#else
     uint8_t port = digitalPinToPort(pin);
+#endif
     if (input)
       result.inout = portInputRegister(port);
     else
@@ -186,3 +349,65 @@ void  MotorDriver::getFastPin(const FSH* type,int pin, bool input, FASTPIN & res
     result.maskLOW = ~result.maskHIGH;
     // DIAG(F(" port=0x%x, inoutpin=0x%x, isinput=%d, mask=0x%x"),port, result.inout,input,result.maskHIGH);
 }
+
+void MotorDriver::checkPowerOverload(bool useProgLimit, byte trackno) {
+  if (millis() - lastSampleTaken  < sampleDelay) return;
+  lastSampleTaken = millis();
+  int tripValue= useProgLimit?progTripValue:getRawCurrentTripValue();
+  
+  // Trackname for diag messages later
+  switch (powerMode) {
+    case POWERMODE::OFF:
+      sampleDelay = POWER_SAMPLE_OFF_WAIT;
+      break;
+    case POWERMODE::ON:
+      // Check current
+      lastCurrent=getCurrentRaw();
+      if (lastCurrent < 0) {
+	  // We have a fault pin condition to take care of
+	  lastCurrent = -lastCurrent;
+	  setPower(POWERMODE::OVERLOAD); // Turn off, decide later how fast to turn on again
+	  if (commonFaultPin) {
+	      if (lastCurrent < tripValue) {
+		      setPower(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: POWERTOGGLE TRACK %c"), trackno + 'A');
+	  } else {
+	    DIAG(F("TRACK %c FAULT PIN ACTIVE - OVERLOAD"), trackno + 'A');
+	      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 {
+        setPower(POWERMODE::OVERLOAD);
+        unsigned int mA=raw2mA(lastCurrent);
+        unsigned int maxmA=raw2mA(tripValue);
+	      power_good_counter=0;
+        sampleDelay = power_sample_overload_wait;
+        DIAG(F("TRACK %c POWER OVERLOAD %dmA (limit %dmA) shutdown for %dms"), trackno + 'A', 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
+      setPower(POWERMODE::ON);
+      sampleDelay = POWER_SAMPLE_ON_WAIT;
+      // Debug code....
+      DIAG(F("TRACK %c POWER RESTORE (check %dms)"), trackno + 'A', sampleDelay);
+      break;
+    default:
+      sampleDelay = 999; // cant get here..meaningless statement to avoid compiler warning.
+  }
+}

MotorDriver.h

@@ -1,7 +1,12 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
+ *  © 2022 Paul M Antoine
+ *  © 2021 Mike S
+ *  © 2021 Fred Decker
+ *  © 2020 Chris Harlow
+ *  © 2022 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
@@ -19,6 +24,52 @@
 #ifndef MotorDriver_h
 #define MotorDriver_h
 #include "FSH.h"
+#include "IODevice.h"
+#include "DCCTimer.h"
+
+#define setHIGH(fastpin)  *fastpin.inout |= fastpin.maskHIGH
+#define setLOW(fastpin)   *fastpin.inout &= fastpin.maskLOW
+#define isHIGH(fastpin)   (*fastpin.inout & fastpin.maskHIGH)
+#define isLOW(fastpin)    (!isHIGH(fastpin))
+
+#define TOKENPASTE(x, y) x ## y
+#define TOKENPASTE2(x, y) TOKENPASTE(x, y)
+
+#if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)
+#define HAVE_PORTA(X) X
+#define HAVE_PORTB(X) X
+#define HAVE_PORTC(X) X
+#endif
+#if defined(ARDUINO_AVR_UNO)
+#define HAVE_PORTB(X) X
+#endif
+#if defined(ARDUINO_ARCH_SAMD)
+#define PORTA REG_PORT_OUT0
+#define HAVE_PORTA(X) X
+#define PORTB REG_PORT_OUT1
+#define HAVE_PORTB(X) X
+#endif
+#if defined(ARDUINO_ARCH_STM32)
+#define PORTA GPIOA->ODR
+#define HAVE_PORTA(X) X
+#define PORTB GPIOB->ODR
+#define HAVE_PORTB(X) X
+#define PORTC GPIOC->ODR
+#define HAVE_PORTC(X) X
+#endif
+
+// if macros not defined as pass-through we define
+// them here as someting that is valid as a
+// statement and evaluates to false.
+#ifndef HAVE_PORTA
+#define HAVE_PORTA(X) byte TOKENPASTE2(Unique_, __LINE__) __attribute__((unused)) =0
+#endif
+#ifndef HAVE_PORTB
+#define HAVE_PORTB(X) byte TOKENPASTE2(Unique_, __LINE__) __attribute__((unused)) =0
+#endif
+#ifndef HAVE_PORTC
+#define HAVE_PORTC(X) byte TOKENPASTE2(Unique_, __LINE__) __attribute__((unused)) =0
+#endif
 
 // Virtualised Motor shield 1-track hardware Interface
 
@@ -26,63 +77,165 @@
 #define UNUSED_PIN 127 // inside int8_t
 #endif
 
-#if defined(__IMXRT1062__)
-struct FASTPIN {
-  volatile uint32_t *inout;
-  uint32_t maskHIGH;  
-  uint32_t maskLOW;  
+class pinpair {
+public:
+  pinpair(byte p1, byte p2) {
+    pin = p1;
+    invpin = p2;
+  };
+  byte pin = UNUSED_PIN;
+  byte invpin = UNUSED_PIN;
 };
+
+#if defined(__IMXRT1062__) || defined(ARDUINO_ARCH_ESP8266) || defined(ARDUINO_ARCH_ESP32) || defined(ARDUINO_ARCH_SAMD) || defined(ARDUINO_ARCH_STM32)
+typedef uint32_t portreg_t;
 #else
-struct FASTPIN {
-  volatile uint8_t *inout;
-  uint8_t maskHIGH;  
-  uint8_t maskLOW;  
-};
+typedef uint8_t portreg_t;
 #endif
 
+struct FASTPIN {
+  volatile portreg_t *inout;
+  portreg_t maskHIGH;
+  portreg_t maskLOW;
+  volatile portreg_t *shadowinout;
+};
+// The port registers that are shadowing
+// the real port registers. These are
+// defined in Motordriver.cpp
+extern volatile portreg_t shadowPORTA;
+extern volatile portreg_t shadowPORTB;
+extern volatile portreg_t shadowPORTC;
+
+enum class POWERMODE : byte { OFF, ON, OVERLOAD };
+
 class MotorDriver {
   public:
-    MotorDriver(byte power_pin, byte signal_pin, byte signal_pin2, int8_t brake_pin, 
+    
+    MotorDriver(int16_t power_pin, byte signal_pin, byte signal_pin2, int8_t brake_pin, 
                 byte current_pin, float senseFactor, unsigned int tripMilliamps, byte faultPin);
-    virtual void setPower( bool on);
-    virtual void setSignal( bool high);
-    virtual void setBrake( bool on);
-    virtual int  getCurrentRaw();
-    virtual unsigned int raw2mA( int raw);
-    virtual int mA2raw( unsigned int mA);
+    void setPower( POWERMODE mode);
+    POWERMODE getPower() { return powerMode;}
+    // as the port registers can be shadowed to get syncronized DCC signals
+    // we need to take care of that and we have to turn off interrupts if
+    // we setSignal() or setBrake() or setPower() during that time as
+    // otherwise the call from interrupt context can undo whatever we do
+    // from outside interrupt
+    void setBrake( bool on, bool interruptContext=false);
+  __attribute__((always_inline)) inline void setSignal( bool high) {
+      if (trackPWM) {
+	DCCTimer::setPWM(signalPin,high);
+      }
+      else {
+	if (high) {
+	  setHIGH(fastSignalPin);
+	  if (dualSignal) setLOW(fastSignalPin2);
+	}
+	else {
+	  setLOW(fastSignalPin);
+	  if (dualSignal) setHIGH(fastSignalPin2);
+	}
+      }
+    };
+    inline void enableSignal(bool on) {
+      if (on)
+	pinMode(signalPin, OUTPUT);
+      else
+	pinMode(signalPin, INPUT);
+    };
+    inline pinpair getSignalPin() { return pinpair(signalPin,signalPin2); };
+    void setDCSignal(byte speedByte);
+    inline void detachDCSignal() {
+#if defined(__arm__)
+      pinMode(brakePin, OUTPUT);
+#elif defined(ARDUINO_ARCH_ESP32)
+      ledcDetachPin(brakePin);
+#else
+      setDCSignal(128);
+#endif
+    };
+    int  getCurrentRaw(bool fromISR=false);
+    unsigned int raw2mA( int raw);
+    unsigned int mA2raw( unsigned int mA);
+    inline bool brakeCanPWM() {
+#if defined(ARDUINO_ARCH_ESP32) || defined(__arm__)
+      // TODO: on ARM we can use digitalPinHasPWM, and may wish/need to
+      return true;
+#else
+#ifdef digitalPinToTimer
+      return ((brakePin!=UNUSED_PIN) && (digitalPinToTimer(brakePin)));
+#else
+      return (brakePin<14 && brakePin >1);
+#endif //digitalPinToTimer
+#endif //ESP32/ARM
+    }
     inline int getRawCurrentTripValue() {
 	    return rawCurrentTripValue;
     }
     bool isPWMCapable();
     bool canMeasureCurrent();
-    static bool usePWM;
+    bool trackPWM = false; // this track uses PWM timer to generate the DCC waveform
     static bool commonFaultPin; // This is a stupid motor shield which has only a common fault pin for both outputs
     inline byte getFaultPin() {
 	return faultPin;
     }
+    inline void makeProgTrack(bool on) {  // let this output know it's a prog track.
+      isProgTrack = on;
+    }
+    void checkPowerOverload(bool useProgLimit, byte trackno);
+    inline void setTrackLetter(char c) {
+      trackLetter = c;
+    };
+#ifdef ANALOG_READ_INTERRUPT
+    bool sampleCurrentFromHW();
+    void startCurrentFromHW();
+#endif
   private:
+    char trackLetter = '?';
+    bool isProgTrack = false; // tells us if this is a prog track
     void  getFastPin(const FSH* type,int pin, bool input, FASTPIN & result);
     void  getFastPin(const FSH* type,int pin, FASTPIN & result) {
 	getFastPin(type, pin, 0, result);
     }
-    byte powerPin, signalPin, signalPin2, currentPin, faultPin, brakePin;
-    FASTPIN fastPowerPin,fastSignalPin, fastSignalPin2, fastBrakePin,fastFaultPin;
+    VPIN powerPin;
+    byte signalPin, signalPin2, currentPin, faultPin, brakePin;
+    FASTPIN fastSignalPin, fastSignalPin2, fastBrakePin,fastFaultPin;
     bool dualSignal;       // true to use signalPin2
     bool invertBrake;       // brake pin passed as negative means pin is inverted
-    float senseFactor;
+    bool invertPower;       // power pin passed as negative means pin is inverted
+    
+    // Raw to milliamp conversion factors avoiding float data types.
+    // Milliamps=rawADCreading * sensefactorInternal / senseScale
+    //
+    // senseScale is chosen as 256 to give enough scale for 2 decimal place 
+    // raw->mA conversion with an ultra fast optimised integer multiplication  
+    int senseFactorInternal;  // set to senseFactor * senseScale
+    static const int senseScale=256;
     int senseOffset;
     unsigned int tripMilliamps;
     int rawCurrentTripValue;
-#if defined(ARDUINO_TEENSY40) || defined(ARDUINO_TEENSY41)
-    static bool disableInterrupts() {
-      uint32_t primask;
-      __asm__ volatile("mrs %0, primask\n" : "=r" (primask)::);
-      __disable_irq();
-      return (primask == 0) ? true : false;
-    }
-    static void enableInterrupts(bool doit) {
-      if (doit) __enable_irq();
-    }
+    // current sampling
+    POWERMODE powerMode;
+    unsigned long lastSampleTaken;
+    unsigned int sampleDelay;
+    int progTripValue;
+    int  lastCurrent;
+#ifdef ANALOG_READ_INTERRUPT
+    volatile unsigned long sampleCurrentTimestamp;
+    volatile uint16_t sampleCurrent;
 #endif
+    int maxmA;
+    int tripmA;
+
+    // Wait times for power management. Unit: milliseconds
+    static const int  POWER_SAMPLE_ON_WAIT = 100;
+    static const int  POWER_SAMPLE_OFF_WAIT = 1000;
+    static const int  POWER_SAMPLE_OVERLOAD_WAIT = 20;
+    
+    // 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;
+
 };
 #endif

MotorDrivers.h

@@ -1,4 +1,7 @@
 /*
+ *  © 2022 Paul M. Antoine
+ *  © 2021 Fred Decker
+ *  © 2020-2022 Harald Barth
  *  (c) 2020 Chris Harlow. All rights reserved.
  *  (c) 2021 Fred Decker.  All rights reserved.
  *  (c) 2020 Harald Barth. All rights reserved.
@@ -36,17 +39,56 @@
 #define UNUSED_PIN 127 // inside int8_t
 #endif
 
+// The MotorDriver definition is:
+//
 // MotorDriver(byte power_pin, byte signal_pin, byte signal_pin2, int8_t brake_pin, byte current_pin,
 //             float senseFactor, unsigned int tripMilliamps, byte faultPin);
 //
-// If the brakePin is negative that means the sense
+// power_pin:     Turns the board on/off. Often called ENABLE or PWM on the shield
+// signal_pin:    Where the DCC signal goes in. Often called DIR on the shield
+// signal_pin2:   Inverse of signal_pin. A few shields need this as well, can be replace by hardware inverter
+// brake_pin:     When tuned on, brake is set - output shortened (*)
+// current_pin:   Current sense voltage pin from shield to ADC
+// senseFactor:   Relation between volts on current_pin and actual output current
+// tripMilliamps: Short circuit trip limit in milliampere, max 32767 (32.767A)
+// faultPin:      Some shields have a pin to to report a fault condition to the uCPU. High when fault occurs
+//
+// (*) If the brake_pin is negative that means the sense
 // of the brake pin on the motor bridge is inverted
 // (HIGH == release brake)
-//
-// Arduino standard Motor Shield
+
+// Arduino STANDARD Motor Shield, used on different architectures:
+
+#if defined(ARDUINO_ARCH_SAMD) || defined(ARDUINO_ARCH_STM32)
+// Setup for SAMD21 Sparkfun DEV board using Arduino standard Motor Shield R3 (MUST be R3
+// for 3v3 compatibility!!) senseFactor for 3.3v systems is 1.95 as calculated when using
+// 10-bit A/D samples, and for 12-bit samples it's more like 0.488, but we probably need
+// to tweak both these
 #define STANDARD_MOTOR_SHIELD F("STANDARD_MOTOR_SHIELD"),                                                 \
-                              new MotorDriver(3, 12, UNUSED_PIN, UNUSED_PIN, A0, 2.99, 2000, UNUSED_PIN), \
-                              new MotorDriver(11, 13, UNUSED_PIN, UNUSED_PIN, A1, 2.99, 2000, UNUSED_PIN)
+                              new MotorDriver(3, 12, UNUSED_PIN, 9, A0, 0.488, 1500, UNUSED_PIN), \
+                              new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 0.488, 1500, UNUSED_PIN)
+#define SAMD_STANDARD_MOTOR_SHIELD STANDARD_MOTOR_SHIELD
+#define STM32_STANDARD_MOTOR_SHIELD STANDARD_MOTOR_SHIELD
+
+#elif defined(ARDUINO_ARCH_ESP32)
+// STANDARD shield on an ESPDUINO-32 (ESP32 in Uno form factor). The shield must be eiter the
+// 3.3V compatible R3 version or it has to be modified to not supply more than 3.3V to the
+// analog inputs. Here we use analog inputs A2 and A3 as A0 and A1 are wired in a way so that
+// they are not useable at the same time as WiFi (what a bummer). The numbers below are the
+// actual GPIO numbers. In comments the numbers the pins have on an Uno.
+#define STANDARD_MOTOR_SHIELD F("STANDARD_MOTOR_SHIELD"),                                                 \
+    new MotorDriver(25/* 3*/, 19/*12*/, UNUSED_PIN, 13/*9*/, 35/*A2*/, 0.70, 1500, UNUSED_PIN), \
+    new MotorDriver(23/*11*/, 18/*13*/, UNUSED_PIN, 12/*8*/, 34/*A3*/, 0.70, 1500, UNUSED_PIN)
+
+#else
+// STANDARD shield on any Arduino Uno or Mega compatible with the original specification.
+#define STANDARD_MOTOR_SHIELD F("STANDARD_MOTOR_SHIELD"),                                                 \
+                              new MotorDriver(3, 12, UNUSED_PIN, 9, A0, 2.99, 1500, UNUSED_PIN), \
+                              new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 2.99, 1500, UNUSED_PIN)
+#define BRAKE_PWM_SWAPPED_MOTOR_SHIELD F("BPS_MOTOR_SHIELD"),                                       \
+                              new MotorDriver(-9 , 12, UNUSED_PIN, -3, A0, 2.99, 1500, UNUSED_PIN), \
+                              new MotorDriver(-8 , 13, UNUSED_PIN,-11, A1, 2.99, 1500, UNUSED_PIN)
+#endif
 
 // Pololu Motor Shield
 #define POLOLU_MOTOR_SHIELD F("POLOLU_MOTOR_SHIELD"),                                                 \
@@ -63,6 +105,17 @@
 //                          new MotorDriver(2, 8, UNUSED_PIN, -10, A1, 18, 3000, 12)
 // See Pololu dial_mc33926_shield_schematic.pdf and truth table on page 17 of the MC33926 data sheet.
 
+// Pololu Dual TB9051FTG Motor Shield
+// This is the shield without modifications. Unfortunately the TB9051FTG driver chip on
+// the shield makes short delays when direction is switched. That means that the chip
+// can NOT provide a standard conformant DCC signal independent how hard we try. If your
+// Decoders tolerate that signal, use it by all mean but it is not recommended. Without
+// modifications it uses the following pins below which means no HA waveform and no
+// RailCom on an Arduino Mega 2560 but the DCC signal is broken anyway.
+#define POLOLU_TB9051FTG F("POLOLU_TB9051FTG"),              \
+   new MotorDriver(2, 7, UNUSED_PIN,  -9, A0, 10, 2500,  6), \
+   new MotorDriver(4, 8, UNUSED_PIN, -10, A1, 10, 2500, 12)
+
 // Firebox Mk1
 #define FIREBOX_MK1 F("FIREBOX_MK1"),                                                  \
                     new MotorDriver(3, 6, 7, UNUSED_PIN, A5, 9.766, 5500, UNUSED_PIN), \
@@ -75,16 +128,61 @@
 
 // FunduMoto Motor Shield
 #define FUNDUMOTO_SHIELD F("FUNDUMOTO_SHIELD"),                                              \
-                         new MotorDriver(10, 12, UNUSED_PIN, 9, A0, 2.99, 2000, UNUSED_PIN), \
-                         new MotorDriver(11, 13, UNUSED_PIN, UNUSED_PIN, A1, 2.99, 2000, UNUSED_PIN)
+                         new MotorDriver(10, 12, UNUSED_PIN, UNUSED_PIN, A0, 2.99, 1500, UNUSED_PIN), \
+                         new MotorDriver(11, 13, UNUSED_PIN, UNUSED_PIN, A1, 2.99, 1500, UNUSED_PIN)
 
 // IBT_2 Motor Board for Main and Arduino Motor Shield for Prog
 #define IBT_2_WITH_ARDUINO F("IBT_2_WITH_ARDUINO_SHIELD"),                                              \
                          new MotorDriver(4, 5, 6, UNUSED_PIN, A5, 41.54, 5000, UNUSED_PIN), \
-                         new MotorDriver(11, 13, UNUSED_PIN, UNUSED_PIN, A1, 2.99, 2000, UNUSED_PIN)
+                         new MotorDriver(11, 13, UNUSED_PIN, UNUSED_PIN, A1, 2.99, 1500, UNUSED_PIN)
 // YFROBOT Motor Shield (V3.1)
 #define YFROBOT_MOTOR_SHIELD F("YFROBOT_MOTOR_SHIELD"), \
-    new MotorDriver(5, 4, UNUSED_PIN, UNUSED_PIN, A0, 2.99, 2000, UNUSED_PIN), \
-    new MotorDriver(6, 7, UNUSED_PIN, UNUSED_PIN, A1, 2.99, 2000, UNUSED_PIN)
+    new MotorDriver(5, 4, UNUSED_PIN, UNUSED_PIN, A0, 2.99, 1500, UNUSED_PIN), \
+    new MotorDriver(6, 7, UNUSED_PIN, UNUSED_PIN, A1, 2.99, 1500, UNUSED_PIN)
 
+// Makeblock ORION UNO like sized board with integrated motor driver
+// This is like an Uno with H-bridge and RJ12 contacts instead of pin rows.
+// No current sense. Barrel connector max 12V, Vmotor max 15V. 1.1A polyfuse as output protection.
+// Main is marked M1 and near RJ12 #5
+// Prog is marked M2 and near RJ12 #4
+// For details see
+// http://docs.makeblock.com/diy-platform/en/electronic-modules/main-control-boards/makeblock-orion.html
+#define ORION_UNO_INTEGRATED_SHIELD F("ORION_UNO_INTEGRATED_SHIELD"),		      \
+    new MotorDriver(6, 7, UNUSED_PIN, UNUSED_PIN, UNUSED_PIN, 1.0, 1100, UNUSED_PIN), \
+    new MotorDriver(5, 4, UNUSED_PIN, UNUSED_PIN, UNUSED_PIN, 1.0, 1100, UNUSED_PIN)
+
+// This is an example how to setup a motor shield definition for a motor shield connected
+// to an NANO EVERY board. You have to make the connectons from the shield to the board
+// as in this example or adjust the values yourself.
+#define NANOEVERY_EXAMPLE F("NANOEVERY_EXAMPLE"), \
+ new MotorDriver(5,  6, UNUSED_PIN, UNUSED_PIN, A0, 2.99, 1500, UNUSED_PIN),\
+ new MotorDriver(9, 10, UNUSED_PIN, UNUSED_PIN, A1, 2.99, 1500, UNUSED_PIN)
+
+// This is an example how to stack two standard motor shields. The upper shield
+// needs pins 3 8 9 11 12 13 A0 A1 disconnected from the lower shield and
+// jumpered instead like this:  2-3 6-8 7-9 4-13 5-11 10-12 A0-A4 A1-A5
+// Pin assigment table:
+// 2 Enable C  jumpered
+// 3 Enable A  direct
+// 4 Dir D     jumpered
+// 5 Enable D  jumpered
+// 6 Brake D   jumpered
+// 7 Brake C   jumpered
+// 8 Brake B   direct
+// 9 Brake A   direct
+// 10 Dir C    jumpered
+// 11 Enable B direct
+// 12 Dir A    direct
+// 13 Dir B    direct
+// A0 Sense A  direct
+// A1 Sense B  direct
+// A4 Sense C  jumpered
+// A5 Sense D  jumpered
+//
+#define STACKED_MOTOR_SHIELD F("STACKED_MOTOR_SHIELD"),\
+  new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 2.99, 1500, UNUSED_PIN), \
+  new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 2.99, 1500, UNUSED_PIN), \
+  new MotorDriver( 2, 10, UNUSED_PIN, 7, A4, 2.99, 1500, UNUSED_PIN), \
+  new MotorDriver( 5,  4, UNUSED_PIN, 6, A5, 2.99, 1500, UNUSED_PIN)
+//
 #endif

Outputs.cpp

@@ -1,5 +1,9 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
+ *  © 2021 Neil McKechnie
+ *  © 2021 Harald Barth
+ *  © 2020-2021 Fred Decker
+ *  © 2020-2021 Chris Harlow
+ *  All rights reserved.
  *  
  *  This file is part of Asbelos DCC API
  *
@@ -82,7 +86,9 @@ the state of any outputs being monitored or controlled by a separate interface o
 **********************************************************************/
 
 #include "Outputs.h"
+#ifndef DISABLE_EEPROM
 #include "EEStore.h"
+#endif
 #include "StringFormatter.h"
 #include "IODevice.h"
 
@@ -102,10 +108,11 @@ void  Output::activate(uint16_t s){
   data.active = s;                     // if s>0, set status to active, else inactive
   // set state of output pin to HIGH or LOW depending on whether bit zero of iFlag is set to 0 (ACTIVE=HIGH) or 1 (ACTIVE=LOW)
   IODevice::write(data.pin, s ^ data.invert);  
-
+#ifndef DISABLE_EEPROM
   // Update EEPROM if output has been stored.    
   if(EEStore::eeStore->data.nOutputs > 0 && num > 0)
     EEPROM.put(num, data.oStatus);
+#endif
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -141,7 +148,7 @@ bool Output::remove(uint16_t n){
 
 ///////////////////////////////////////////////////////////////////////////////
 // Static function to load configuration and state of all Outputs from EEPROM
-
+#ifndef DISABLE_EEPROM
 void Output::load(){
   struct OutputData data;
   Output *tt;
@@ -176,6 +183,7 @@ void Output::store(){
   }
 
 }
+#endif
 
 ///////////////////////////////////////////////////////////////////////////////
 // Static function to create an Output object

Outputs.h

@@ -1,5 +1,8 @@
 /*
- *  © 2020, Chris Harlow. All rights reserved.
+ *  © 2021 Harald Barth
+ *  © 2021 Fred Decker
+ *  © 2020 Chris Harlow
+ *  All rights reserved.
  *  
  *  This file is part of Asbelos DCC API
  *
@@ -48,8 +51,10 @@ public:
   bool isActive();
   static Output* get(uint16_t);
   static bool remove(uint16_t);
+#ifndef DISABLE_EEPROM
   static void load();
   static void store();
+#endif
   static Output *create(uint16_t, VPIN, int, int=0);
   static Output *firstOutput;
   struct OutputData data;

README.md

@@ -17,12 +17,12 @@ Both CommandStation-EX and BaseStation-Classic support much of the NMRA Digital
 * Control of all cab functions F0-F28 and F29-F68
 * Main Track: Write configuration variable bytes and set/clear specific configuration variable (CV) bits (aka Programming on Main or POM)
 * Programming Track: Same as the main track with the addition of reading configuration variable bytes
-* And manu more custom features. see [What's new in CommandStation-EX?](#whats-new-in-commandstation-ex)
+* And many more custom features. see [What's new in CommandStation-EX?](#whats-new-in-commandstation-ex)
 
 
 # What’s in this Repository?
 
-This repository, CommandStation-EX, contains a complete DCC++ EX Commmand Station sketch designed for compiling and uploading into an Arduino Uno, Mega, or Nano.  All sketch files are in the folder named CommandStation-EX and its subforlders. 
+This repository, CommandStation-EX, contains a complete DCC++ EX Commmand Station sketch designed for compiling and uploading into an Arduino Uno, Mega, or Nano.
 
 To utilize this sketch, you can use the following: 
 
@@ -69,7 +69,7 @@ in config.h.
 * Automatic slot (register) management 
 * Automation (coming soon)
 
-NOTE: DCC-EX is a major rewrite to the code. We started over and rebuilt it from the ground up! For what that means to you, click [HERE](notes/rewrite.md).
+NOTE: DCC-EX is a major rewrite to the code. We started over and rebuilt it from the ground up! For what that means, you can read [HERE](https://dcc-ex.com/about/rewrite.html).
 
 # More information
 You can learn more at the [DCC++ EX website](https://dcc-ex.com/)

RMFT2.cpp

@@ -1,769 +0,0 @@
-/*
- *  © 2020,2021 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 <Arduino.h>
-#include "RMFT2.h"
-#include "DCC.h"
-#include "DCCWaveform.h"
-#include "DIAG.h"
-#include "WiThrottle.h"
-#include "DCCEXParser.h"
-#include "Turnouts.h"
-
-
-// Command parsing keywords
-const int16_t HASH_KEYWORD_EXRAIL=15435;    
-const int16_t HASH_KEYWORD_ON = 2657;
-const int16_t HASH_KEYWORD_START=23232;
-const int16_t HASH_KEYWORD_RESERVE=11392;
-const int16_t HASH_KEYWORD_FREE=-23052;
-const int16_t HASH_KEYWORD_LATCH=1618;  
-const int16_t HASH_KEYWORD_UNLATCH=1353;
-const int16_t HASH_KEYWORD_PAUSE=-4142;
-const int16_t HASH_KEYWORD_RESUME=27609;
-const int16_t HASH_KEYWORD_KILL=5218;
-const int16_t HASH_KEYWORD_ROUTES=-3702;
-
-// One instance of RMFT clas is used for each "thread" in the automation.
-// Each thread manages a loco on a journey through the layout, and/or may manage a scenery automation.
-// The thrrads exist in a ring, each time through loop() the next thread in the ring is serviced.
-
-// Statics 
-const int16_t LOCO_ID_WAITING=-99; // waiting for loco id from prog track
-int16_t RMFT2::progtrackLocoId;  // used for callback when detecting a loco on prograck
-bool RMFT2::diag=false;      // <D EXRAIL ON>  
-RMFT2 * RMFT2::loopTask=NULL; // loopTask contains the address of ONE of the tasks in a ring.
-RMFT2 * RMFT2::pausingTask=NULL; // Task causing a PAUSE.
- // when pausingTask is set, that is the ONLY task that gets any service,
- // and all others will have their locos stopped, then resumed after the pausing task resumes.
-byte RMFT2::flags[MAX_FLAGS];
-
-#define GET_OPCODE GETFLASH(RMFT2::RouteCode+progCounter)
-#define GET_OPERAND(n) GETFLASHW(RMFT2::RouteCode+progCounter+1+(n*3))
-#define SKIPOP progCounter+=3
-
-/* static */ void RMFT2::begin() { 
-  DCCEXParser::setRMFTFilter(RMFT2::ComandFilter);
-  for (int f=0;f<MAX_FLAGS;f++) flags[f]=0;
-  int progCounter;
-  // first pass startup, define any turnouts or servos, set signals red and count size.
-  for (progCounter=0;; SKIPOP){
-     byte opcode=GET_OPCODE;
-     if (opcode==OPCODE_ENDEXRAIL) break;
-
-     switch (opcode) {
-     case OPCODE_AT:
-     case OPCODE_AFTER:
-     case OPCODE_IF:
-     case OPCODE_IFNOT:
-       int16_t pin = (int16_t)GET_OPERAND(0);
-       if (pin<0) pin = -pin;
-       IODevice::configureInput((VPIN)pin,true);
-     }
-
-     if (opcode==OPCODE_SIGNAL) {
-      VPIN red=GET_OPERAND(0);
-      VPIN amber=GET_OPERAND(1);
-      VPIN green=GET_OPERAND(2);
-      IODevice::write(red,true);
-      if (amber) IODevice::write(amber,false);
-      IODevice::write(green,false);
-      continue;
-     }
-     
-     if (opcode==OPCODE_TURNOUT) {
-      VPIN id=GET_OPERAND(0);
-      int addr=GET_OPERAND(1);
-      byte subAddr=GET_OPERAND(2);
-      DCCTurnout::create(id,addr,subAddr);
-      continue;
-     }
-
-     if (opcode==OPCODE_SERVOTURNOUT) {
-      int16_t id=GET_OPERAND(0);
-      VPIN pin=GET_OPERAND(1);
-      int activeAngle=GET_OPERAND(2);
-      int inactiveAngle=GET_OPERAND(3);
-      int profile=GET_OPERAND(4);
-      ServoTurnout::create(id,pin,activeAngle,inactiveAngle,profile);
-      continue;
-     }
-
-     if (opcode==OPCODE_PINTURNOUT) {
-      int16_t id=GET_OPERAND(0);
-      VPIN pin=GET_OPERAND(1);
-      VpinTurnout::create(id,pin);
-      continue;
-     }
-     // other opcodes are not needed on this pass
-  } 
-  SKIPOP; // include ENDROUTES opcode
-  DIAG(F("EXRAIL %db, MAX_FLAGS=%d"), progCounter,MAX_FLAGS);
-  new RMFT2(0); // add the startup route
-}
-
-// 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 
-    bool reject=false;
-    switch(opcode) {
-        
-     case 'D':
-        if (p[0]==HASH_KEYWORD_EXRAIL) { // <D EXRAIL ON/OFF>
-           diag = paramCount==2 && (p[1]==HASH_KEYWORD_ON || p[1]==1);
-           opcode=0;
-        }
-        break;
-          
-     case '/':  // New EXRAIL command
-          reject=!parseSlash(stream,paramCount,p);
-          opcode=0;
-          break;
-          
-     default:  // other commands pass through 
-     break;       
-   }
- if (reject) {
-   opcode=0;
-   StringFormatter::send(stream,F("<X>"));
-   }
-}
-     
-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) {
-                   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) { // 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"));
-                     }                 
-                 }
-                 StringFormatter::send(stream,F(" *>\n"));
-                 return true;
-            }
-          switch (p[0]) {
-            case HASH_KEYWORD_PAUSE: // </ 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 HASH_KEYWORD_RESUME: // </ 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 HASH_KEYWORD_START: // </ 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=locateRouteStart(route);                 
-                  if (pc<0) return false;
-                    RMFT2* task=new RMFT2(pc);
-                    task->loco=cab;                    
-                 }
-              return true;
-
-            case HASH_KEYWORD_ROUTES: // </ ROUTES > JMRI withrottle support 
-                 if (paramCount>1) return false;
-                 StringFormatter::send(stream,F("</ROUTES "));
-                 emitWithrottleRouteList(stream);                                  
-                 StringFormatter::send(stream,F(">"));
-              return true;
-              
-            default:
-              break;
-          }
-          
-          // all other / commands take 1 parameter 0 to MAX_FLAGS-1     
-
-          if (paramCount!=2 || p[1]<0  || p[1]>=MAX_FLAGS) return false;
-
-          switch (p[0]) {  
-               case HASH_KEYWORD_KILL: // Kill taskid
-                    {
-                    RMFT2 * task=loopTask;
-                    while(task) {
-                      if (task->taskId==p[1]) {
-                         delete task;
-                         return  true;
-                      }
-                      task=task->next;      
-                      if (task==loopTask) break;      
-                    }
-                 }
-                 return false;
-                    
-            case HASH_KEYWORD_RESERVE:  // force reserve a section
-                 setFlag(p[1],SECTION_FLAG);
-                 return true;
-    
-            case HASH_KEYWORD_FREE:  // force free a section
-                 setFlag(p[1],0,SECTION_FLAG);
-                 return true;
-                
-            case HASH_KEYWORD_LATCH:
-                 setFlag(p[1], LATCH_FLAG);
-                 return true;
-   
-            case HASH_KEYWORD_UNLATCH:
-                 setFlag(p[1], 0, LATCH_FLAG);
-                 return true;
-                  
-            default:
-                 return false;                 
-          }
-    }
-
-
-// This emits Routes and Automations to Withrottle
-// Automations are given a state to set the button to "handoff" which implies 
-// handing over the loco to the automation.
-// Routes are given "Set" buttons and do not cause the loco to be handed over. 
-void RMFT2::emitWithrottleRouteList(Print* stream) {
-   StringFormatter::send(stream,F("PRT]\\[Routes}|{Route]\\[Set}|{2]\\[Handoff}|{4\nPRL"));
-   emitWithrottleDescriptions(stream);
-   StringFormatter::send(stream,F("\n"));
-}
-
-
-RMFT2::RMFT2(int progCtr) {
-  progCounter=progCtr;
-
-  // get an unused  task id from the flags table 
-  taskId=255; // in case of overflow
-  for (int f=0;f<MAX_FLAGS;f++) {
-    if (!getFlag(f,TASK_FLAG)) {
-      taskId=f;
-      setFlag(f, TASK_FLAG);
-      break;
-    }
-  }
-  delayTime=0;
-  loco=0;
-  speedo=0;
-  forward=true;
-  invert=false;
-  stackDepth=0;
-  onTurnoutId=0; // Not handling an ONTHROW/ONCLOSE
-   
-  // chain into ring of RMFTs
-  if (loopTask==NULL) {
-    loopTask=this;
-    next=this;
-  }
-  else {
-        next=loopTask->next;
-        loopTask->next=this;
-  }
-}
-
-
-RMFT2::~RMFT2() {
-  driveLoco(1); // ESTOP my loco if any 
-  setFlag(taskId,0,TASK_FLAG); // we are no longer using this id
-  if (next==this) loopTask=NULL;
-  else for (RMFT2* ring=next;;ring=ring->next) if (ring->next == this) {
-           ring->next=next;
-           loopTask=next;
-           break;
-       }
-}
-
-void RMFT2::createNewTask(int route, uint16_t cab) {
-      int pc=locateRouteStart(route);
-      if (pc<0) return;
-      RMFT2* task=new RMFT2(pc);
-      task->loco=cab;
-}
-
-   
-int RMFT2::locateRouteStart(int16_t _route) {
-  if (_route==0) return 0; // Route 0 is always start of ROUTES for default startup 
-  for (int progCounter=0;;SKIPOP) {
-    byte opcode=GET_OPCODE;
-    if (opcode==OPCODE_ENDEXRAIL) {
-      DIAG(F("RMFT2 sequence %d not found"), _route);
-      return -1;
-    }
-    if ((opcode==OPCODE_ROUTE || opcode==OPCODE_AUTOMATION || opcode==OPCODE_SEQUENCE) 
-       &&  _route==(int)GET_OPERAND(0)) return progCounter;
-  }
-  return -1;
-}
-
-
-void RMFT2::driveLoco(byte speed) {
-     if (loco<=0) return;  // Prevent broadcast! 
-     if (diag) DIAG(F("EXRAIL drive %d %d %d"),loco,speed,forward^invert);
-     if (DCCWaveform::mainTrack.getPowerMode()==POWERMODE::OFF) {
-        DCCWaveform::mainTrack.setPowerMode(POWERMODE::ON); 
-        Serial.println(F("<p1>")); // tell JMRI
-     }
-     DCC::setThrottle(loco,speed, forward^invert);
-     speedo=speed;
-}
-
-bool RMFT2::readSensor(uint16_t sensorId) {
-  // Exrail operands are unsigned but we need the signed version as inserted by the macros.  
-  int16_t sId=(int16_t) sensorId;
-
-  VPIN vpin=abs(sId);
-  if (getFlag(vpin,LATCH_FLAG)) return true; // latched on
-
-  // negative sensorIds invert the logic (e.g. for a break-beam sensor which goes OFF when detecting)
-  bool s= IODevice::read(vpin) ^ (sId<0);
-  if (s && diag) DIAG(F("EXRAIL Sensor %d hit"),sId);
-  return s;
-}
-
-bool RMFT2::skipIfBlock() {
-  // returns false if killed
-  short nest = 1;
-  while (nest > 0) {
-    SKIPOP;
-    byte opcode =  GET_OPCODE;
-    switch(opcode) {
-      case OPCODE_ENDEXRAIL: 
-           kill(F("missing ENDIF"), nest);
-           return false;  
-      case OPCODE_IF:
-      case OPCODE_IFNOT:
-      case OPCODE_IFRANDOM:
-      case OPCODE_IFRESERVE:
-           nest++;
-           break;
-      case OPCODE_ENDIF:
-           nest--;
-           break;
-      default:
-      break;
-    }
-  }
-  return true; 
-}
-
-
-
-/* static */ void RMFT2::readLocoCallback(int16_t cv) {
-     progtrackLocoId=cv;
-}
-
-void RMFT2::loop() {
-  
-  // Round Robin call to a RMFT task each time 
-     if (loopTask==NULL) return; 
-     
-     loopTask=loopTask->next;
- 
-     if (pausingTask==NULL || pausingTask==loopTask) loopTask->loop2();
-}    
-
-  
-void RMFT2::loop2() {
-   if (delayTime!=0 && millis()-delayStart < delayTime) return;
-     
-  byte opcode = GET_OPCODE;
-  int16_t operand =  GET_OPERAND(0);
-  // if (diag) DIAG(F("RMFT2 %d %d"),opcode,operand); 
-  // Attention: Returning from this switch leaves the program counter unchanged.
-  //            This is used for unfinished waits for timers or sensors.
-  //            Breaking from this switch will step to the next step in the route. 
-  switch ((OPCODE)opcode) {
-    
-    case OPCODE_THROW:
-         Turnout::setClosed(operand, false);
-         break;
-          
-    case OPCODE_CLOSE:
-         Turnout::setClosed(operand, true);
-         break; 
-    
-    case OPCODE_REV:
-      forward = false;
-      driveLoco(operand);
-      break;
-    
-    case OPCODE_FWD:
-      forward = true;
-      driveLoco(operand);
-      break;
-      
-    case OPCODE_SPEED:
-      driveLoco(operand);
-      break;
-    
-    case OPCODE_INVERT_DIRECTION:
-      invert= !invert;
-      driveLoco(speedo);
-      break;
-      
-    case OPCODE_RESERVE:
-      if (getFlag(operand,SECTION_FLAG)) {
-        driveLoco(0);
-        delayMe(500);
-        return;
-      }
-      setFlag(operand,SECTION_FLAG);
-      break;
-    
-    case OPCODE_FREE:
-      setFlag(operand,0,SECTION_FLAG);
-      break;
-    
-    case OPCODE_AT:
-      if (readSensor(operand)) break;
-      delayMe(50);
-      return;
-    
-    case OPCODE_AFTER: // waits for sensor to hit and then remain off for 0.5 seconds. (must come after an AT operation)
-      if (readSensor(operand)) {
-        // reset timer to half a second and keep waiting
-        waitAfter=millis();
-        delayMe(50);
-        return; 
-      }
-      if (millis()-waitAfter < 500 ) return;   
-      break;
-    
-    case OPCODE_LATCH:
-      setFlag(operand,LATCH_FLAG);
-      break;
-    
-    case OPCODE_UNLATCH:
-      setFlag(operand,0,LATCH_FLAG);
-      break;
-
-    case OPCODE_SET:
-      IODevice::write(operand,true);
-      break;
-  
-    case OPCODE_RESET:
-      IODevice::write(operand,false);
-      break;
-    
-    case OPCODE_PAUSE:
-         DCC::setThrottle(0,1,true);  // pause all locos on the track
-         pausingTask=this;
-         break;
-
-    case OPCODE_POM:
-        if (loco) DCC::writeCVByteMain(loco, operand, GET_OPERAND(1));
-        break;
-
-    case OPCODE_POWEROFF:
-        DCCWaveform::mainTrack.setPowerMode(POWERMODE::OFF);
-        DCCWaveform::progTrack.setPowerMode(POWERMODE::OFF);
-        DCC::setProgTrackSyncMain(false);       
-        Serial.println(F("<p0>")); // Tell JMRI
-        break;
-
-    case OPCODE_RESUME:
-         pausingTask=NULL;
-         driveLoco(speedo);
-         for (RMFT2 * t=next; t!=this;t=t->next) if (t->loco >0) t->driveLoco(t->speedo);
-          break;        
-    
-    case OPCODE_IF: // do next operand if sensor set
-      if (!readSensor(operand)) if (!skipIfBlock()) return;
-      break;
-    
-    case OPCODE_IFNOT: // do next operand if sensor not set
-      if (readSensor(operand)) if (!skipIfBlock()) return;
-      break;
-   
-    case OPCODE_IFRANDOM: // do block on random percentage
-      if (random(100)>=operand) if (!skipIfBlock()) return;
-      break;
-   
-    case OPCODE_IFRESERVE: // do block if we successfully RERSERVE
-      if (!getFlag(operand,SECTION_FLAG)) setFlag(operand,SECTION_FLAG);
-      else if (!skipIfBlock()) return;
-      break;
-      
-    case OPCODE_ENDIF:
-      break;
-    
-    case OPCODE_DELAY:
-      delayMe(operand*100L);
-      break;
-   
-    case OPCODE_DELAYMINS:
-      delayMe(operand*60L*1000L);
-      break;
-    
-    case OPCODE_RANDWAIT:
-      delayMe(random(operand)*100L);
-      break;
-    
-    case OPCODE_RED:
-      doSignal(operand,true,false,false);
-      break;
-    
-    case OPCODE_AMBER:
-      doSignal(operand,false,true,false);
-      break;
-    
-    case OPCODE_GREEN:
-      doSignal(operand,false,false,true);
-      break;
-       
-    case OPCODE_FON:      
-      if (loco) DCC::setFn(loco,operand,true);
-      break;
-     
-    case OPCODE_FOFF:
-      if (loco) DCC::setFn(loco,operand,false);
-      break;
-    
-    case OPCODE_XFON:      
-      DCC::setFn(operand,GET_OPERAND(1),true);
-      break;
-   
-    case OPCODE_XFOFF:      
-      DCC::setFn(operand,GET_OPERAND(1),false);
-      break;
-   
-    case OPCODE_FOLLOW:
-      progCounter=locateRouteStart(operand);
-      if (progCounter<0) kill(F("FOLLOW unknown"), operand); 
-      return;
-  
-    case OPCODE_CALL:
-      if (stackDepth==MAX_STACK_DEPTH) {
-        kill(F("CALL stack"), stackDepth);
-        return;
-      }
-      callStack[stackDepth++]=progCounter+3;
-      progCounter=locateRouteStart(operand);
-      if (progCounter<0) kill(F("CALL unknown"),operand); 
-      return;
-
-    case OPCODE_RETURN:
-      if (stackDepth==0) {
-        kill(F("RETURN stack"));
-        return;
-      }
-      progCounter=callStack[--stackDepth];
-      return;
-      
-    case OPCODE_ENDTASK:
-    case OPCODE_ENDEXRAIL:
-      kill();
-      return;
-      
-    case OPCODE_JOIN:
-       DCCWaveform::mainTrack.setPowerMode(POWERMODE::ON); 
-       DCCWaveform::progTrack.setPowerMode(POWERMODE::ON); 
-       DCC::setProgTrackSyncMain(true);
-       Serial.println(F("<p1 JOIN>")); // Tell JMRI
-       break;
-
-    case OPCODE_UNJOIN:
-       DCC::setProgTrackSyncMain(false);
-       break;
-       
-    case OPCODE_READ_LOCO1: // READ_LOCO is implemented as 2 separate opcodes
-       progtrackLocoId=LOCO_ID_WAITING;  // Nothing found yet
-       DCC::getLocoId(readLocoCallback);
-       break;
-      
-      case OPCODE_READ_LOCO2:
-       if (progtrackLocoId==LOCO_ID_WAITING) {
-        delayMe(100);
-        return; // still waiting for callback
-       }
-       if (progtrackLocoId<0) {
-        kill(F("No Loco Found"),progtrackLocoId);
-        return; // still waiting for callback
-       }
-       
-       loco=progtrackLocoId;
-       speedo=0;
-       forward=true;
-       invert=false;
-       break;
-       
-       case OPCODE_START:
-           {
-            int newPc=locateRouteStart(operand);
-            if (newPc<0) break; 
-            new RMFT2(newPc); 
-           }
-           break;
-           
-      case OPCODE_SENDLOCO:  // cab, route
-           {
-            int newPc=locateRouteStart(GET_OPERAND(1));
-            if (newPc<0) break; 
-            RMFT2* newtask=new RMFT2(newPc); // create new task 
-            newtask->loco=operand; 
-           }
-           break;
-           
-       case OPCODE_SETLOCO:
-           {
-             loco=operand; 
-             speedo=0;
-             forward=true;
-             invert=false;
-            }
-       break;
-
-          
-       case OPCODE_SERVO: // OPCODE_SERVO,V(vpin),OPCODE_PAD,V(position),OPCODE_PAD,V(profile),OPCODE_PAD,V(duration)
-        IODevice::writeAnalogue(operand,GET_OPERAND(1),GET_OPERAND(2),GET_OPERAND(3));          
-        break;
-       
-       case OPCODE_WAITFOR: // OPCODE_SERVO,V(pin)
-            if (IODevice::isBusy(operand)) {
-              delayMe(100);
-              return;
-            }
-            break;
-
-       case OPCODE_PRINT:
-            printMessage(operand);
-            break;
-               
-       case OPCODE_ROUTE:
-       case OPCODE_AUTOMATION:
-       case OPCODE_SEQUENCE:
-          if (diag) DIAG(F("EXRAIL begin(%d)"),operand);
-          break;
-
-       case OPCODE_PAD: // Just a padding for previous opcode needing >1 operad byte.
-       case OPCODE_SIGNAL: // Signal definition ignore at run time
-       case OPCODE_TURNOUT: // Turnout definition ignored at runtime
-       case OPCODE_SERVOTURNOUT: // Turnout definition ignored at runtime
-       case OPCODE_PINTURNOUT: // Turnout definition ignored at runtime
-       case OPCODE_ONCLOSE: // Turnout event catcers ignored here
-       case OPCODE_ONTHROW: // Turnout definition ignored at runtime
-       break;
-    
-    default:
-      kill(F("INVOP"),operand);
-    }
-    // Falling out of the switch means move on to the next opcode
-    SKIPOP;
-}
-
-void RMFT2::delayMe(long delay) {
-     delayTime=delay;
-     delayStart=millis();
-}
-
-void RMFT2::setFlag(VPIN id,byte onMask, byte offMask) {  
-   if (FLAGOVERFLOW(id)) return; // Outside range limit
-   byte f=flags[id];
-   f &= ~offMask;
-   f |= onMask;
-   flags[id]=f;
-}
-
-bool RMFT2::getFlag(VPIN id,byte mask) {
-   if (FLAGOVERFLOW(id)) return 0; // Outside range limit
-   return flags[id]&mask;   
-}
-
-void RMFT2::kill(const FSH * reason, int operand) {
-     if (reason) DIAG(F("EXRAIL ERROR pc=%d, cab=%d, %S %d"), progCounter,loco, reason, operand);
-     else if (diag) DIAG(F("ENDTASK at pc=%d"), progCounter); 
-     delete this;
-}
-
-/* static */ void RMFT2::doSignal(VPIN id,bool red, bool amber, bool green) { 
-  // CAUTION: hides class member progCounter
-  for (int progCounter=0;; SKIPOP){
-     byte opcode=GET_OPCODE;
-     if (opcode==OPCODE_ENDEXRAIL) return;
-     if (opcode!=OPCODE_SIGNAL) continue;
-     byte redpin=GET_OPERAND(0);
-     if (redpin!=id)continue;
-     byte amberpin=GET_OPERAND(1);
-     byte greenpin=GET_OPERAND(2);
-     // If amberpin is zero, synthesise amber from red+green
-     IODevice::write(redpin,red || (amber && (amberpin==0)));
-     if (amberpin) IODevice::write(amberpin,amber);
-     if (greenpin) IODevice::write(greenpin,green || (amber && (amberpin==0)));
-     return;
-   }
-  } 
- void RMFT2::turnoutEvent(int16_t turnoutId, bool closed) {
-    
-    // Check we dont already have a task running this turnout
-    RMFT2 * task=loopTask;                 
-    while(task) {
-      if (task->onTurnoutId==turnoutId) {
-        DIAG(F("Recursive ONTHROW/ONCLOSE for Turnout %d"),turnoutId);
-        return;
-        }
-      task=task->next;      
-      if (task==loopTask) break;      
-      }
-    // Hunt for an ONTHROW/ONCLOSE for this turnout   
-    byte huntFor=closed ?  OPCODE_ONCLOSE : OPCODE_ONTHROW ;
-    // caution hides class progCounter;
-    for (int progCounter=0;; SKIPOP){
-     byte opcode=GET_OPCODE;
-     if (opcode==OPCODE_ENDEXRAIL) return;
-     if (opcode!=huntFor) continue;
-     if (turnoutId!=(int16_t)GET_OPERAND(0)) continue;
-     task=new RMFT2(progCounter);  // new task starts at this instruction
-     task->onTurnoutId=turnoutId; // flag for recursion detector
-     return;
-   }
- }
- 
- void RMFT2::printMessage2(const FSH * msg) {
-        DIAG(F("EXRAIL(%d) %S"),loco,msg);
-   }
-
-// This is called by emitRouteDescriptions to emit a withrottle description for a route or autoomation. 
-void RMFT2::emitRouteDescription(Print * stream, char type, int id, const FSH * description) {
- StringFormatter::send(stream,F("]\\[%c%d}|{%S}|{%c"),
-              type,id,description, type=='R'?'2':'4');
-}
- 

RMFT2.h

@@ -1,117 +0,0 @@
-/*
- *  © 2020, 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 RMFT2_H
-#define RMFT2_H
-#include "FSH.h"
-#include "IODevice.h"
-   
-// The following are the operation codes (or instructions) for a kind of virtual machine.
-// Each instruction is normally 2 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_FWD,OPCODE_REV,OPCODE_SPEED,OPCODE_INVERT_DIRECTION,
-             OPCODE_RESERVE,OPCODE_FREE,
-             OPCODE_AT,OPCODE_AFTER,
-             OPCODE_LATCH,OPCODE_UNLATCH,OPCODE_SET,OPCODE_RESET,
-             OPCODE_IF,OPCODE_IFNOT,OPCODE_ENDIF,OPCODE_IFRANDOM,OPCODE_IFRESERVE,
-             OPCODE_DELAY,OPCODE_DELAYMINS,OPCODE_RANDWAIT,
-             OPCODE_FON,OPCODE_FOFF,OPCODE_XFON,OPCODE_XFOFF,
-             OPCODE_RED,OPCODE_GREEN,OPCODE_AMBER,
-             OPCODE_SERVO,OPCODE_SIGNAL,OPCODE_TURNOUT,OPCODE_WAITFOR,
-             OPCODE_PAD,OPCODE_FOLLOW,OPCODE_CALL,OPCODE_RETURN,
-             OPCODE_JOIN,OPCODE_UNJOIN,OPCODE_READ_LOCO1,OPCODE_READ_LOCO2,OPCODE_POM,
-             OPCODE_START,OPCODE_SETLOCO,OPCODE_SENDLOCO,
-             OPCODE_PAUSE, OPCODE_RESUME,OPCODE_POWEROFF,
-             OPCODE_ONCLOSE, OPCODE_ONTHROW, OPCODE_SERVOTURNOUT, OPCODE_PINTURNOUT,
-             OPCODE_PRINT,
-             OPCODE_ROUTE,OPCODE_AUTOMATION,OPCODE_SEQUENCE,OPCODE_ENDTASK,OPCODE_ENDEXRAIL
-             };
-
-
- 
-  // Flag bits for status of hardware and TPL
-  static const byte SECTION_FLAG = 0x01;
-  static const byte LATCH_FLAG = 0x02;
-  static const byte TASK_FLAG = 0x04;
-
-  static const byte  MAX_STACK_DEPTH=4;
- 
-   static const short MAX_FLAGS=256;
-  #define FLAGOVERFLOW(x) x>=MAX_FLAGS
-
- 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 emitWithrottleRouteList(Print* stream); 
-    static void createNewTask(int route, uint16_t cab);
-    static void turnoutEvent(int16_t id, bool closed);  
-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 void setFlag(VPIN id,byte onMask, byte OffMask=0);
-    static bool getFlag(VPIN id,byte mask);   
-    static int locateRouteStart(int16_t _route);
-    static int16_t progtrackLocoId;
-    static void doSignal(VPIN id,bool red, bool amber, bool green); 
-    static void emitRouteDescription(Print * stream, char type, int id, const FSH * description);
-    static void emitWithrottleDescriptions(Print * stream);
-    
-    static RMFT2 * loopTask;
-    static RMFT2 * pausingTask;
-    void delayMe(long millisecs);
-    void driveLoco(byte speedo);
-    bool readSensor(uint16_t sensorId);
-    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);
-
-    
-   static bool diag;
-   static const  FLASH  byte RouteCode[];
-   static byte flags[MAX_FLAGS];
- 
-  // 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 waitAfter; // Used by OPCODE_AFTER
-    unsigned long  delayTime;
-    byte  taskId;
-    
-    uint16_t loco;
-    bool forward;
-    bool invert;
-    byte speedo;
-    int16_t onTurnoutId;
-    byte stackDepth;
-    int callStack[MAX_STACK_DEPTH];
-};
-#endif

RMFTMacros.h

@@ -1,311 +0,0 @@
-/*
- *  © 2020,2021 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 RMFTMacros_H
-#define RMFTMacros_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 incliding 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) and LCD(row,msg) is implemented in a separate pass to create 
-// a getMessageText(id) function.  
-
-// CAUTION: The macros below are multiple passed over myAutomation.h
-
-// Pass 1 Implements aliases and 
-// converts descriptions to  withrottle format emitter function
-// Most macros are simply ignored in this pass.
-
-
-#define ALIAS(name,value) const int name=value; 
-#define EXRAIL  void  RMFT2::emitWithrottleDescriptions(Print * stream) {(void)stream;
-#define ROUTE(id, description) emitRouteDescription(stream,'R',id,F(description));
-#define AUTOMATION(id, description) emitRouteDescription(stream,'A',id,F(description));
-#define ENDEXRAIL  }
- 
-#define AFTER(sensor_id)
-#define AMBER(signal_id)
-#define AT(sensor_id)
-#define CALL(route) 
-#define CLOSE(id) 
-#define DELAY(mindelay)
-#define DELAYMINS(mindelay)
-#define DELAYRANDOM(mindelay,maxdelay) 
-#define DONE
-#define ENDIF  
-#define ENDTASK
-#define ESTOP 
-#define FADE(pin,value,ms)
-#define FOFF(func)
-#define FOLLOW(route) 
-#define FON(func) 
-#define FREE(blockid) 
-#define FWD(speed) 
-#define GREEN(signal_id)
-#define IF(sensor_id) 
-#define IFNOT(sensor_id)
-#define IFRANDOM(percent) 
-#define IFRESERVE(block)
-#define INVERT_DIRECTION 
-#define JOIN 
-#define LATCH(sensor_id) 
-#define LCD(row,msg) 
-#define LCN(msg) 
-#define ONCLOSE(turnout_id)
-#define ONTHROW(turnout_id) 
-#define PAUSE
-#define PRINT(msg) 
-#define POM(cv,value)
-#define POWEROFF
-#define READ_LOCO 
-#define RED(signal_id) 
-#define RESERVE(blockid) 
-#define RESET(pin) 
-#define RESUME 
-#define RETURN 
-#define REV(speed) 
-#define START(route) 
-#define SENDLOCO(cab,route) 
-#define SERIAL(msg) 
-#define SERIAL1(msg) 
-#define SERIAL2(msg) 
-#define SERIAL3(msg) 
-#define SERVO(id,position,profile) 
-#define SERVO2(id,position,duration) 
-#define SETLOCO(loco) 
-#define SET(pin) 
-#define SEQUENCE(id) 
-#define SPEED(speed) 
-#define STOP 
-#undef SIGNAL
-#define SIGNAL(redpin,amberpin,greenpin) 
-#define SERVO_TURNOUT(id,pin,activeAngle,inactiveAngle,profile) 
-#define PIN_TURNOUT(id,pin) 
-#define THROW(id)  
-#define TURNOUT(id,addr,subaddr) 
-#define UNJOIN 
-#define UNLATCH(sensor_id) 
-#define WAITFOR(pin)
-#define XFOFF(cab,func)
-#define XFON(cab,func)
-
-#include "myAutomation.h"
-
-// setup for pass 2... Create getMessageText function
-#undef ALIAS
-#undef ROUTE
-#undef AUTOMATION  
-#define ROUTE(id, description)
-#define AUTOMATION(id, description)  
-
-#undef EXRAIL 
-#undef PRINT
-#undef LCN
-#undef SERIAL
-#undef SERIAL1
-#undef SERIAL2
-#undef SERIAL3
-#undef ENDEXRAIL  
-#undef LCD
-const int StringMacroTracker1=__COUNTER__;
-#define ALIAS(name,value) 
-#define EXRAIL void  RMFT2::printMessage(uint16_t id) { switch(id) {
-#define ENDEXRAIL  default: DIAG(F("printMessage error %d %d"),id,StringMacroTracker1); return ; }}
-#define PRINT(msg)    case (__COUNTER__ - StringMacroTracker1) : printMessage2(F(msg));break;
-#define LCN(msg)      case (__COUNTER__ - StringMacroTracker1) : StringFormatter::send(&LCN_SERIAL,F(msg));break;
-#define SERIAL(msg)   case (__COUNTER__ - StringMacroTracker1) : StringFormatter::send(&Serial,F(msg));break;
-#define SERIAL1(msg)  case (__COUNTER__ - StringMacroTracker1) : StringFormatter::send(&Serial1,F(msg));break;
-#define SERIAL2(msg)  case (__COUNTER__ - StringMacroTracker1) : StringFormatter::send(&Serial2,F(msg));break;
-#define SERIAL3(msg)  case (__COUNTER__ - StringMacroTracker1) : StringFormatter::send(&Serial3,F(msg));break;
-#define LCD(id,msg)   case (__COUNTER__ - StringMacroTracker1) : StringFormatter::lcd(id,F(msg));break;
-#include "myAutomation.h"
-
-// Setup for Pass 3: create main routes table 
-#undef AFTER
-#undef AMBER
-#undef AT
-#undef AUTOMATION 
-#undef CALL
-#undef CLOSE
-#undef DELAY
-#undef DELAYMINS
-#undef DELAYRANDOM
-#undef DONE
-#undef ENDIF
-#undef ENDEXRAIL
-#undef ENDTASK
-#undef ESTOP
-#undef EXRAIL
-#undef FOFF
-#undef FOLLOW
-#undef FON
-#undef FREE
-#undef FWD
-#undef GREEN
-#undef IF
-#undef IFNOT
-#undef IFRANDOM
-#undef IFRESERVE
-#undef INVERT_DIRECTION
-#undef JOIN
-#undef LATCH
-#undef LCD
-#undef LCN
-#undef ONCLOSE
-#undef ONTHROW
-#undef PAUSE
-#undef POM
-#undef POWEROFF
-#undef PRINT
-#undef READ_LOCO
-#undef RED
-#undef RESERVE
-#undef RESET
-#undef RESUME
-#undef RETURN
-#undef REV
-#undef ROUTE 
-#undef START
-#undef SEQUENCE 
-#undef SERVO
-#undef SERVO2
-#undef FADE
-#undef SENDLOCO
-#undef SERIAL
-#undef SERIAL1
-#undef SERIAL2
-#undef SERIAL3
-#undef SETLOCO
-#undef SET
-#undef SPEED
-#undef STOP
-#undef SIGNAL
-#undef SERVO_TURNOUT
-#undef PIN_TURNOUT
-#undef THROW
-#undef TURNOUT
-#undef UNJOIN
-#undef UNLATCH
-#undef WAITFOR
-#undef XFOFF
-#undef XFON
-
-// Define macros for route code creation 
-#define V(val) ((int16_t)(val))&0x00FF,((int16_t)(val)>>8)&0x00FF
-#define NOP 0,0
-
-#define ALIAS(name,value) 
-#define EXRAIL const  FLASH  byte RMFT2::RouteCode[] = {
-#define AUTOMATION(id, description)  OPCODE_AUTOMATION, V(id), 
-#define ROUTE(id, description)  OPCODE_ROUTE, V(id), 
-#define SEQUENCE(id)  OPCODE_SEQUENCE, V(id), 
-#define ENDTASK OPCODE_ENDTASK,NOP,
-#define DONE OPCODE_ENDTASK,NOP,
-#define ENDEXRAIL OPCODE_ENDTASK,NOP,OPCODE_ENDEXRAIL,NOP };
- 
-#define AFTER(sensor_id) OPCODE_AT,V(sensor_id),OPCODE_AFTER,V(sensor_id),
-#define AMBER(signal_id) OPCODE_AMBER,V(signal_id),
-#define AT(sensor_id) OPCODE_AT,V(sensor_id),
-#define CALL(route) OPCODE_CALL,V(route),
-#define CLOSE(id)  OPCODE_CLOSE,V(id),
-#define DELAY(ms) OPCODE_DELAY,V(ms/100L),
-#define DELAYMINS(mindelay) OPCODE_DELAYMINS,V(mindelay),
-#define DELAYRANDOM(mindelay,maxdelay) OPCODE_DELAY,V(mindelay/100L),OPCODE_RANDWAIT,V((maxdelay-mindelay)/100L),
-#define ENDIF  OPCODE_ENDIF,NOP,
-#define ESTOP OPCODE_SPEED,V(1), 
-#define FADE(pin,value,ms) OPCODE_SERVO,V(pin),OPCODE_PAD,V(value),OPCODE_PAD,V(PCA9685::ProfileType::UseDuration|PCA9685::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 FREE(blockid) OPCODE_FREE,V(blockid),
-#define FWD(speed) OPCODE_FWD,V(speed),
-#define GREEN(signal_id) OPCODE_GREEN,V(signal_id),
-#define IF(sensor_id) OPCODE_IF,V(sensor_id),
-#define IFNOT(sensor_id) OPCODE_IFNOT,V(sensor_id),
-#define IFRANDOM(percent) OPCODE_IFRANDOM,V(percent),
-#define IFRESERVE(block) OPCODE_IFRESERVE,V(block),
-#define INVERT_DIRECTION OPCODE_INVERT_DIRECTION,NOP,
-#define JOIN OPCODE_JOIN,NOP,
-#define LATCH(sensor_id) OPCODE_LATCH,V(sensor_id),
-#define LCD(id,msg) PRINT(msg)
-#define LCN(msg) PRINT(msg)
-#define ONCLOSE(turnout_id) OPCODE_ONCLOSE,V(turnout_id),
-#define ONTHROW(turnout_id) OPCODE_ONTHROW,V(turnout_id),
-#define PAUSE OPCODE_PAUSE,NOP,
-#define POM(cv,value) OPCODE_POM,V(cv),OPCODE_PAD,V(value),
-#define POWEROFF OPCODE_POWEROFF,NOP,
-#define PRINT(msg) OPCODE_PRINT,V(__COUNTER__ - StringMacroTracker2),
-#define READ_LOCO OPCODE_READ_LOCO1,NOP,OPCODE_READ_LOCO2,NOP,
-#define RED(signal_id) OPCODE_RED,V(signal_id),
-#define RESERVE(blockid) OPCODE_RESERVE,V(blockid),
-#define RESET(pin) OPCODE_RESET,V(pin),
-#define RESUME OPCODE_RESUME,NOP,
-#define RETURN OPCODE_RETURN,NOP,
-#define REV(speed) OPCODE_REV,V(speed),
-#define SENDLOCO(cab,route) OPCODE_SENDLOCO,V(cab),OPCODE_PAD,V(route),
-#define SERIAL(msg) PRINT(msg)
-#define SERIAL1(msg) PRINT(msg)
-#define SERIAL2(msg) PRINT(msg)
-#define SERIAL3(msg) PRINT(msg)
-#define START(route) OPCODE_START,V(route),
-#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 SETLOCO(loco) OPCODE_SETLOCO,V(loco),
-#define SET(pin) OPCODE_SET,V(pin),
-#define SPEED(speed) OPCODE_SPEED,V(speed),
-#define STOP OPCODE_SPEED,V(0), 
-#define SIGNAL(redpin,amberpin,greenpin) OPCODE_SIGNAL,V(redpin),OPCODE_PAD,V(amberpin),OPCODE_PAD,V(greenpin), 
-#define SERVO_TURNOUT(id,pin,activeAngle,inactiveAngle,profile) OPCODE_SERVOTURNOUT,V(id),OPCODE_PAD,V(pin),OPCODE_PAD,V(activeAngle),OPCODE_PAD,V(inactiveAngle),OPCODE_PAD,V(PCA9685::ProfileType::profile),
-#define PIN_TURNOUT(id,pin) OPCODE_PINTURNOUT,V(id),OPCODE_PAD,V(pin), 
-#define THROW(id)  OPCODE_THROW,V(id),
-#define TURNOUT(id,addr,subaddr) OPCODE_TURNOUT,V(id),OPCODE_PAD,V(addr),OPCODE_PAD,V(subaddr),
-#define UNJOIN OPCODE_UNJOIN,NOP,
-#define UNLATCH(sensor_id) OPCODE_UNLATCH,V(sensor_id),
-#define WAITFOR(pin) OPCODE_WAITFOR,V(pin),
-#define XFOFF(cab,func) OPCODE_XFOFF,V(cab),OPCODE_PAD,V(func),
-#define XFON(cab,func) OPCODE_XFON,V(cab),OPCODE_PAD,V(func),
-
-// PASS2 Build RouteCode
-const int StringMacroTracker2=__COUNTER__;
-#include "myAutomation.h"
-
-// Restore normal code LCD & SERIAL  macro
-#undef LCD
-#define LCD   StringFormatter::lcd
-#undef SERIAL
-#define SERIAL  0x0
-#endif

Release - Architecture Doc/CommandStation-EX-Arch-v1-0.svg

@@ -485,10 +485,10 @@
 				<text x="32.86" y="598.05" class="st4" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>Accessories <v:newlineChar/><tspan
 							x="30.42" dy="1.2em" class="st5">(</tspan>Output.cpp)</text>			</g>
 		</a>
-		<a xlink:href="https://github.com/DCC-EX/CommandStation-EX/blob/master/LCDDisplay.cpp">
+		<a xlink:href="https://github.com/DCC-EX/CommandStation-EX/blob/master/Display.cpp">
 			<g id="shape14-81" v:mID="14" v:groupContext="shape" v:layerMember="0" transform="translate(288,-116.156)">
 				<title>Process.14</title>
-				<desc>Other Utilities (LCDDisplay.cpp)</desc>
+				<desc>Other Utilities (Display.cpp)</desc>
 				<v:custProps>
 					<v:cp v:nameU="Cost" v:lbl="Cost" v:prompt="" v:type="7" v:format="@" v:sortKey="" v:invis="false"
 							v:ask="false" v:langID="1033" v:cal="0"/>
@@ -522,7 +522,7 @@
 				</g>
 				<rect x="0" y="580.5" width="90" height="31.5" rx="13.5" ry="13.5" class="st3"/>
 				<text x="19.29" y="593.55" class="st4" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>Other Utilities<v:newlineChar/><tspan
-							x="14.29" dy="1.2em" class="st5">(</tspan>LCDDisplay.cpp)</text>			</g>
+							x="14.29" dy="1.2em" class="st5">(</tspan>Display.cpp)</text>			</g>
 		</a>
 		<g id="shape3-88" v:mID="3" v:groupContext="shape" v:layerMember="1" transform="translate(108,-443.812)">
 			<title>Dynamic connector</title>

Release_Notes/CommandRef.md

@@ -0,0 +1,197 @@
+This file is being used to consolidate the command reference information. 
+
+General points:
+  - Commands below have a single character opcode and parameters.
+  Even <JA> is actually read as <J A> 
+  - Keyword parameters are shown in upper case but may be entered in mixed case.
+  - value parameters are decimal numeric (unless otherwise noted)
+  - [something]  indicates its optional.
+  - Not all commands have a response, and broadcasts mean that not all responses come from the last commands that you have issued.
+   
+Startup status
+<s> Return status like
+    <iDCC-EX V-4.2.22 / MEGA / STANDARD_MOTOR_SHIELD G-devel-202302281422Z>
+    also returns defined turnout list:
+    <H id 1|0>   1=thrown
+
+Track power management. After power commands a power state is broadcast to all throttles.
+
+<1>                Power on all
+<1 MAIN|PROG|JOIN> Power on MAIN or PROG track
+<1 JOIN>           Power on MAIN and PROG track but send main track data on both.
+<0>                Power off all tracks 
+<0 MAIN|PROG>      Power off main or prog track
+
+Basic manual loco control
+<t locoid speed direction>  Throttle loco. 
+    speed in JMRI-form  (-1=ESTOP, 0=STOP, 1..126 = DCC speeds 2..127)
+    direction 1=forward, 0=reverse
+    For response see broadcast <l>
+
+<F locoid function 1|0>     Set loco function 1=ON, 0-OFF
+    For response see broadcast <l>
+
+<!>  emergency stop all locos
+<T id 0|1|T|C>  Control turnout id, 0=C=Closed, 1=T=Thrown
+       response broadcast <H id 0|1>
+
+
+DCC accessory control
+<a address subaddress activate [onoff]>
+<a linearaddress activate> 
+
+
+Turnout definition
+Note: Turnouts are best defined in myAutomation.h where a turnout description can also be provided ( refer to EXRAIL documentation) or by using these commands in a mySetup.h file. 
+
+<T id SERVO vpin thrown closed profile>
+<T id VPIN vpin>
+<T id DCC addr subaddr>
+<T id DCC linearaddr>
+   Valid commands respond with <O>
+
+Direct pin manipulation (replaces <Z commands, no predefinition required)
+<z vpin>     Set pin HIGH
+<z -vpin>    Set pin LOW
+<z vpin value> Set pin analog value
+<z vpin value profile> Set pin analog with profile
+<z vpin value profile duration> set pin analog with profile and value
+
+
+Sensors (Used by JMRI, not required by EXRAIL)
+<S id vpin pullup> define a sensor to be monitored.
+   Responses <Q id> and <q id> as sensor changes  
+
+Decoder programming - main track
+<w cab cv value> POM write value to cv on loco
+<b cab cv bit value> POM write bit to cv on loco
+
+Decoder Programming - prog track
+<W cabid>  Clear consist and write new cab id (includes long/short settings)
+           Responds <W cabid> or <W -1> for error
+<W cv value> Write value to cv
+
+<V cv predictedValue> Read cv value, much faster if prediction is correct. 
+<V cv bit predictedValue>      Read CV bit
+
+<R>         Read drive-away loco id. (May be a consist id)
+<D ACK ON|OFF>
+<D ACK LIMIT|MIN|MAX|RETRY value>
+<D PROGBOOST>
+
+Advanced DCC control
+<M  packet.... >
+<P  packet ...>
+<f map1 map2 [map3]>
+<#>
+<->
+<- cabid>
+<D CABS>
+<D SPEED28>
+<D SPEED128>
+
+
+EEPROM commands
+These commands exist for
+backwards JMRI compatibility. 
+You are strongly discouraged from maintaining your configuration settings in EEPROM.    
+<E>
+<e>
+<D EEPROM>
+<T>
+<T id>
+<S>
+<S id>
+<Z>
+<Z id>
+
+Diagnostic commands
+<D CMD ON|OFF>
+<D WIFI ON|OFF>
+<D ETHERNET ON|OFF>
+<D WIT ON|OFF>
+<D LCN ON|OFF>
+<D EXRAIL ON|OFF>
+<D RESET>
+<D SERVO|ANOUT vpin position [profile]>
+<D ANIN vpin>
+<D HAL SHOW>
+<D HAL RESET>
+<+ cmd>
+<+>
+<Q>
+
+User defined filter commands
+<U ....>
+<u ....>
+
+Track Management
+<=>
+<= track DCC|PROG|OFF>
+<= track DC|DCX cabid>
+<JG>
+<JI>
+
+
+Turntable interface
+<D TT vpin steps [activity]>
+
+Fast clock interface
+<JC>
+<JC mins rate>
+
+
+Advanced Throttle access to features
+<t cab>
+<JA>
+<JA id>
+<JR>
+<JR id>
+<JT>
+<JT id>
+
+*******************
+EXRAIL Commands
+*******************
+
+</>
+</PAUSE>
+</RESUME>
+</START cab sequence>
+</START sequence>
+</KILL taskid>
+</KILL ALL>
+</RESERVE|FREE blockid>
+</LATCH|UNLATCH latchid>
+</RED|AMBER|GREEN signalid>
+
+Obsolete commands/formats
+<c>
+<t ignored cab speed direction> 
+<T id vpin thrown closed>
+<T id addr subaddr>
+<B cv bit value obsolete obsolete>
+<R cv obsolete obsolete>
+<W cv value obsolete obsolete>
+<R cv>            V command is much faster if prediction is correct.
+<B cv bit value>  V command is much faster if prediction is correct.
+<Z id vpin active> (use <z)  Define an output pin that JMRI can set by id 
+<Z id activate>    (use <z)  Activate an output pin by id
+
+
+Broadcast responses
+Note: broadcasts are sent to all throttles when appropriate (usually because something has changed)
+
+<p0>
+<p1>
+<p1 MAIN|PROG|JOIN>
+
+<l cab slot dccspeed functionmap>
+<H id 1|0>
+<jC mmmm speed>
+
+Diagnostic responses
+These are not meant to be software readable. They contain diagnostic information for programmers to identify issues.
+<X> 
+<*  ... *>
+

Release_Notes/ThrottleAssists.md

@@ -0,0 +1,75 @@
+Throttle Assist updates for versiuon 4.?
+
+Chris Harlow April 2022
+
+There are a number of additional throttle information commands that have been implemented to assist throttle authors to obtain information from the Command Station in order to implement turnout, route/automation and roster features which are already found in the Withrottle implementations. 
+These commands are new and not overlapped with the existing commands which are probabaly due to be obsoleted as they are over complex and unfit for purpose. 
+
+Turnouts:
+
+The conventional turnout definition commands and the ```<H>``` responses do not contain information about the turnout description which may have been provided in an EXRAIL script. A turnout description is much more user friendly than T123 and having a list helps the throttle UI build a suitable set of buttons.
+
+```<JT>``` command returns a list of turnout ids. The throttle should be uninterested in the turnout technology used but needs to know the ids it can throw/close and monitor the current state. 
+e.g.  response ```<jT 1 17 22 19>``` 
+
+```<JT 17>`` requests info on turnout 17.
+e.g. response ```<jT 17 T "Coal yard exit">``` or ```<jT 17 C "Coal yard exit">```
+(T=thrown, C=closed)
+or ```<jT 17 C "">``` indicating turnout description not given. 
+or ```<jT 17 X>``` indicating turnout unknown (or possibly hidden.) 
+
+Note: It is still the throttles responsibility to monitor the status broadcasts.
+ (TBD I'm thinking that the existing broadcast is messy and needs cleaning up)
+ However, I'm not keen on dynamically created/deleted turnouts so I have no intention of providing a command that indicates the turnout list has been updated since the throttle started. 
+ Also note that turnouts marked in EXRAIL with the HIDDEN keyword instead of a "description" will NOT show up in these commands. 
+
+
+ Automations/Routes
+
+ A throttle need to know which EXRAIL Automations and Routes it can show the user.
+
+ ```<JA>``` Returns a list of Automations/Routes
+ e.g. ```<jA 13 16 23>```
+ Indicates route/automation ids.
+ Information on each route needs to be obtained by 
+ ```<JA 13>``` 
+ returns e.g. ```<jA 13 R "description">``` for a route
+ or  ```<jA 13 A "description">``` for an automation. 
+ or ```<jA 13 X>``` for id not found
+
+ Whats the difference: 
+   A Route is just a call to an EXRAIL ROUTE, traditionally to set some turnouts or signals but can be used to perform any kind of EXRAIL function... but its not expecting to know the loco.  
+   Thus a route can be triggered by sending in for example ```</START 13>```. 
+ 
+   An Automation is a handoff of the last accessed loco id to an EXRAIL AUTOMATION which would typically drive the loco away.
+   Thus an Automation expects a start command with a cab id
+   e.g. ```</START 13 3>```
+
+
+   Roster Information:
+   The ```<JR>``` command requests a list of cab ids from the roster.
+   e.g. responding ```<jR 3 200 6336>```
+   or <jR> for none. 
+
+   Each Roster entry had a name and function map obtained by:
+   ```<JR 200>```  reply like ```<jR 200 "Thomas" "whistle/*bell/squeal/panic">
+   
+   Refer to EXRAIL ROSTER command for function map format.
+
+
+  Obtaining throttle status.
+  ```<t cabid>```  Requests a deliberate update on the cab speed/functions in the same format as the cab broadcast.
+     ```<l cabid slot speedbyte functionMap>```
+      Note that a slot of -1 indicates that the cab is not in the reminders table and this comand will not reserve a slot until such time as the cab is throttled.
+
+
+  COMMANDS TO AVOID
+
+  ```<f cab func1 func2>```     Use ```<F cab function 1/0>```
+  ```<t  slot cab speed dir>``` Just drop the slot number 
+  ```<T commands>``` other than ```<T id 0/1>```
+  ```<s>```
+  ```<c>```
+
+
+

Release_Notes/TrackManager.md

@@ -0,0 +1,139 @@
+# DCC++EX Track Manager
+
+Chris Harlow 2022/03/23
+
+**If you are only interested in a standard setup using just a DCC track and PROG track, then you DO NOT need to read the rest of this document.**
+
+What follows is for advanced users interested in managing power districts and/or running DC locomotives through DCC++EX.
+
+## What is the Track Manager
+Track Manger (TM from now on) is an integral part of DCC++EX software that is responsible for:
+- Managing track power state.
+- Monitoring track overloads and shorts.
+- Routing the DCC main or prog track waveforms to the correct Motor Driver and thus track.
+- Managing the JOIN feature.
+- Intercepting throttle commands to locos running on DC tracks.
+- Handling user or EXRAIL commands to switch track status.
+
+In the default scenario of a single DCC track and a PROG track, the TM behaves as for the previous versions of DCC++EX so if thats what you want, you dont need to mess with it.
+
+The TM is able to handle up to 8 separate track domains. Each domain requires a hardware driver to supply track voltage. A typical motor driver shield supplies two tracks, which is what we have used in the past as main and prog.
+
+Unlike the previous version of DCC++EX, where the shield channel A was always the DCC main and channel B was always the DCC prog track, TM allows :
+- None, any or all the tracks can be DCC Main.
+- None or ONE track may be DCC prog at any given time.
+- Any track may be powered on or off independently of the others.
+- Any track may be disconnected from the DCC signal and used as a DC track with a given loco address. (See DC discussion later)
+
+With such flexibility comes responsibility... the potential for making mistakes means taking extra care with your configuration!
+
+**NOTE** TM does NOT use "zero stretching" to control your DC motor. Instead, it uses true Pulse Width Modulation (PWM) to efficiently run your loco using the same method a decoder uses to control a DCC loco's motor. DC locos can even run better on TM than they can on a normal analog throttle, especially at low speed, since it is always applying the full track voltage, albeit in pulses of varying duration. 
+
+## Using the Track Manager (DCC)
+TM names the tracks A to H. In a default setup, you will normally have tracks A and B where A will default to be the DCC main signal and B will be the DCC prog.
+
+There is a new user command `<=>` which is used to control the TM but the `<0>` and `<1>` commands operate as before.
+
+- `<=>`  lists the current track settings.
+In a default setup this will normally return 
+```
+        <=A DCC>
+        <=B PROG>
+```
+- `<=t DCC>`  sets track t (A..H) to use the DCC main track.   For example `<=C DCC>` sets track C. All tracks that are set to DCC will receive the same DCC signal waveform.
+- `<=t PROG>` Sets track t (A..H) to be the one and only PROG track. Any previous PROG track is turned off.
+- `<=t OFF>` turns off the track t. It will not power on with `<1>` because it will not know what signal to send. 
+
+In an all-DCC environment it is unlikely that you will need to do anything other than setting any additional tracks (C...H) as DCC in your `mySetup.h` file.
+
+Bear in mind that a track may actually be only connected to DCC accessories such as signals and turnouts... your layout, your choice. 
+
+Note that when setting a track to PROG or OFF, its power is switched off automatically. (The PROG track manages power on an as-needed basis under normal circumstances.
+When setting a track to MAIN (or DC, DCX see later) the power is applied according to the most recent `<1>` or `<0>` command as being the most compatible with previous versions.
+
+## using the Track Manager (DC)
+
+TM allows any or all of your tracks to be individually selected as a DC track which responds to throttle commands on any given loco address. So for example if track A is set to DC address 55, then any throttle commands to loco 55 will be transmitted as DC onto track A and thus a DC loco can be driven along that track. almost exactly as if it was DCC.
+Your throttle (JMRI, EX-Webthrottle, Withrottle, Engine Driver etc etc) do not know or care that this is a DC loco so nothing needs to change.
+
+For a simple Command Station setup to run just two DC tracks instead of DCC, you only need to assign DC addresses to tracks A and B. If you want DCC on track A and DC on track B, you just need to set track B to a suitable DC address.
+
+The command to set a track to a DC address is as follows 
+- `<=t DC a>` Sets track t (A..H) to use loco address a. e.g. <=A DC 3>
+
+A simple 2 separate loop DC track, wired the traditional way in opposite directions, may be set like this to use loco addresses 1 and 2.  
+```
+<=A DC 1>
+<=A DC 2>
+```
+
+### Crossing between DC tracks 
+
+There are some slightly mind-bending issues to be addressed, especially if you want to be able to cross between two separate DC tracks or use your layout in DCC or DC mode. This is because the control of DC loco direction is relative to the TRACK and not the LOCO. (you turn a DC loco round on the track and it continues in the same geographical direction. You turn a DCC loco around and it continues to go forwards or backwards in the opposite geographical direction.)
+
+Generally DC tracks are wired so that two mainline tracks are in opposite direction which makes operation easy BUT crossovers between tracks will cause shorts unless you have very complex switching arrangements.
+This is generally incompatible with DCC wiring which expects to be able to cross between tracks with impunity because they are all wired with the same polarity. 
+
+To get over this issue TM allows the polarity of a DC track to be swapped so that tracks wired for DCC may be switched to DC with a polarity chosen at run time according to your operations. So, for example, you may have two loops with a crossing between them. Normally you need them in opposite directions, but when you need to drive over the crossing, you need to switch one or other track so that they are at the same polarity.
+(This is a good case for using EXRAIL to help)
+
+The command `<=t DCX a>` will set track t (A..H) to be DC but with reversed polarity compared with a track set to DC.
+
+Its perfectly OK to cross between DC tracks by setting them to the same loco address and making sure you get the polarity right!
+
+## Connecting Hardware
+Each track requires hardware to control it
+- Power on/off
+- Polarity (direction, signal etc)
+- Brake (shorts tracks together)
+- Current (analog reading)
+
+The standard motor shields provide this for two separate tracks and are predictable and easy to use. However STACKING shields is not a viable way of adding more tracks because it prevents the software from gaining access to the individual track pins. Similarly, wiring all the signal pins together for example, will give you a shared DCC signal but it will eliminate any possibility of switching the track purpose at run time. So, you are going to have to understand enough to wire track drivers to various pins if you wish to extend beyond 2 tracks and take advantage of TM.
+
+You will also need to consider the implications of differing electronic implementations that would cause unexpected issues when a loco moves between tracks. We know this works fine for a typical shield because we use `<1 JOIN>` quite happily but this may be different if you mix hardware types..... (NOT MY PROBLEM !) 
+
+The easiest way to consider the wiring is to treat each track individually (either as a separate driver or as half of a shield).
+
+You will require,for each track, on the Arduino:
+- A GPIO pin (or a HAL vpin perhaps on an I2C extender, code TBA!!!) to switch power.
+- A GPIO pin to switch the signal direction
+- A GPIO pin with PWM capability to switch the Brake (you may omit this if you dont want any DC capability)
+- Optionally An Analog pin to read the current (unless your hardware cant do that, perhaps its just feeding a booster)
+- Optionally a GPIO fault pin if thats how your hardware works. (NOT recommended as you're going to run out of pins)
+
+IF you have no more than 3 tracks and you can arrange for the signal pins to be one of 11,12,13 on a Mega, THEN there is a slight advantage internally and the waveform will be super-sharp.
+
+**Hardware that has two signal pins still needs some code thought!!!!!!!!**
+
+
+## Configuring the Software
+
+Configuring the software to provide more tracks is a simple extension of the existing method of customising the #define of MOTOR_SHIELD_TYPE in config.h
+Since there can be no standard setup of your wiring and hardware choices, it will be necessary to create your custom built MOTOR_SHIELD_TYPE in the manner described in MotorDrivers.h and simply continue to add more `new MotorDriver(` definitions to the list, providing all the pin numbers and electronic limits for each track. (or even shorten the list to 1)
+
+## Using EXRAIL to control Track Manager
+EXRAIL has a single additional command that can be used to automate TM.
+
+- `SET_TRACK(t,mode)`
+where t is the track letter A..H and mode is one of
+- `OFF`  track is switched off
+- `DCC`  track gets DCC signal
+- `PROG` track gets DCC prog signal
+- `DC`   track is set to DC mode with the cab address of the currently executing EXRAIL sequence. 
+- `DCX` as DC but with reversed polarity.
+
+DC/DCX are designed so that you can be automating a DCC loco, drive it onto a separate track and switch to DC without having to know the cab address. (e.g AUTOMATION) 
+If however you are just running a ROUTE you can always do something like this:
+```
+ ROUTE(77,"Set track G to DC 123")
+   SETLOCO(123)
+   SET_TRACK(G,DC)
+   DONE
+```
+
+## Where and How for the Code.
+The TM code is primarily in TrackManager.cpp which is responsible for coordinating the track settings and commands. 
+
+Each individual track is handled by an instance of MotorDriver created from the MOTOPR_SHIELD_TYPE definition in config.h 
+
+Many functions formerly in the DCCWaveform code have been moved to TrackManager or MotorDriver, notably the power control and checking. This makes the code easier to follow.

Release_Notes/duinoNodes.md

@@ -0,0 +1,39 @@
+Using Lew's Duino Gear boards:
+
+1. DNIN8 Input
+   This is a shift-register implementation of a digital input collector. 
+   Multiple DNIN8 may be connected in sequence but it is IMPORTANT that the software 
+   configuratuion correctly represents the number of boards connected otherwise the results will be meaningless. 
+
+   Use in myAnimation.h
+
+   HAL(IO_DNIN8, firstVpin, numPins, clockPin, latchPin, dataPin)
+   e.g. 
+   HAL(IO_DNIN8, 400, 16, 40, 42, 44)
+
+   OR Use in myHal.cpp
+     IO_DNIN8::create( firstVpin, numPins, clockPin, latchPin, dataPin)
+
+
+
+   This will create virtaul pins 400-415 using two DNIN8 boards connected in sequence. 
+   Vpins 400-407 will be on the first board (closest to the CS) and 408-415 on the second.
+
+   Note: 16 pins uses two boards. You may specify a non-multiple-of-8 pins but this will be rounded up to a multiple of 8 and you must connect ONLY the number of boards that this takes. 
+      
+   This example uses Arduino GPIO pins 40,42,44 as these are conveniently side-by-side on a Mega which is easier when you are using a 3 strand cable. 
+ 
+ The DNIN8K module works the same but you must use DNIN8K in the HAL setup instead of DNIN8. NO you cant mix 8 and 8k versions in the same string of boards but you can create another string of boards. 
+
+
+ DNOU8 works the same way, 
+   Use in myAnimation.h
+
+   HAL(IO_DNOU8, firstVpin, numPins, clockPin, latchPin, dataPin)
+   e.g. 
+   HAL(IO_DNIN8, 450, 16, 45, 47, 49)
+
+   OR Use in myHal.cpp
+     IO_DNIN8::create( firstVpin, numPins, clockPin, latchPin, dataPin)
+
+This creates a string of input pins 450-465. Note the clock/latch/data pins must be different to any DNIN8/k pins.      

Release_Notes/release_notes_v4.0.0.md

@@ -0,0 +1,284 @@
+Version 4.0 Release Notes
+*************************
+
+The DCC-EX Team is pleased to release CommandStation-EX-v4.0.0 as a Production Release.  Release v4.0.0 is a Major release that adds significant new product design, plus Automation features and bug fixes. The team continues improving the architecture of DCC++EX to make it more flexible and optimizing the code so as to get more performance from the Arduino (and other) microprocessors.  This release includes all of the Point Releases from v3.2.0 to v3.2.0 rc13.
+
+**Downloads (zip and tar.gz) below. These are named without version number in the folder name to make the Arduino IDE happy.**
+
+[CommandStation-EX.zip](https://github.com/DCC-EX/CommandStation-EX/releases/download/v4.0.0-Prod/CommandStation-EX.zip)
+
+
+[CommandStation-EX.tar.gz](https://github.com/DCC-EX/CommandStation-EX/releases/download/v0.0.0-Prod/CommandStation-EX.tar.gz)
+
+**Known Issues**
+
+- **Wi-Fi** - Requires sending `<AT>` commands from a serial monitor if you want to switch between AP mode and STA station mode after initial setup
+- **Pololu Motor Shield** - is supported with this release, but the user may have to adjust timings to enable programming mode due to limitations in its current sensing circuitry
+
+**All New Major DCC++EX 4.0.0 features**
+
+- **New HAL Hardware Abstraction Layer API** that automatically detects and greatly simplifies interfacing to many predefined accessory boards for servos, signals & sensors and added I/O (digital and analog inputs and outputs, servos etc). 
+- HAL Support for;
+  - MCP23008, MCP23017 and PCF9584 I2C GPIO Extender modules. 
+  - PCA9685 PWM (servo & signal) control modules. 
+  - Analogue inputs on Arduino pins and on ADS111x I2C modules. 
+  - MP3 sound playback via DFPlayer module. 
+  - HC-SR04 Ultrasonic range sensor module. 
+  - VL53L0X Laser range sensor module (Time-Of-Flight). 
+  - A new `<D HAL SHOW>` command to list the HAL devices attached to the command station
+ 
+**New Command Station Broadcast throttle logic**
+
+- Synchronizes multiple WiThrottles and PC based JMRI Throttles for direction, speed and F-key updates
+
+**New ‘Discovered Servers’ on WiFi Throttles**
+
+- Our New multicast Dynamic Network Server (mDNS) enhancement allows us to display the available WiFi server connections to a DCC++EX Command Station. Selecting it allows your WiThrottle App to connect to and load Server Rosters and function keys to your throttle from the new DCC++EX Command Station Server Roster.
+
+**New DCC++EX 4.0.0 with EX-RAIL Extended Railroad Automation Instruction Language**
+
+- Use to control your entire layout or as a separate accessory/animation controller
+- Awesome, cleverly powerful yet simple user friendly scripting language for user built Automation & Routing scripts. 
+- You can control Engines, Sensors, Turnouts, Signals, Outputs and Accessories that are entered into your new myAutomation.h file, then uploaded into the DCC++EX Command Station.
+- EX-RAIL scripts are automatically displayed as Automation {Handoff} and Route {Set} buttons on supported WiFi Throttle Apps.
+
+**New EX-RAIL ‘Roster’ Feature**
+
+- List and store user defined engine roster & function keys inside the command station, and automatically load them in WiFi Throttle Apps.
+- When choosing “DCC++EX” from discovered servers an Engine Driver or WiThrottle is directly connected to the Command Station. 
+- The EX-RAIL ’ROSTER’ command allows all the engine numbers, names and function keys you’ve listed in your myAutomation.h file to automatically upload the Command Station's ‘Server Roster’ into your Engine Driver and WiThrottle Apps.  
+
+**New JMRI 4.99.2 and above specific DCC++EX 4.0 features**
+
+- Enhanced JMRI DCC++ Configure Base Station pane for building and maintaining Sensor, Turnout and Output devices, or these can automatically be populated from the DCC++EX Command Station's mySetup.h file into JMRI.
+
+- JMRI now supports multiple serial connected DCC++EX Command Stations, to display and track separate "Send DCC++ Command" and "DCC++ Traffic" Monitors for each Command Station at the same time.
+  For example: Use an Uno DCC++EX DecoderPro Programming Station {DCC++Prg} on a desktop programming track and a second Mega DCC++EX EX-RAIL Command Station for Operations {DCC++Ops} on the layout with an additional `<JOINED>` programming spur or siding track for acquiring an engine and ‘Drive Away’ onto the mainline (see the DriveAway feature for more information).
+
+**DCC++EX 4.0.0 additional product enhancements**
+
+- Additional Motor Shields and Motor Board {boosters) supported
+- Additional Accessory boards supported for GPIO expansion, Sensors, Servos & Signals
+- Additional diagnostic commands like ‘D ACK RETRY’ and ‘D EXRAIL ON’ events, ‘D HAL SHOW’ devices and ‘D SERVO’ positions, and ‘D RESET’ the command station while maintaining the serial connection with JMRI
+- Automatic retry on failed ACK detection to give decoders another chance
+- New EX-RAIL ’/’ slash command allows JMRI to directly communicate with many EX-RAIL scripts
+- Turnout class revised to expand turnout capabilities and allow turnout names/descriptors to display in WiThrottle Apps.
+- Build turnouts through either or both mySetup.h and myAutomation.h files, and have them automatically passed to, and populate, JMRI Turnout Tables
+- Turnout user names display in Engine Driver & WiThrottles
+- Output class now allows ID > 255. 
+- Configuration options to globally flip polarity of DCC Accessory states when driven from `<a>` command and `<T>` command.
+- Increased use of display for showing loco decoder programming information. 
+- Can disable EEPROM memory code to allow room for DCC++EX 4.0 to fit on a Uno Command Station
+- Can define border between long and short addresses 
+- Native non-blocking I2C drivers for AVR and Nano architectures (fallback to blocking Wire library for other platforms). 
+- EEPROM layout change - deletes EEPROM contents on first start following upgrade. 
+
+**4.0.0 Bug Fixes**
+
+- Compiles on Nano Every
+- Diagnostic display of ack pulses >32ms
+- Current read from wrong ADC during interrupt
+- AT(+) Command Pass Through 
+- CiDAP WiFi Drop out and the WiThrottle F-key looping error corrected
+- One-off error in CIPSEND drop
+- Common Fault Pin Error
+- Uno Memory Utilization optimized
+
+#### Summary of Release 3.1.0 key features and/or bug fixes by Point Release
+
+**Summary of the key new features added to CommandStation-EX V3.0.16**
+
+- Ignore CV1 bit 7 read if rejected by a non NMRA compliant decoder when identifying loco id
+
+**Summary of the key new features added to CommandStation-EX V3.0.15**
+
+- Send function commands just once instead of repeating them 4 times
+
+**Summary of the key new features added to CommandStation-EX V3.0.14**
+
+- Add feature to tolerate decoders that incorrectly have gaps in their ACK pulse
+- Provide proper track power management when joining and unjoining tracks with <1 JOIN>
+
+**Summary of the key new features added to CommandStation-EX V3.0.13**
+
+- Fix for CAB Functions greater than 127
+
+**Summary of the key new features added to CommandStation-EX V3.0.12**
+
+- Fixed clear screen issue for nanoEvery and nanoWifi
+
+**Summary of the key new features added to CommandStation-EX V3.0.11**
+
+- Reorganized files for support of 128 speed steps
+
+**Summary of the key new features added to CommandStation-EX V3.0.10**
+
+- Added Support for the Teensy 3.2, 3.5, 3.6, 4.0 and 4.1 MCUs
+- No functional change just changes to avoid complier warnings for Teensy/nanoEvery
+
+**Summary of the key new features added to CommandStation-EX V3.0.9**
+
+- Rearranges serial newlines for the benefit of JMRI
+- Major update for efficiencies in displays (LCD, OLED)
+- Add I2C Support functions
+
+**Summary of the key new features added to CommandStation-EX V3.0.8**
+
+- Wraps <* *> around DIAGS for the benefit of JMRI
+
+**Summary of the key new features added to CommandStation-EX V3.0.7**
+
+- Implemented support for older 28 apeed step decoders - Option to turn on 28 step speed decoders in addition to 128. If set, all locos will use 28 steps.
+- Improved overload messages with raw values (relative to offset)
+
+**Summary of the key new features added to CommandStation-EX V3.0.6**
+
+- Prevent compiler warning about deprecated B constants
+- Fix Bug that did not let us transmit 5 byte sized packets - 5 Byte commands like PoM (programming on main) were not being sent correctly
+- Support for Huge function numbers (DCC BinaryStateControl) - Support Functions beyond F28
+- <!> ESTOP all - New command to emergency stop all locos on the main track
+- <- [cab]> estop and forget cab/all cabs - Stop and remove loco from the CS. Stops the repeating throttle messages
+- `<D RESET>` command to reboot Arduino
+- Automatic sensor offset detect
+- Improved startup msgs from Motor Drivers (accuracy and auto sense factors)
+- Drop post-write verify - No need to double check CV writes. Writes are now even faster.
+- Allow current sense pin set to UNUSED_PIN - No need to ground an unused analog current pin. Produce startup warning and callback -2 for prog track cmds.
+
+**Summary of the key new features added to CommandStation-EX V3.0.5**
+
+- Fix Fn Key startup with loco ID and fix state change for F16-28
+- Removed ethernet mac config and made it automatic
+- Show wifi ip and port on lcd
+- Auto load config.example.h with warning
+- Dropped example .ino files
+- Corrected .ino comments
+- Add Pololu fault pin handling
+- Waveform speed/simplicity improvements
+- Improved pin speed in waveform
+- Portability to nanoEvery and UnoWifiRev2 CPUs
+- Analog read speed improvements
+- Drop need for DIO2 library
+- Improved current check code
+- Linear command
+- Removed need for ArduinoTimers files
+- Removed option to choose different timer
+- Added EX-RAIL hooks for automation in future version
+- Fixed Turnout list
+- Allow command keywords in mixed case
+- Dropped unused memstream
+- PWM pin accuracy if requirements met
+
+**Summary of the key new features added to CommandStation-EX V3.0.4**
+
+- "Drive-Away" Feature - added so that throttles like Engine Driver can allow a loco to be programmed on a usable, electrically isolated programming track and then drive off onto the main track
+- WiFi Startup Fixes
+
+**Summary of the key new features added to CommandStation-EX V3.0.3**
+
+- Command to write loco address and clear consist
+- Command will allow for consist address
+- Startup commands implemented
+
+**Summary of the key new features added to CommandStation-EX V3.0.2:**
+
+- Create new output for current in mA for `<c>` command - New current response outputs current in mA, overlimit current, and maximum board capable current
+- Simultaneously update JMRI to handle new current meter
+
+**Summary of the key new features added to CommandStation-EX V3.0.1:**
+
+- Add back fix for jitter
+- Add Turnouts, Outputs and Sensors to `<s>` command output
+
+**CommandStation-EX V3.0.0:**
+
+**Release v3.0.0 was a major rewrite if earlier versions of DCC++.  The code base was re-architeced and core changes were made to the Waveform generator to reduce overhead and make better use of Arduino.** **Summary of the key new features added in Release v3.0.0 include:**
+
+- **New USB Browser Based Throttle** - WebThrottle-EX is a full front-end to controller to control the CS to run trains.
+- **WiFi Support** - AP and station modes supported. Auto-detection of an ESP8266 WiFi module with AT firmware on a Mega's serial port. Connection to JMRI and WiThrottle clients.
+- **Withrottle Integrations** - Act as a host for up to four WiThrottle clients concurrently.
+- **Add LCD/OLED support** - OLED supported on Mega only
+- **Improved CV programming routines** - checks for length of CV pulse, and breaks out of the wait state once it has received an ACK, now reading one CV per second.
+- **Improved current sensing** - rewrote current sensing routines for safer operation. Current thresholds based on milliamps, not magic numbers
+- **Individual track power control** - Ability to toggle power on either or both tracks, and to "JOIN" the tracks and make them output the same waveform for multiple power districts.
+- **Single or Dual-Pin PWM output** - Allows control of H-bridges with PH/EN or dual PWM inputs
+- **New, simpler function command** - `<F>` command allows setting functions based on their number, not based on a code as in `<f>`
+- **Function reminders** - Function reminders are sent in addition to speed reminders
+- **Functions to F28** - All NMRA functions are now supported
+- **Filters and user functions** - Ability to filter commands in the parser and execute custom code based on them. (ex: Redirect Turnout commands via NRF24)
+- **Diagnostic `<D>` commands** - See documentation for a full list of new diagnostic commands
+- **Rewrote DCC++ Parser** - more efficient operation, accepts multi-char input and uses less RAM
+- **Rewritten waveform generator** - capable of using any pin for DCC waveform out, eliminating the need for jumpers
+- **Rewritten packet generator** - Simplify and make smaller, remove idea of "registers" from original code
+- **Add free RAM messages** - Free RAM messages are now printed whenever there is a decerase in available RAM
+- **Fix EEPROM bugs**
+- **Number of locos discovery command** - `<#>` command
+- **Support for more locomotives** - 20 locomotives on an UNO and 50 an a Mega.
+- **Automatic slot management** - slot variable in throttle/function commands are ignored and slot management is taken care of automatically. `<->` and `<- CAB>` commands added to release locos from memory and stop packets to the track.
+
+**Key Contributors**
+
+**Project Lead**
+
+- Fred Decker - Holly Springs, North Carolina, USA (FlightRisk)
+
+**CommandStation-EX Developers**
+
+- Chris Harlow - Bournemouth, UK (UKBloke)
+- Harald Barth - Stockholm, Sweden (Haba)
+- Neil McKechnie - Worcestershire, UK (NeilMck)
+- Fred Decker - Holly Springs, North Carolina, USA (FlightRisk)
+- Dave Cutting - Logan, Utah, USA (Dave Cutting/ David Cutting)
+- M Steve Todd - Oregon, USA (MSteveTodd) 
+- Scott Catalano - Pennsylvania
+- Gregor Baues - Île-de-France, France (grbba)
+
+**Engine Driver and JMRI Interface**
+
+- M Steve Todd
+
+**exInstaller Software**
+
+- Anthony W - Dayton, Ohio, USA (Dex, Dex++)
+
+**Website and Documentation**
+
+- Mani Kumar - Bangalor, India (Mani / Mani Kumar)
+- Fred Decker - Holly Springs, North Carolina, USA (FlightRisk)
+- Dave Cutting - Logan, Utah, USA (Dave Cutting/ David Cutting)
+- Roger Beschizza - Dorset, UK (Roger Beschizza)
+- Keith Ledbetter - Chicago, Illinois, USA (Keith Ledbetter)
+- Kevin Smith - Rochester Hills, Michigan USA (KC Smith)
+- Colin Grabham - Central NSW, Australia (Kebbin)
+
+**WebThrotle-EX**
+
+- Fred Decker - Holly Springs, NC (FlightRisk/FrightRisk)
+- Mani Kumar - Bangalor, India (Mani /Mani Kumar)
+- Matt H - Somewhere in Europe
+
+**Beta Testing / Release Management / Support**
+
+- Larry Dribin - Release Management
+- Kevin Smith - Rochester Hills, Michigan USA (KC Smith)
+- Herb Morton - Kingwood Texas, USA (Ash++)
+- Keith Ledbetter
+- Brad Van der Elst
+- Andrew Pye
+- Mike Bowers
+- Randy McKenzie
+- Roberto Bravin
+- Sam Brigden
+- Alan Lautenslager
+- Martin Bafver
+- Mário André Silva
+- Anthony Kochevar
+- Gajanatha Kobbekaduwe
+- Sumner Patterson
+- Paul - Virginia, USA
+
+**Downloads (zip and tar.gz) below. These are named without version number in the folder name to make the Arduino IDE happy.**
+
+[CommandStation-EX.zip](https://github.com/DCC-EX/CommandStation-EX/releases/download/v4.0.0-Prod/CommandStation-EX.zip)
+
+
+[CommandStation-EX.tar.gz](https://github.com/DCC-EX/CommandStation-EX/releases/download/v4.0.0-Prod/CommandStation-EX.tar.gz)