Repository: DCC-EX/CommandStation-EX Branch: master Commit: 288ae34fdecc Files: 226 Total size: 1.7 MB Directory structure: gitextract_3uy1hr_0/ ├── .gitattributes ├── .github/ │ ├── FUNDING.yml │ └── workflows/ │ ├── docs.yml │ ├── label-sponsors.yml │ ├── main.yml │ └── sha.yml ├── .gitignore ├── .travis.yml ├── CONTRIBUTING.md ├── CamParser.cpp ├── CamParser.h ├── CommandDistributor.cpp ├── CommandDistributor.h ├── CommandStation-EX.ino ├── DCC.cpp ├── DCC.h ├── DCCACK.cpp ├── DCCACK.h ├── DCCConsist.cpp ├── DCCConsist.h ├── DCCDecoder.cpp ├── DCCDecoder.h ├── DCCEX.h ├── DCCEXParser.cpp ├── DCCEXParser.h ├── DCCPacket.h ├── DCCQueue.cpp ├── DCCQueue.h ├── DCCRMT.cpp ├── DCCRMT.h ├── DCCTimer.h ├── DCCTimerAVR.cpp ├── DCCTimerESP.cpp ├── DCCTimerMEGAAVR.cpp ├── DCCTimerSAMD.cpp ├── DCCTimerSTM32.cpp ├── DCCTimerTEENSY.cpp ├── DCCWaveform.cpp ├── DCCWaveform.h ├── DCCWaveformRMT.cpp ├── DIAG.h ├── Display.cpp ├── Display.h ├── DisplayInterface.cpp ├── DisplayInterface.h ├── Display_Implementation.h ├── EEStore.cpp ├── EEStore.h ├── EXRAIL.h ├── EXRAIL2.cpp ├── EXRAIL2.h ├── EXRAIL2MacroBase.h ├── EXRAIL2MacroReset.h ├── EXRAIL2Parser.cpp ├── EXRAILAsserts.h ├── EXRAILMacros.h ├── EXRAILSensor.cpp ├── EXRAILSensor.h ├── EXRAILTest.h ├── EXmDNS.cpp ├── EXmDNS.h ├── EthernetInterface.cpp ├── EthernetInterface.h ├── FSH.h ├── GITHUB_SHA.h ├── I2CManager.cpp ├── I2CManager.h ├── I2CManager_AVR.h ├── I2CManager_Mega4809.h ├── I2CManager_NonBlocking.h ├── I2CManager_SAMD.h ├── I2CManager_STM32.h ├── I2CManager_Wire.h ├── IODevice.cpp ├── IODevice.h ├── IODeviceList.h ├── IO_AnalogueInputs.h ├── IO_Bitmap.h ├── IO_DCCAccessory.cpp ├── IO_DFPlayer.h ├── IO_DFPlayerBase.h ├── IO_DFPlayerI2C.h ├── IO_DFPlayerSerial.h ├── IO_DS1307.cpp ├── IO_DS1307.h ├── IO_EXFastclock.h ├── IO_EXIOExpander.h ├── IO_EXSensorCAM.h ├── IO_EXTurntable.cpp ├── IO_EncoderThrottle.cpp ├── IO_EncoderThrottle.h ├── IO_ExampleSerial.h ├── IO_GPIOBase.h ├── IO_HALDisplay.h ├── IO_HCSR04.h ├── IO_I2CDFPlayer-OBSOLETE.h ├── IO_I2CRailcom.cpp ├── IO_I2CRailcom.h ├── IO_MCP23008.h ├── IO_MCP23017.h ├── IO_NeoPixel.h ├── IO_PCA9554.h ├── IO_PCA9555.h ├── IO_PCA9685.cpp ├── IO_PCA9685pwm.h ├── IO_PCF8574.h ├── IO_PCF8575.h ├── IO_RotaryEncoder.h ├── IO_Servo.cpp ├── IO_Servo.h ├── IO_TCA8418.h ├── IO_TM1638.cpp ├── IO_TM1638.h ├── IO_TouchKeypad.h ├── IO_VL53L0X.h ├── IO_XL9535.h ├── IO_duinoNodes.h ├── IO_trainbrains.h ├── KeywordHasher.h ├── LCN.cpp ├── LCN.h ├── LICENSE ├── LiquidCrystal_I2C.cpp ├── LiquidCrystal_I2C.h ├── LocoSlot.cpp ├── LocoSlot.h ├── MotorDriver.cpp ├── MotorDriver.h ├── MotorDrivers.h ├── Outputs.cpp ├── Outputs.h ├── README.md ├── Railcom.cpp ├── Railcom.h ├── Release - Architecture Doc/ │ ├── CommandStation-EX-Arch-v1-0.vsd │ ├── Prod-Release-Notes.md │ └── Rough Release-Notes.md ├── Release_Notes/ │ ├── CommandRef.md │ ├── DCC-EX v5.4 Release Notes.xlsx │ ├── Exrail mods.txt │ ├── IO_Bitmap.md │ ├── NeoPixel.md │ ├── Railcom.md │ ├── Stash.md │ ├── TCA8418.md │ ├── TM1638.md │ ├── ThrottleAssists.md │ ├── TrackManager.md │ ├── consists.md │ ├── duinoNodes.md │ ├── momentum.md │ ├── release_notes_v3.0.0.md │ ├── release_notes_v3.1.0.md │ ├── release_notes_v4.0.0.md │ └── websocketTester.html ├── RingStream.cpp ├── RingStream.h ├── SSD1306Ascii.cpp ├── SSD1306Ascii.h ├── STM32lwipopts.h.copyme ├── SensorGroup.cpp ├── SensorGroup.h ├── Sensors.cpp ├── Sensors.h ├── SerialManager.cpp ├── SerialManager.h ├── SerialUsbLog.cpp ├── SerialUsbLog.h ├── SerialUsbLog.html.h ├── SerialUsbLog.script1.js.h ├── SerialUsbLog.script2.js.h ├── SerialUsbLog.style.css.h ├── Sniffer.cpp ├── Sniffer.h ├── Stash.cpp ├── Stash.h ├── StringBuffer.cpp ├── StringBuffer.h ├── StringFormatter.cpp ├── StringFormatter.h ├── TemplateForEnums.h ├── TrackManager.cpp ├── TrackManager.h ├── Turnouts.cpp ├── Turnouts.h ├── Turntables.cpp ├── Turntables.h ├── Websockets.cpp ├── Websockets.h ├── WiThrottle.cpp ├── WiThrottle.h ├── WifiESP32.cpp ├── WifiESP32.h ├── WifiInboundHandler.cpp ├── WifiInboundHandler.h ├── WifiInterface.cpp ├── WifiInterface.h ├── Ztest.cpp ├── Ztest.h ├── config.example.h ├── defines.h ├── docs/ │ ├── DoxyfileEXRAIL │ ├── Makefile │ ├── _static/ │ │ └── css/ │ │ ├── dccex_theme.css │ │ └── sphinx_design_overrides.css │ ├── conf.py │ ├── index.rst │ ├── make.bat │ ├── requirements.txt │ └── robots.txt ├── install_via_powershell.cmd ├── installer.json ├── installer.ps1 ├── installer.sh ├── libsha1.cpp ├── libsha1.h ├── myAutomation.example.h ├── myEX-Turntable.example.h ├── myHal.cpp.txt ├── myHal.cpp_example.txt ├── myTrackStatus.example.h ├── objdump.bat ├── objdump.sh ├── platformio.ini ├── release_notes.md └── version.h ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitattributes ================================================ # Auto detect text files and perform LF normalization * text=auto *.svg -text ================================================ FILE: .github/FUNDING.yml ================================================ github: DCC-EX patreon: dccex ================================================ FILE: .github/workflows/docs.yml ================================================ name: Docs on: push: branches: - devel pull_request: branches: [ master ] workflow_dispatch: jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4.1.1 - name: Install Requirements run: | cd docs python -m pip install --upgrade pip pip3 install -r requirements.txt sudo apt-get install doxygen - name: Build Prod docs run: | cd docs make html touch _build/html/.nojekyll - name: Deploy uses: JamesIves/github-pages-deploy-action@ba1486788b0490a235422264426c45848eac35c6 with: token: ${{ secrets.GITHUB_TOKEN }} branch: gh-pages # The branch the action should deploy to. folder: docs/_build/html # The folder the action should deploy. ================================================ FILE: .github/workflows/label-sponsors.yml ================================================ 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 }} ================================================ FILE: .github/workflows/main.yml ================================================ name: CI on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Install Python Wheel run: pip install wheel - name: Install PlatformIO Core run: pip install -U platformio - name: Copy generic config over run: cp config.example.h config.h - name: Compile Command Station (AVR) run: python -m platformio run ================================================ FILE: .github/workflows/sha.yml ================================================ name: SHA # Run this workflow ever time code is pushed to a branch # other than `main` in your repository on: push jobs: # Set the job key. The key is displayed as the job name # when a job name is not provided sha: # Name the Job name: Commit SHA # Set the type of machine to run on runs-on: ubuntu-latest if: github.ref == 'refs/heads/master' steps: # Checks out a copy of your repository on the ubuntu-latest machine - name: Checkout code uses: actions/checkout@v2 - name: Create SHA File run: | sha=$(git rev-parse --short "$GITHUB_SHA") echo "#define GITHUB_SHA \"$sha\"" > GITHUB_SHA.h - 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 ================================================ FILE: .gitignore ================================================ Release/* .ino.cpp .pioenvs .piolibdeps .clang_complete .gcc-flags.json .pio/ .vscode/ config.h mySetup.cpp myHal.cpp myFilter.cpp my*.h !my*.example.h compile_commands.json newcode.txt.old UserAddin.txt _build venv .DS_Store ================================================ FILE: .travis.yml ================================================ # Continuous Integration (CI) is the practice, in software # engineering, of merging all developer working copies with a shared mainline # several times a day < https://docs.platformio.org/page/ci/index.html > # # Documentation: # # * Travis CI Embedded Builds with PlatformIO # < https://docs.travis-ci.com/user/integration/platformio/ > # # * PlatformIO integration with Travis CI # < https://docs.platformio.org/page/ci/travis.html > # # * User Guide for `platformio ci` command # < https://docs.platformio.org/page/userguide/cmd_ci.html > # # # Please choose one of the following templates (proposed below) and uncomment # it (remove "# " before each line) or use own configuration according to the # Travis CI documentation (see above). # # # Template #1: General project. Test it using existing `platformio.ini`. # # language: python # python: # - "2.7" # # sudo: false # cache: # directories: # - "~/.platformio" # # install: # - pip install -U platformio # - platformio update # # script: # - platformio run # # Template #2: The project is intended to be used as a library with examples. # # language: python # python: # - "2.7" # # sudo: false # cache: # directories: # - "~/.platformio" # # env: # - PLATFORMIO_CI_SRC=path/to/test/file.c # - PLATFORMIO_CI_SRC=examples/file.ino # - PLATFORMIO_CI_SRC=path/to/test/directory # # install: # - pip install -U platformio # - platformio update # # script: # - platformio ci --lib="." --board=ID_1 --board=ID_2 --board=ID_N ================================================ FILE: CONTRIBUTING.md ================================================ # Contributing Thanks for considering contributing to our project. Here is a guide for how to get started and and a list of our conventions. We will also walk you through the Github command line and Desktop commands necessary to download the code, make changes, and get it included in a next version of the sofware. Before contributing to this repository, please first discuss the change you wish to make via issue, or any other method with the owners of this repository before making a change. Find us on our website at https://dcc-ex.com, on our Discord https://discord.gg/y2sB4Fp or on Trainboard: https://www.trainboard.com/highball/index.php?threads/dcc-update-project-2020.130071/ # Development Environment We recommend using PlatformIO IDE for VSCode. If you haven't yet used it, it is an easy to learn and easy to use IDE that really shines for embedded development and the Arduino based hardware we use. For more information go to https://platformio.org/ * Download and install the latest version of the Arduino IDE * Download and install the latest version of Visual Studio Code from Microsoft * Run VSCode and click on the "extensions" icon on the left. Install "PlatformIO IDE for VSCode" and the "Arduino Framework" support If you don't see C/C++ Installed in the list, install that too. We also recomment installing the Gitlens extension to make working with Git and GitHub even easier. You may ask if you can use the Arduino IDE, Visual Studio, or even a text editor and the answer is "of course" if you know what you are doing. Since you are just changing text files, you can use whatever you like as long as your commits and pull requests can be merged in GitHub. However, it will be much easier to follow our coding standards if you have an IDE that can automatically format things for you. # Coding Style Guidelines We have adopted the Google style guidlines. In particular please make sure to adhere to these standards: 1. All header files should have #define guards to prevent multiple inclusion. 2. Use Unix style line endings 3. We indent using two spaces (soft tabs) 4. Braces For more information just check our code or read https://google.github.io/styleguide/cppguide.html#C++_Version ## Using the Repository 1. Clone the repository on your local machine 2. Create a working branch using the format "username-featurename" ex: "git branch -b frightrisk-turnouts" 3. Commit offen, ex: "git add ." and then "git commit -m "description of your changes" 4. Push your changes to our repository "git push" 5. When you are ready, issue a pull request for your changes to be merged into the main branch ## Pull Request Process 1. Ensure any install or build dependencies are removed before the end of the layer when doing a build. ## Code of Conduct Be Nice ### Enforcement Contributors who do not follow the be nice rule in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. ## How Can I Contribute? The DCC-EX Team has several projects and sub teams where you can help donate your epertise. See the sections below for the project or projects you are interested in. ### Development ### Documentation ### WebThrottle-EX ### Web Support ### Organization/Coordination Links to external documentation goes here XXX ================================================ FILE: CamParser.cpp ================================================ /* * © 2023-2025, Barry Daniel * © 2025 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 . */ //sensorCAM parser.cpp devel. version 3.07 August 2025 #include "DCCEXParser.h" #include "CamParser.h" #include "FSH.h" // The CAMVPINS array will be filled by IO_EXSensorCam HAL drivers calling // the CamParser::addVpin() function. // The CAMBaseVpin is the one to be used when commands are given without a vpin. VPIN CamParser::CAMBaseVpin = 0; // no vpins yet known VPIN CamParser::CAMVPINS[] = {0,0,0,0}; // determines max # CAM's int CamParser::vpcount=sizeof(CAMVPINS)/sizeof(CAMVPINS[0]); void CamParser::parse(Print * stream, byte & opcode, byte & paramCount, int16_t p[]) { if (opcode!='N') return; // this is not for us. if (parseN(stream,paramCount,p)) opcode=0; // we have consumed this // If we fail, the caller will the =100) CAMBaseVpin=p[1]; if(p[1]<=vpcount && p[1]>0) CAMBaseVpin=CAMVPINS[p[1]-1]; DIAG(F("CAM base Vpin: %c %d "),p[0],CAMBaseVpin); return true; } if ((camop<='a') && (camop>='A')){ //switch CAM# if p[1] or p[2] dictates (beware 'k') vpin=p[1]; if(camop != 'A') if(p[2] < vpcount*100+99) { vpin=(p[1] > p[2]) ? p[1] : p[2] ; //get the larger. p[2]=p[2]%100; //strip off any CAM # } if((vpin>=100) && (int(vpin)<=vpcount*100+99)) { //limits to CAM# 1 to vpcount CAMBaseVpin=CAMVPINS[vpin/100-1]; DIAG(F("switching to CAM %d baseVpin:%d"),vpin/100,CAMBaseVpin); p[1]=p[1]%100; //strip off any CAM # } vpin=CAMBaseVpin; } if (CAMBaseVpin==0) return false; // no cam defined // send UPPER case to sensorCAM to flag binary data from a DCCEX-CS parser switch(paramCount) { case 1: // produces '^' if (STRCHR_P((const char *)F("EFGMQRVW^"),camop) == nullptr) return false; if (camop=='Q') param3=10; // for activation state of all 10 banks of sensors if (camop=='F') camop=']'; // for Reset/Finish webCAM. break; // F Coded as ']' else conflicts with case 2: // if (STRCHR_P((const char *)F("ABFHILMNOPQRSTUV"),camop)==nullptr) return false; param1=p[1]; break; case 3: // or if (p[0]>=100) { //vpin - i.e. NOT 'A' through 'Z' if (p[1]>236 || p[1]<0) return false; //row if (p[2]>316 || p[2]<0) return false; //column camop=0x80; // special 'a' case for IO_SensorCAM vpin = p[0]; }else if (STRCHR_P((const char *)F("IJMNT"),camop) == nullptr) return false; camop=p[0]; param1 = p[1]; param3 = p[2]; break; case 4: // if (camop!='A') return false; //must start with 'a' if (p[3]>316 || p[3]<0) return false; if (p[2]>236 || p[2]<0) return false; if (p[1]>97 || p[1]<0) return false; //treat as bsNo. vpin = vpin + (p[1]/10)*8 + p[1]%10; //translate p[1] camop=0x80; // special 'a' case for IO_SensorCAM param1=p[2]; // row param3=p[3]; // col break; default: return false; } DIAG(F("CamParser: %d %c %d %d"),vpin,camop,param1,param3); IODevice::writeAnalogue(vpin,param1,camop,param3); return true; } void CamParser::addVpin(VPIN pin) { // called by IO_EXSensorCam starting up a camera on a vpin byte slot=255; for (auto i=0;i. */ #ifndef CamParser_H #define CamParser_H #include #include "IODevice.h" class CamParser { public: static void parse(Print * stream, byte & opcode, byte & paramCount, int16_t p[]); static void addVpin(VPIN pin); private: static bool parseN(Print * stream, byte paramCount, int16_t p[]); static VPIN CAMBaseVpin; static VPIN CAMVPINS[]; static int vpcount; }; #endif ================================================ FILE: CommandDistributor.cpp ================================================ /* * © 2022 Harald Barth * © 2020-2025 Chris Harlow * © 2020 Gregor Baues * © 2022 Colin Murdoch * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * 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 . */ #include #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" #include "Websockets.h" #include "LocoSlot.h" // variables to hold clock time int16_t lastclocktime; int8_t lastclockrate; #if WIFI_ON || ETHERNET_ON || defined(SERIAL1_COMMANDS) || defined(SERIAL2_COMMANDS) || defined(SERIAL3_COMMANDS) || defined(SERIAL4_COMMANDS) || defined(SERIAL5_COMMANDS) || defined(SERIAL6_COMMANDS) // use a buffer to allow broadcast StringBuffer * CommandDistributor::broadcastBufferWriter=new StringBuffer(256); template void CommandDistributor::broadcastReply(clientType type, Targs... msg){ broadcastBufferWriter->flush(); StringFormatter::send(broadcastBufferWriter, msg...); broadcastToClients(type); if (type==COMMAND_TYPE) broadcastToClients(WEBSOCKET_TYPE); } #else // on a single USB connection config, write direct to Serial and ignore flush/shove template 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[MAX_NUM_TCP_CLIENTS]={ NONE_TYPE }; // 0 is and must be 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 (clientId>=sizeof (clients)) { // Caution, diag dump of buffer could corrupt ringstream // if headed by websocket bytes. DIAG(F("::parse invalid client=%d"),clientId); return; } 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) { auto websock=Websockets::checkConnectionString(clientId,buffer,stream); if (websock) { clients[clientId]=WEBSOCK_CONNECTING_TYPE; // websockets will have replied already return; } if (buffer[0] == '<') clients[clientId]=COMMAND_TYPE; else clients[clientId]=WITHROTTLE_TYPE; } // after first inbound transmission the websocket is connected if (clients[clientId]==WEBSOCK_CONNECTING_TYPE) clients[clientId]=WEBSOCKET_TYPE; // mark buffer that is sent to parser // When type is known, send the string // to the right parser if (clients[clientId] == COMMAND_TYPE) { ring->mark(clientId); DCCEXParser::parse(stream, buffer, ring); } else if (clients[clientId] == WITHROTTLE_TYPE) { ring->mark(clientId); WiThrottle::getThrottle(clientId)->parse(ring, buffer); } else if (clients[clientId] == WEBSOCKET_TYPE) { buffer=Websockets::unmask(clientId,ring, buffer); if (!buffer) return; // unmask may have handled it alrerday (ping/pong) // mark ring with client flagged as websocket for transmission later ring->mark(clientId | Websockets::WEBSOCK_CLIENT_MARKER); DCCEXParser::parse(stream, buffer, ring); } 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 for client %d processing cmd:%s"),clientId, buffer); } } else { DIAG(F("CD parse: was alredy committed")); //XXX Could have been committed by broadcastClient?! } } void CommandDistributor::forget(byte clientId) { if (clients[clientId]==WITHROTTLE_TYPE) WiThrottle::forget(clientId); clients[clientId]=NONE_TYPE; if (virtualLCDClient==clientId) virtualLCDClient=RingStream::NO_CLIENT; } #endif // This will not be called on a uno void CommandDistributor::broadcastToClients(clientType type) { byte rememberClient; (void)rememberClient; // shut up compiler warning // Broadcast to Serials if (type==COMMAND_TYPE) SerialManager::broadcast(broadcastBufferWriter->getString()); #ifdef CD_HANDLE_RING // If we are broadcasting from a wifi/eth process we need to complete its output // before merging broadcasts in the ring, then reinstate it in case // the process continues to output to its client. if (ring) { if ((rememberClient = ring->peekTargetMark()) != RingStream::NO_CLIENT) { //DIAG(F("CD precommit client %d"), rememberClient); ring->commit(); } // loop through ring clients for (byte clientId=0; clientIdmark(clientId | (type==WEBSOCKET_TYPE? Websockets::WEBSOCK_CLIENT_MARKER : 0)); 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("\n"),id, !isClosed); #ifdef CD_HANDLE_RING broadcastReply(WITHROTTLE_TYPE, F("PTA%c%d\n"), isClosed?'2':'4', id); #endif } void CommandDistributor::broadcastTurntable(int16_t id, uint8_t position, bool moving) { broadcastReply(COMMAND_TYPE, F("\n"), id, position, moving); } void CommandDistributor::broadcastClockTime(int16_t time, int8_t rate) { // The JMRI clock command is of the form : PFT65871<;>4 // The CS broadcast is of the form "\n"),time, rate); #ifdef CD_HANDLE_RING broadcastReply(WITHROTTLE_TYPE, F("PFT%l<;>%d\n"), (int32_t)time*60, rate); #endif } void CommandDistributor::setClockTime(int16_t clocktime, int8_t clockrate) { // save the latest time if changed if (clocktime != lastclocktime){ auto difference = clocktime - lastclocktime; if (difference<0) difference+=1440; DCC::setTime(clocktime,clockrate,difference>2); byte hh=clocktime/60; byte mm=clocktime%60; if (hh>23) hh=0; LCD(6,clockrate<=1?F("Time %d%d:%d%d"):F("Time %d%d:%d%d (%d)"), hh/10, hh%10, mm/10, mm%10, clockrate); // look for an event for this time #ifdef EXRAIL_ACTIVE RMFT2::clockEvent(clocktime,1); #endif // Now tell everyone else what the time is. CommandDistributor::broadcastClockTime(clocktime, clockrate); lastclocktime = clocktime; lastclockrate = clockrate; } } int16_t CommandDistributor::retClockTime() { return lastclocktime; } void CommandDistributor::broadcastLoco(LocoSlot * sp) { if (!sp) { broadcastReply(COMMAND_TYPE,F("\n")); return; } // Broadcast the given loco. // If its a consist leader, broadcast all followers too. // A consist follower will only be broadcast because its functions have changed. bool isFollower=sp->isConsistFollower(); #ifdef CD_HANDLE_RING // Use the buffer directly to avoid multiple transmits in the case of a consist broadcastBufferWriter->flush(); for (auto slot=sp; slot; slot=slot->getConsistNext()) { StringFormatter::send(broadcastBufferWriter, F("\n"), slot->getLoco(),slot->getTargetSpeed(),slot->getFunctions()); if (isFollower) break; // dont follow next chain if original call was for a follower } broadcastToClients(COMMAND_TYPE); broadcastToClients(WEBSOCKET_TYPE); #else // no ring handling, just broadcast each separately for (auto slot=sp; slot; slot=slot->getConsistNext()) { broadcastReply(COMMAND_TYPE, F("\n"), slot->getLoco(),slot->getTargetSpeed(),slot->getFunctions()); if (isFollower) break; // dont follow next chain if original call was for a follower } #endif #ifdef SABERTOOTH if (Serial2 && sp->loco == SABERTOOTH) { static uint8_t rampingmode = 0; auto speedCode=sp->getSpeedCode(); bool direction = (speedCode & 0x80) !=0; // true for forward int32_t speed = speedCode & 0x7f; if (speed == 1) { // emergency stop if (rampingmode != 1) { rampingmode = 1; Serial2.print("R1: 0\r\n"); Serial2.print("R2: 0\r\n"); } Serial2.print("MD: 0\r\n"); } else { if (speed != 0) { // speed is here 2 to 127 speed = (speed - 1) * 1625 / 100; speed = speed * (direction ? 1 : -1); // speed is here -2047 to 2047 } if (rampingmode != 2) { rampingmode = 2; Serial2.print("R1: 2047\r\n"); Serial2.print("R2: 2047\r\n"); } Serial2.print("M1: "); Serial2.print(speed); Serial2.print("\r\n"); Serial2.print("M2: "); Serial2.print(speed); Serial2.print("\r\n"); } } #endif #ifdef CD_HANDLE_RING WiThrottle::markForBroadcast(sp->getLoco()); #endif } void CommandDistributor::broadcastForgetLoco(int16_t loco) { broadcastReply(COMMAND_TYPE, F("\n<- %d>\n"), loco,loco); } void CommandDistributor::broadcastPower() { char pstr[] = "? x"; byte trackcount=0; byte oncount=0; byte offcount=0; uint8_t numTracks = TrackManager::numTracks(); { char trackLetter[numTracks+1]; trackLetter[numTracks] = '\0'; for(byte t=0; t\n"),pstr); if (TrackManager::isActive(t)) { trackcount++; // do not call getPower(t) unless isActive(t)! if (TrackManager::getPower(t) == POWERMODE::ON) { oncount++; trackLetter[t] = t + 'A'; } else if (TrackManager::getPower(t) == POWERMODE::OFF) { offcount++; trackLetter[t] = t + 'a'; } else { trackLetter[t] = 'X'; } } else { trackLetter[t] = '_'; } } //DIAG(F("t=%d on=%d off=%d"), trackcount, oncount, offcount); char state='2'; if (oncount==0 || offcount == trackcount) // none on or all active off state = '0'; else if (oncount == numTracks) { // all on, no inactive tracks state = '1'; } if (state != '2') broadcastReply(COMMAND_TYPE, F("\n"),state); // additional info about MAIN, PROG and JOIN bool main=TrackManager::getMainPower()==POWERMODE::ON; bool prog=TrackManager::getProgPower()==POWERMODE::ON; bool join=TrackManager::isJoined(); //DIAG(F("m=%d p=%d j=%d"), main, prog, join); const FSH * reason=F(""); if (join) { reason = F(" JOIN"); // with space at start so we can append without space broadcastReply(COMMAND_TYPE, F("\n"),reason); } else { if (main) { //reason = F("MAIN"); broadcastReply(COMMAND_TYPE, F("\n")); } if (prog) { //reason = F("PROG"); broadcastReply(COMMAND_TYPE, F("\n")); } } #ifdef CD_HANDLE_RING // send '1' if all main are on, otherwise global state (which in that case is '0' or '2') broadcastReply(WITHROTTLE_TYPE, F("PPA%c\n"), main?'1': state); #endif #if defined(HAS_ENOUGH_MEMORY) LCD(2,F("PWR %s%S"),state=='1'? "On" : ( state=='0'? "Off" : trackLetter ),reason); #else LCD(2,F("PWR %s%S"),trackLetter ,reason); #endif } } void CommandDistributor::broadcastRaw(clientType type, char * msg) { broadcastReply(type, F("%s"),msg); } void CommandDistributor::broadcastEstopLock(bool locked) { if (locked) { broadcastReply(COMMAND_TYPE, F("\n")); broadcastReply(WITHROTTLE_TYPE, F("HmESTOP PAUSED\n")); } else { broadcastReply(COMMAND_TYPE, F("\n")); broadcastReply(WITHROTTLE_TYPE, F("HmESTOP RESUMED\n")); } } void CommandDistributor::broadcastMessage(char * message) { broadcastReply(COMMAND_TYPE, F("\n"),message); broadcastReply(WITHROTTLE_TYPE, F("Hm%s\n"),message); } void CommandDistributor::broadcastTrackState(const FSH* format, byte trackLetter, const FSH *modename, int16_t dcAddr) { broadcastReply(COMMAND_TYPE, format, trackLetter, modename, dcAddr); } void CommandDistributor::broadcastRouteState(int16_t routeId, byte state ) { broadcastReply(COMMAND_TYPE, F("\n"),routeId,state); } void CommandDistributor::broadcastRouteCaption(int16_t routeId, const FSH* caption ) { broadcastReply(COMMAND_TYPE, F("\n"),routeId,caption); } Print * CommandDistributor::getVirtualLCDSerial(byte screen, byte row) { Print * stream=virtualLCDSerial; #ifdef CD_HANDLE_RING rememberVLCDClient=RingStream::NO_CLIENT; if (!stream && virtualLCDClient!=RingStream::NO_CLIENT) { // If we are broadcasting from a wifi/eth process we need to complete its output // before merging broadcasts in the ring, then reinstate it in case // the process continues to output to its client. if ((rememberVLCDClient = ring->peekTargetMark()) != RingStream::NO_CLIENT) { ring->commit(); } ring->mark(virtualLCDClient); stream=ring; } #endif if (stream) StringFormatter::send(stream,F("<@ %d %d \""), screen,row); return stream; } void CommandDistributor::commitVirtualLCDSerial() { #ifdef CD_HANDLE_RING if (virtualLCDClient!=RingStream::NO_CLIENT) { StringFormatter::send(ring,F("\">\n")); ring->commit(); if (rememberVLCDClient!=RingStream::NO_CLIENT) ring->mark(rememberVLCDClient); return; } #endif StringFormatter::send(virtualLCDSerial,F("\">\n")); } void CommandDistributor::setVirtualLCDSerial(Print * stream) { #ifdef CD_HANDLE_RING virtualLCDClient=RingStream::NO_CLIENT; if (stream && stream->availableForWrite()==RingStream::THIS_IS_A_RINGSTREAM) { virtualLCDClient=((RingStream *) stream)->peekTargetMark(); virtualLCDSerial=nullptr; return; } #endif virtualLCDSerial=stream; } Print* CommandDistributor::virtualLCDSerial=&USB_SERIAL; byte CommandDistributor::virtualLCDClient=0xFF; byte CommandDistributor::rememberVLCDClient=0; ================================================ FILE: CommandDistributor.h ================================================ /* * © 2022 Harald Barth * © 2020-2025 Chris Harlow * © 2020 Gregor Baues * © 2022 Colin Murdoch * * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * 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 . */ #ifndef CommandDistributor_h #define CommandDistributor_h #include "DCCEXParser.h" #include "RingStream.h" #include "StringBuffer.h" #include "defines.h" #include "EXRAIL2.h" #include "DCC.h" #if WIFI_ON | ETHERNET_ON // Command Distributor must handle a RingStream of clients #define CD_HANDLE_RING #endif class CommandDistributor { public: enum clientType: byte {NONE_TYPE = 0,COMMAND_TYPE,WITHROTTLE_TYPE,WEBSOCK_CONNECTING_TYPE,WEBSOCKET_TYPE}; // independent of other types, NONE_TYPE must be 0 private: static void broadcastToClients(clientType type); static StringBuffer * broadcastBufferWriter; #ifdef CD_HANDLE_RING static RingStream * ring; static clientType clients[MAX_NUM_TCP_CLIENTS]; #endif public : static void parse(byte clientId,byte* buffer, RingStream * ring); static void broadcastLoco(LocoSlot * slot); static void broadcastForgetLoco(int16_t loco); static void broadcastSensor(int16_t id, bool value); static void broadcastTurnout(int16_t id, bool isClosed); static void broadcastTurntable(int16_t id, uint8_t position, bool moving); static void broadcastClockTime(int16_t time, int8_t rate); static void setClockTime(int16_t time, int8_t rate); static int16_t retClockTime(); static void broadcastPower(); static void broadcastRaw(clientType type,char * msg); static void broadcastTrackState(const FSH* format,byte trackLetter, const FSH* modename, int16_t dcAddr); template static void broadcastReply(clientType type, Targs... msg); static void forget(byte clientId); static void broadcastRouteState(int16_t routeId,byte state); static void broadcastRouteCaption(int16_t routeId,const FSH * caption); static void broadcastMessage(char * message); static void broadcastEstopLock(bool locked); // Handling code for virtual LCD receiver. static Print * getVirtualLCDSerial(byte screen, byte row); static void commitVirtualLCDSerial(); static void setVirtualLCDSerial(Print * stream); private: static Print * virtualLCDSerial; static byte virtualLCDClient; static byte rememberVLCDClient; }; #endif ================================================ FILE: CommandStation-EX.ino ================================================ //////////////////////////////////////////////////////////////////////////////////// // DCC-EX CommandStation-EX Please see https://DCC-EX.com // // This file is the main sketch for the Command Station. // // 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. // // If config.h is not found, the command station will build with no motor shield. //////////////////////////////////////////////////////////////////////////////////// #if __has_include ( "config.h") #include "config.h" #else #warning config.h not found. #endif #ifndef MOTOR_SHIELD_TYPE #warning MOTOR_SHIELD_TYPE not found. Building with no motor shield #define MOTOR_SHIELD_TYPE NO_SHIELD #endif /* * © 2021 Neil McKechnie * © 2020-2025 Chris Harlow, Harald Barth, David Cutting, * Fred Decker, Gregor Baues, Anthony W - Dayton * © 2023 Nathan Kellenicki * © 2025 Herb Morton * 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 . */ #include "DCCEX.h" #include "Display_Implementation.h" #ifdef ARDUINO_ARCH_ESP32 #include "Sniffer.h" #include "DCCDecoder.h" Sniffer *dccSniffer = NULL; bool DCCDecoder::active = false; #endif // ARDUINO_ARCH_ESP32 #define QWRAP_(x) QWRAP__(x) #define QWRAP__(x) #x static_assert(MAX_LOCOS >1 && MAX_LOCOS<256, "#define MAX_LOCOS " QWRAP_(MAX_LOCOS) " must be >1 and <256"); #ifdef CPU_TYPE_ERROR #error CANNOT COMPILE - DCC++ EX ONLY WORKS WITH THE ARCHITECTURES LISTED IN defines.h #endif #ifdef WIFI_WARNING #warning You have defined that you want WiFi but your hardware has not enough memory to do that, so WiFi DISABLED #endif #ifdef ETHERNET_WARNING #warning You have defined that you want Ethernet but your hardware has not enough memory to do that, so Ethernet DISABLED #endif #ifdef EXRAIL_WARNING #warning You have myAutomation.h but your hardware has not enough memory to do that, so EX-RAIL DISABLED #endif // compile time check, passwords 1 to 7 chars do not work, so do not try to compile with them at all // remember trailing '\0', sizeof("") == 1. #define PASSWDCHECK(S) static_assert(sizeof(S) == 1 || sizeof(S) > 8, "Password shorter than 8 chars") void setup() { // The main sketch has responsibilities during setup() // Responsibility 1: Start the usb connection for diagnostics // This is normally Serial but uses SerialUSB on a SAMD processor SerialManager::init(); DIAG(F("License GPLv3 fsf.org (c) dcc-ex.com")); // If user has defined a startup delay, delay here before starting IO #if defined(STARTUP_DELAY) DIAG(F("Delaying startup for %dms"), STARTUP_DELAY); delay(STARTUP_DELAY); #endif // Initialise HAL layer before reading EEprom or setting up MotorDrivers IODevice::begin(); // As the setup of a motor shield may require a read of the current sense input from the ADC, // let's make sure to initialise the ADCee class! ADCee::begin(); // Set up MotorDrivers early to initialize all pins TrackManager::Setup(MOTOR_SHIELD_TYPE); DISPLAY_START ( // This block is still executed for DIAGS if display not in use LCD(0,F("DCC-EX v" VERSION)); LCD(1,F("Lic GPLv3")); ); // Responsibility 2: Start all the communications before the DCC engine // Start the WiFi interface on a MEGA, Uno cannot currently handle WiFi // Start Ethernet if it exists #if WIFI_ON PASSWDCHECK(WIFI_PASSWORD); // compile time check #ifndef ARDUINO_ARCH_ESP32 WifiInterface::setup(WIFI_SERIAL_LINK_SPEED, F(WIFI_SSID), F(WIFI_PASSWORD), F(WIFI_HOSTNAME), IP_PORT, WIFI_CHANNEL, WIFI_FORCE_AP); #else WifiESP::setup(WIFI_SSID, WIFI_PASSWORD, WIFI_HOSTNAME, IP_PORT, WIFI_CHANNEL, WIFI_FORCE_AP); #endif // ARDUINO_ARCH_ESP32 #endif // WIFI_ON #if ETHERNET_ON EthernetInterface::setup(); #endif // ETHERNET_ON // Responsibility 3: Start the DCC engine. DCC::begin(); // Start RMFT aka EX-RAIL (ignored if no automnation) RMFT::begin(); #ifdef ARDUINO_ARCH_ESP32 #ifdef BOOSTER_INPUT dccSniffer = new Sniffer(BOOSTER_INPUT); #endif // BOOSTER_INPUT #endif // ARDUINO_ARCH_ESP32 // Invoke any DCC++EX commands in the form "SETUP("xxxx");"" found in optional file mySetup.h. // This can be used to create turnouts, outputs, sensors etc. through the normal text commands. #if __has_include ( "mySetup.h") #define SETUP(cmd) DCCEXParser::parse(F(cmd)) #include "mySetup.h" #undef SETUP #endif #if defined(LCN_SERIAL) LCN_SERIAL.begin(115200); LCN::init(LCN_SERIAL); #endif LCD(3, F("Ready")); CommandDistributor::broadcastPower(); } void loop() { #ifdef ENABLE_SERIAL_LOG SerialLog.loop(); #endif #ifdef ARDUINO_ARCH_ESP32 #ifdef BOOSTER_INPUT static bool oldactive = false; if (dccSniffer) { bool newactive = dccSniffer->inputActive(); if (oldactive != newactive) { RMFT2::railsyncEvent(newactive); oldactive = newactive; } DCCPacket p = dccSniffer->fetchPacket(); if (p.len() != 0) { if (DCCDecoder::parse(p)) { if (Diag::SNIFFER) p.print(); } } } #endif // BOOSTER_INPUT #endif // ARDUINO_ARCH_ESP32 // The main sketch has responsibilities during loop() // Responsibility 1: Handle DCC background processes // (loco reminders and power checks) DCC::loop(); // Responsibility 2: handle any incoming commands on USB connection SerialManager::loop(); // Responsibility 3: Optionally handle any incoming WiFi traffic #ifndef ARDUINO_ARCH_ESP32 #if WIFI_ON WifiInterface::loop(); #endif //WIFI_ON #else //ARDUINO_ARCH_ESP32 #if WIFI_ON #ifndef WIFI_TASK_ON_CORE0 WifiESP::loop(); #endif #endif //WIFI_ON #endif //ARDUINO_ARCH_ESP32 #if ETHERNET_ON EthernetInterface::loop(); #endif RMFT::loop(); // ignored if no automation #if defined(LCN_SERIAL) LCN::loop(); #endif // Display refresh DisplayInterface::loop(); // Handle/update IO devices. IODevice::loop(); 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 #ifdef ARDUINO_ARCH_AVR // count every byte of free RAM on AVR int freeNow = DCCTimer::getMinimumFreeMemory(); if (freeNow < ramLowWatermark) { ramLowWatermark = freeNow; LCD(3,F("Free RAM=%5db"), ramLowWatermark); } #else // on other platforms, just report every 4kb int freeNow = DCCTimer::getMinimumFreeMemory() / 4096; if (freeNow < ramLowWatermark) { ramLowWatermark = freeNow; LCD(3,F("Free RAM=%5dKb"), ramLowWatermark*4); } #endif } ================================================ FILE: DCC.cpp ================================================ /* * © 2021 Neil McKechnie * © 2021 Mike S * © 2021 Fred Decker * © 2021 Herb Morton * © 2020-2022 Harald Barth * © 2020-2021 M Steve Todd * © 2020-2026 Chris Harlow * All rights reserved. * * 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 . */ #include "DIAG.h" #include "DCC.h" #include "DCCWaveform.h" #include "DCCConsist.h" #ifndef DISABLE_EEPROM #include "EEStore.h" #endif #include "GITHUB_SHA.h" #include "version.h" #include "FSH.h" #include "IODevice.h" #include "EXRAIL2.h" #include "CommandDistributor.h" #include "TrackManager.h" #include "DCCTimer.h" #include "Railcom.h" #include "DCCQueue.h" // This module is responsible for converting API calls into // messages to be sent to the waveform generator. // It has no visibility of the hardware, timers, interrupts // nor of the waveform issues such as preambles, start bits checksums or cutouts. // // Nor should it have to deal with JMRI responsess other than the OK/FAIL // or cv value returned. I will move that back to the JMRI interface later // // The interface to the waveform generator is narrowed down to merely: // Scheduling a message on the prog or main track using a function // Obtaining ACKs from the prog track using a function // There are no volatiles here. const byte FN_GROUP_1=0x01; const byte FN_GROUP_2=0x02; const byte FN_GROUP_3=0x04; const byte FN_GROUP_4=0x08; const byte FN_GROUP_5=0x10; FSH* DCC::shieldName=NULL; byte DCC::globalSpeedsteps=128; #define SLOTLOOP for (auto slot=LocoSlot::getFirst();slot;slot=slot->getNext()) void DCC::begin() { StringFormatter::send(&USB_SERIAL,F("\n"), F(VERSION), F(ARDUINO_TYPE), shieldName, F(GITHUB_SHA)); #ifndef DISABLE_EEPROM // Load stuff from EEprom (void)EEPROM; // tell compiler not to warn this is unused EEStore::init(); #endif #ifndef ARDUINO_ARCH_ESP32 /* On ESP32 started in TrackManager::setTrackMode() */ DCCWaveform::begin(); #endif } byte DCC::defaultMomentumA=0; byte DCC::defaultMomentumD=0; bool DCC::linearAcceleration=false; byte DCC::getMomentum(LocoSlot * slot) { auto target=slot->getTargetSpeed() & 0x7f; auto current=slot->getSpeedCode() & 0x7f; if (target > current) { // accelerating auto momentum=(slot->getMomentumA() == MOMENTUM_USE_DEFAULT) ? defaultMomentumA : slot->getMomentumA(); // if nonlinear acceleration, momentum is reduced according to // gap between throttle and speed. // ie. Loco takes accelerates faster if high throttle if (momentum==0 || linearAcceleration) return momentum; auto powerDifference= (target-current)/8; if (momentum-powerDifference <0) return 0; return momentum-powerDifference; } return (slot->getMomentumD() == MOMENTUM_USE_DEFAULT) ? defaultMomentumD : slot->getMomentumD(); } bool DCC::setThrottle( uint16_t cab, uint8_t tSpeed, bool tDirection) { if (tSpeed==1) { if (cab==0) { estopAll(); // ESTOP broadcast fix return true; } } byte speedCode = (tSpeed & 0x7F) + tDirection * 128; auto slot=LocoSlot::getSlot(cab, true); if (!slot) return false; // speed table full, can not do anything // Ignore any throttle command to consist follower. if (slot->isConsistFollower()) return true; if (slot->getTargetSpeed()==speedCode) // speed has been reached return true; slot->setTargetSpeed(speedCode); // copy target speed to consist followers for (auto follower=slot->getConsistNext(); follower; follower=follower->getConsistNext()) { follower->setTargetSpeed(speedCode ^ (follower->isConsistReverse() ? 0x80 : 0) ); } byte momentum=getMomentum(slot); if (momentum && tSpeed!=1) { // not ESTOP // we dont throttle speed, we just let the reminders take it to target slot->setMomentumBase(millis()); } else { // Momentum not involved, throttle now. setThrottle2(slot,speedCode); if (!estopIsLocked) TrackManager::setDCSignal(cab,speedCode); // in case this is a dcc track on this addr } CommandDistributor::broadcastLoco(slot); return true; } // set speedCode directly to DCC and make followers same void DCC::setThrottle2( LocoSlot * slot, byte speedCode) { for (auto follower=slot; follower; follower=follower->getConsistNext()) { follower->setSpeedCode(speedCode); setThrottleDCC(follower,speedCode); } } void DCC::setThrottleDCC( LocoSlot * slot, byte speedCode) { uint16_t cab=0; if (slot) { cab=slot->getLoco(); if (slot->isConsistReverse()) speedCode^=0x80; } // any throttle traffic is blocked when estop is locked if (estopIsLocked) { // replace speed with emergency stop but keep direction speedCode = (speedCode & 0x80) | 0x01; } uint8_t b[4]; uint8_t nB = 0; // DIAG(F("setSpeedInternal %d %x"),cab,speedCode); if (cab > HIGHEST_SHORT_ADDR) b[nB++] = highByte(cab) | 0xC0; // convert train number into a two-byte address b[nB++] = lowByte(cab); if (globalSpeedsteps <= 28) { uint8_t speed128 = speedCode & 0x7F; uint8_t speed28; uint8_t code28; if (speed128 == 0 || speed128 == 1) { // stop or emergency stop code28 = speed128; } else { speed28= (speed128*10+36)/46; // convert 2-127 to 1-28 /* if (globalSpeedsteps <= 14) // Don't want to do 14 steps, to get F0 there is ugly code28 = (speed28+3)/2 | (Value of F0); // convert 1-28 to DCC 14 step speed code else */ code28 = (speed28+3)/2 | ( (speed28 & 1) ? 0 : 0b00010000 ); // convert 1-28 to DCC 28 step speed code } // Construct command byte from: // command speed direction b[nB++] = 0b01000000 | code28 | ((speedCode & 0x80) ? 0b00100000 : 0); } else { // 128 speedsteps b[nB++] = SET_SPEED; // 128-step speed control byte b[nB++] = speedCode; // for encoding see setThrottle } if ((speedCode & 0x7F) == 1) DCCQueue::scheduleEstopPacket(b, nB, 4, cab); // highest priority else DCCQueue::scheduleDCCSpeedPacket( b, nB, 0, cab); } void DCC::setFunctionInternal(int cab, byte group, byte byte1, byte byte2) { // DIAG(F("setFunctionInternal %d %x %x"),cab,byte1,byte2); byte b[4]; byte nB = 0; if (cab > HIGHEST_SHORT_ADDR) b[nB++] = highByte(cab) | 0xC0; // convert train number into a two-byte address b[nB++] = lowByte(cab); if (byte1!=0) b[nB++] = byte1; b[nB++] = byte2; DCCQueue::scheduleDCCFunctionPacket(b, nB, cab,group); } // returns speed steps 0 to 127 (1 == emergency stop) // or -1 on "loco not found" int8_t DCC::getThrottleSpeed(int cab) { return getThrottleSpeedByte(cab) & 0x7F; } // returns speed code byte // or 128 (speed 0, dir forward) on "loco not found". // This is the throttle set speed... which may be different // from the actual loco speed if momentum is active or // speed limiting is applied. uint8_t DCC::getThrottleSpeedByte(int cab) { auto slot=LocoSlot::getSlot(cab,false); return slot?slot->getTargetSpeed():128; } // returns speed code byte for loco. // This is the most recently send DCC speed packet byte // or 128 (speed 0, dir forward) on "loco not found". uint8_t DCC::getLocoSpeedByte(int cab) { auto slot=LocoSlot::getSlot(cab,false); return slot?slot->getSpeedCode():128; } // returns 0 to 7 for frequency uint8_t DCC::getThrottleFrequency(int cab) { #if defined(ARDUINO_AVR_UNO) (void)cab; return 0; #else auto slot=LocoSlot::getSlot(cab,false); if (slot == nullptr) // speed table full, can not do anything return 0; // return value for default frequency // shift out first 29 bits so we have the 3 "frequency bits" left uint8_t res = (uint8_t)(slot->getFunctions() >>29); //DIAG(F("Speed table %d functions %l shifted %d"), reg, slot->functions, res); return res; #endif } // returns direction on loco // or true/forward on "loco not found" bool DCC::getThrottleDirection(int cab) { return getThrottleSpeedByte(cab) & 0x80; } // Set function to value on or off bool DCC::setFn( int cab, int16_t functionNumber, bool on) { if (cab<=0 ) return false; if (functionNumber < 0) return false; if (functionNumber>28) { //non reminding advanced binary bit set byte b[5]; byte nB = 0; if (cab > HIGHEST_SHORT_ADDR) b[nB++] = highByte(cab) | 0xC0; // convert train number into a two-byte address b[nB++] = lowByte(cab); if (functionNumber <= 127) { b[nB++] = 0b11011101; // Binary State Control Instruction short form b[nB++] = functionNumber | (on ? 0x80 : 0); } else { b[nB++] = 0b11000000; // Binary State Control Instruction long form b[nB++] = (functionNumber & 0x7F) | (on ? 0x80 : 0); // low order bits and state flag b[nB++] = functionNumber >>7 ; // high order bits } DCCQueue::scheduleDCCPacket(b, nB, 4,cab); } // We use the reminder table up to 28 for normal functions. // We use 29 to 31 for DC frequency as well so up to 28 // are "real" functions and 29 to 31 are frequency bits // controlled by function buttons if (functionNumber > 31) return true; auto slot=LocoSlot::getSlot(cab,true); if (!slot) return false; // speed table full, can not do anything // Take care of functions: // Set state of function uint32_t previous=slot->getFunctions(); uint32_t newset=previous; uint32_t funcmask = (1UL<setFunctions(newset); if (functionNumber <= 28) updateGroupflags(slot, functionNumber); CommandDistributor::broadcastLoco(slot); } return true; } // Flip function state (used from withrottle protocol) void DCC::changeFn( int cab, int16_t functionNumber) { auto currentValue=getFn(cab,functionNumber); if (currentValue<0) return; // function not valid for change setFn(cab,functionNumber, currentValue?false:true); } // Report function state (used from withrottle protocol) // returns 0 false, 1 true or -1 for do not know int8_t DCC::getFn( int cab, int16_t functionNumber) { if (cab<=0 || functionNumber>31) return -1; // unknown auto slot = LocoSlot::getSlot(cab, false); if (slot == nullptr) // not found return -1; unsigned long funcmask = (1UL<getFunctions() & funcmask)? 1 : 0; } // Set the group flag to say we have touched the particular group. // A group will be reminded only if it has been touched. void DCC::updateGroupflags(LocoSlot * slot, int16_t functionNumber) { byte groupMask; if (functionNumber<=4) groupMask=FN_GROUP_1; else if (functionNumber<=8) groupMask=FN_GROUP_2; else if (functionNumber<=12) groupMask=FN_GROUP_3; else if (functionNumber<=20) groupMask=FN_GROUP_4; else groupMask=FN_GROUP_5; slot->setGroupFlags((slot->getGroupFlags()) | groupMask); } uint32_t DCC::getFunctionMap(int cab) { if (cab<=0) return 0; // unknown pretend all functions off auto slot = LocoSlot::getSlot(cab,false); return slot?slot->getFunctions():0; } // saves DC frequency (0..3) in spare functions 29,30,31 void DCC::setDCFreq(int cab,byte freq) { if (cab==0 || freq>3) return; auto slot=LocoSlot::getSlot(cab,true); if (!slot) return; // speed table full, can not do anything // drop and replace F29,30,31 (top 3 bits) auto newFunctions=slot->getFunctions() & 0x1FFFFFFFUL; // get and clear relevant bits if (freq != 0) newFunctions |= (1UL<<(28 + freq)); // 1->29, 2->30, 3->31 if (newFunctions==slot->getFunctions()) return; // no change slot->setFunctions(newFunctions); CommandDistributor::broadcastLoco(slot); } void DCC::saveSpeed(int cab) { auto slot=LocoSlot::getSlot(cab,false); if (slot == nullptr) // speed table full, can not do anything return; slot->saveSpeed(); } void DCC::restoreSpeed(int cab) { auto slot=LocoSlot::getSlot(cab,false); if (slot == nullptr) // speed table full, can not do anything return; auto speedCode=slot->getSavedSpeedCode(); setThrottle(cab, speedCode& 0x7f, (speedCode & 0x80)!=0); } void DCC::setAccessory(int address, byte port, bool gate, byte onoff /*= 2*/) { // onoff is tristate: // 0 => send off packet // 1 => send on packet // >1 => send both on and off packets. // An accessory has an address, 4 ports and 2 gates (coils) each. That's how // the initial decoders were orgnized and that influenced how the DCC // standard was made. #ifdef DIAG_IO DIAG(F("DCC::setAccessory(%d,%d,%d,%d)"), address, port, gate, onoff); #endif // use masks to detect wrong values and do nothing if(address != (address & 511)) return; if(port != (port & 3)) return; byte b[2]; // first byte is of the form 10AAAAAA, where AAAAAA represent 6 least signifcant bits of accessory address // second byte is of the form 1AAACPPG, where C is 1 for on, PP the ports 0 to 3 and G the gate (coil). b[0] = address % 64 + 128; b[1] = ((((address / 64) % 8) << 4) + (port % 4 << 1) + gate % 2) ^ 0xF8; if (onoff==0) { // off packet only b[1] &= ~0x08; // set C to 0 DCCQueue::scheduleDCCPacket(b, 2, 3); } else if (onoff==1) { // on packet only DCCQueue::scheduleDCCPacket(b, 2, 3); } else { // auto timed on then off DCCQueue::scheduleAccOnOffPacket(b, 2, 3, 100); // On then off after 100mS } #if defined(EXRAIL_ACTIVE) if (onoff !=0) RMFT2::activateEvent(address<<2|port,gate); #endif } bool DCC::setExtendedAccessory(int16_t address, int16_t value, byte repeats) { /* From https://www.nmra.org/sites/default/files/s-9.2.1_2012_07.pdf The Extended Accessory Decoder Control Packet is included for the purpose of transmitting aspect control to signal decoders or data bytes to more complex accessory decoders. Each signal head can display one aspect at a time. {preamble} 0 10AAAAAA 0 0AAA0AA1 0 000XXXXX 0 EEEEEEEE 1 XXXXX is for a single head. A value of 00000 for XXXXX indicates the absolute stop aspect. All other aspects represented by the values for XXXXX are determined by the signaling system used and the prototype being modeled. From https://normen.railcommunity.de/RCN-213.pdf: More information is in RCN-213 about how the address bits are organized. preamble -0- 1 0 A7 A6 A5 A4 A3 A2 -0- 0 ^A10 ^A9 ^A8 0 A1 A0 1 -0- .... Thus in byte packet form the format is 10AAAAAA, 0AAA0AA1, 000XXXXX Die Adresse für den ersten erweiterten Zubehördecoder ist wie bei den einfachen Zubehördecodern die Adresse 4 = 1000-0001 0111-0001 . Diese Adresse wird in Anwenderdialogen als Adresse 1 dargestellt. This means that the first address shown to the user as "1" is mapped to internal address 4. Note that the Basic accessory format mentions "By convention these bits (bits 4-6 of the second data byte) are in ones complement" but this note is absent from the advanced packet description. The english translation does not mention that the address format for the advanced packet follows the one for the basic packet but according to the RCN-213 this is the case. We allow for addresses from -3 to 2047-3 as that allows to address the whole range of the 11 bits sent to track. */ if ((address > 2044) || (address < -3)) return false; // 2047-3, 11 bits but offset 3 if (value != (value & 0x1F)) return false; // 5 bits address+=3; // +3 offset according to RCN-213 byte b[3]; b[0]= 0x80 // bits always on | ((address>>2) & 0x3F); // shift out 2, mask out used bits b[1]= 0x01 // bits always on | (((~(address>>8)) & 0x07)<<4) // shift out 8, invert, mask 3 bits, shift up 4 | ((address & 0x03)<<1); // mask 2 bits, shift up 1 b[2]=value; DCCQueue::scheduleDCCPacket(b, sizeof(b), repeats); return true; } // // writeCVByteMain: Write a byte with PoM on main. This writes // the 5 byte sized packet to implement this DCC function // void DCC::writeCVByteMain(int cab, int cv, byte bValue) { byte b[5]; byte nB = 0; if (cab > HIGHEST_SHORT_ADDR) b[nB++] = highByte(cab) | 0xC0; // convert train number into a two-byte address b[nB++] = lowByte(cab); b[nB++] = cv1(WRITE_BYTE_MAIN, cv); // any CV>1023 will become modulus(1024) due to bit-mask of 0x03 b[nB++] = cv2(cv); b[nB++] = bValue; DCCQueue::scheduleDCCPacket(b, nB, 4,cab); } // // readCVByteMain: Read a byte with PoM on main. // This requires Railcom active // void DCC::readCVByteMain(int cab, int cv, ACK_CALLBACK callback) { byte b[5]; byte nB = 0; if (cab > HIGHEST_SHORT_ADDR) b[nB++] = highByte(cab) | 0xC0; // convert train number into a two-byte address b[nB++] = lowByte(cab); b[nB++] = cv1(READ_BYTE_MAIN, cv); // any CV>1023 will become modulus(1024) due to bit-mask of 0x03 b[nB++] = cv2(cv); b[nB++] = 0; DCCQueue::scheduleDCCPacket(b, nB, 2,cab); Railcom::anticipate(cab,cv,callback); } // // writeCVBitMain: Write a bit of a byte with PoM on main. This writes // the 5 byte sized packet to implement this DCC function // void DCC::writeCVBitMain(int cab, int cv, byte bNum, bool bValue) { byte b[5]; byte nB = 0; bValue = bValue % 2; bNum = bNum % 8; if (cab > HIGHEST_SHORT_ADDR) b[nB++] = highByte(cab) | 0xC0; // convert train number into a two-byte address b[nB++] = lowByte(cab); b[nB++] = cv1(WRITE_BIT_MAIN, cv); // any CV>1023 will become modulus(1024) due to bit-mask of 0x03 b[nB++] = cv2(cv); b[nB++] = WRITE_BIT | (bValue ? BIT_ON : BIT_OFF) | bNum; DCCQueue::scheduleDCCPacket(b, nB, 4,cab); } bool DCC::setTime(uint16_t minutes,uint8_t speed, bool suddenChange) { /* see rcn-122 5 Global commands These commands are sent and begin exclusively with a broadcast address 0 always with {synchronous bits} 0 0000-0000 … and end with the checksum ... PPPPPPPP 1. Therefore, only the bytes of the commands and not that of shown below whole package shown. The commands can be used by vehicle and accessory decoders alike. 5.1 Time command This command is four bytes long and has the format: 1100-0001 CCxx-xxxx xxxx-xxxxx xxxx-xxxx CC indicates what data is transmitted in the packet: CC = 00 Model Time 1100-0001 00MM-MMMM WWWH-HHHH U0BB-BBBB with: MMMMMM = Minutes, Value range: 0..59 WWW = Day of the Week, Value range: 0 = Monday, 1 = Tuesday, 2 = Wednesday, 3 = Thursday, 4 = Friday, 5 = Saturday, 6 = Sunday, 7 = Weekday is not supported. HHHHH = Hours, value range: 0..23 U = Update, i.e. the time has changed suddenly, e.g. by a new one timetable to start. Up to 4 can occur per sudden change commands can be marked like this. BBBBBB = Acceleration factor, value range 0..63. An acceleration factor of 0 means the model clock has been stopped, a factor of 1 corresponds to real time, at 2 the clock runs twice as fast, at three times as fast as real time, etc. */ if (minutes>=1440 || speed>63 ) return false; byte b[5]; b[0]=0; // broadcast address b[1]=0b11000001; // 1100-0001 (model time) b[2]=minutes % 60 ; // MM b[3]= 0b11100000 | (minutes/60); // 111H-HHHH weekday not supported b[4]= (suddenChange ? 0b10000000 : 0) | speed; DCCQueue::scheduleDCCPacket(b, sizeof(b), 2); return true; } FSH* DCC::getMotorShieldName() { return shieldName; } const ackOp FLASH WRITE_BIT0_PROG[] = { BASELINE, W0,WACK, V0, WACK, // validate bit is 0 ITC1, // if acked, callback(1) CALLFAIL // callback (-1) }; const ackOp FLASH WRITE_BIT1_PROG[] = { BASELINE, W1,WACK, V1, WACK, // validate bit is 1 ITC1, // if acked, callback(1) CALLFAIL // callback (-1) }; const ackOp FLASH VERIFY_BIT0_PROG[] = { BASELINE, V0, WACK, // validate bit is 0 ITC0, // if acked, callback(0) V1, WACK, // validate bit is 1 ITC1, CALLFAIL // callback (-1) }; const ackOp FLASH VERIFY_BIT1_PROG[] = { BASELINE, V1, WACK, // validate bit is 1 ITC1, // if acked, callback(1) V0, WACK, ITC0, CALLFAIL // callback (-1) }; const ackOp FLASH READ_BIT_PROG[] = { BASELINE, V1, WACK, // validate bit is 1 ITC1, // if acked, callback(1) V0, WACK, // validate bit is zero ITC0, // if acked callback 0 CALLFAIL // bit not readable }; const ackOp FLASH WRITE_BYTE_PROG[] = { BASELINE, WB,WACK,ITC1, // Write and callback(1) if ACK // handle decoders that dont ack a write VB,WACK,ITC1, // validate byte and callback(1) if correct CALLFAIL // callback (-1) }; const ackOp FLASH VERIFY_BYTE_PROG[] = { BASELINE, BIV, // ackManagerByte initial value VB,WACK, // validate byte ITCB, // if ok callback value STARTMERGE, //clear bit and byte values ready for merge pass // each bit is validated against 0 and the result inverted in MERGE // this is because there tend to be more zeros in cv values than ones. // There is no need for one validation as entire byte is validated at the end V0, WACK, MERGE, // read and merge first tested bit (7) ITSKIP, // do small excursion if there was no ack SETBIT,(ackOp)7, V1, WACK, NAKFAIL, // test if there is an ack on the inverse of this bit (7) SETBIT,(ackOp)6, // and abort whole test if not else continue with bit (6) SKIPTARGET, V0, WACK, MERGE, // read and merge second tested bit (6) V0, WACK, MERGE, // read and merge third tested bit (5) ... V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, ITCBV, // verify merged byte and return it if acked ok - with retry report CALLFAIL }; const ackOp FLASH READ_CV_PROG[] = { BASELINE, STARTMERGE, //clear bit and byte values ready for merge pass // each bit is validated against 0 and the result inverted in MERGE // this is because there tend to be more zeros in cv values than ones. // There is no need for one validation as entire byte is validated at the end V0, WACK, MERGE, // read and merge first tested bit (7) ITSKIP, // do small excursion if there was no ack SETBIT,(ackOp)7, V1, WACK, NAKFAIL, // test if there is an ack on the inverse of this bit (7) SETBIT,(ackOp)6, // and abort whole test if not else continue with bit (6) SKIPTARGET, V0, WACK, MERGE, // read and merge second tested bit (6) V0, WACK, MERGE, // read and merge third tested bit (5) ... V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, ITCB, // verify merged byte and return it if acked ok CALLFAIL }; // verification failed // returns loco id or consist id or -1 on failure const ackOp FLASH LOCO_DRIVEAWAY_PROG[] = { BASELINE, // first check cv20 for extended addressing SETCV, (ackOp)20, // CV 19 is extended SETBYTE, (ackOp)0, VB, WACK, ITSKIP, // skip past extended section if cv20 is zero // read cv20 and 19 and merge STARTMERGE, // Setup to read cv 20 V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, NAKSKIP, // bad read of cv20, assume its 0 BAD20SKIP, // detect invalid cv20 value and ignore STASHLOCOID, // keep cv 20 until we have cv19 as well. SETCV, (ackOp)19, STARTMERGE, // Setup to read cv 19 V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, NAKFAIL, // cant recover if cv 19 unreadable COMBINE1920, // Combile byte with stash and callback // end of advanced 20,19 check SKIPTARGET, SETCV, (ackOp)19, // CV 19 is consist setting SETBYTE, (ackOp)0, VB, WACK, ITSKIP, // ignore consist if cv19 is zero (no consist) SETBYTE, (ackOp)128, VB, WACK, ITSKIP, // ignore consist if cv19 is 128 (no consist, direction bit set) STARTMERGE, // Setup to read cv 19 V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, ITCB7, // return 7 bits only, No_ACK means CV19 not supported so ignore it SKIPTARGET, // continue here if CV 19 is zero or fails all validation SETCV,(ackOp)29, SETBIT,(ackOp)5, V0, WACK, ITSKIP, // Skip to SKIPTARGET if bit 5 of CV29 is zero // Long locoid SETCV, (ackOp)17, // CV 17 is part of locoid STARTMERGE, V0, WACK, MERGE, // read and merge bit 1 etc V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, NAKFAIL, // verify merged byte and return -1 it if not acked ok STASHLOCOID, // keep stashed cv 17 for later // Read 2nd part from CV 18 SETCV, (ackOp)18, STARTMERGE, V0, WACK, MERGE, // read and merge bit 1 etc V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, NAKFAIL, // verify merged byte and return -1 it if not acked ok COMBINELOCOID, // Combile byte with stash to make long locoid and callback // ITSKIP Skips to here if CV 29 bit 5 was zero. so read CV 1 and return that SKIPTARGET, SETCV, (ackOp)1, STARTMERGE, SETBIT, (ackOp)6, // skip over first bit as we know its a zero V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, ITCB, // verify merged byte and callback CALLFAIL }; // returns loco id regardless of consist const ackOp FLASH LOCO_READ_ID_PROG[] = { BASELINE, SETCV,(ackOp)29, SETBIT,(ackOp)5, V0, WACK, ITSKIP, // Skip to SKIPTARGET if bit 5 of CV29 is zero // Long locoid SETCV, (ackOp)17, // CV 17 is part of locoid STARTMERGE, V0, WACK, MERGE, // read and merge bit 1 etc V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, NAKFAIL, // verify merged byte and return -1 it if not acked ok STASHLOCOID, // keep stashed cv 17 for later // Read 2nd part from CV 18 SETCV, (ackOp)18, STARTMERGE, V0, WACK, MERGE, // read and merge bit 1 etc V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, NAKFAIL, // verify merged byte and return -1 it if not acked ok COMBINELOCOID, // Combile byte with stash to make long locoid and callback // ITSKIP Skips to here if CV 29 bit 5 was zero. so read CV 1 and return that SKIPTARGET, SETCV, (ackOp)1, STARTMERGE, SETBIT, (ackOp)6, // skip over first bit as we know its a zero V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, ITCB, // verify merged byte and callback CALLFAIL }; // returns consist id or -1 on failure const ackOp FLASH LOCO_READ_CONSIST_PROG[] = { BASELINE, // first check cv20 for extended addressing SETCV, (ackOp)20, // CV 19 is extended SETBYTE, (ackOp)0, VB, WACK, ITSKIP, // skip past extended section if cv20 is zero // read cv20 and 19 and merge STARTMERGE, // Setup to read cv 20 V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, NAKSKIP, // bad read of cv20, assume its 0 BAD20SKIP, // detect invalid cv20 value and ignore STASHLOCOID, // keep cv 20 until we have cv19 as well. SETCV, (ackOp)19, STARTMERGE, // Setup to read cv 19 V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, NAKFAIL, // cant recover if cv 19 unreadable COMBINE1920, // Combile byte with stash and callback // end of advanced 20,19 check SKIPTARGET, SETCV, (ackOp)19, // CV 19 is consist setting SETBYTE, (ackOp)0, VB, WACK, ITC0, // rerturn 0 if cv19 is zero (no consist) SETBYTE, (ackOp)128, VB, WACK, ITC0, // return 0 if cv19 is 128 (no consist, direction bit set) STARTMERGE, // Setup to read cv 19 V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, V0, WACK, MERGE, VB, WACK, ITCB7, // return 7 bits only, No_ACK means CV19 not supported so ignore it CALLFAIL // return -1 if cv19 wont verify }; const ackOp FLASH SHORT_LOCO_ID_PROG[] = { BASELINE, // Clear consist CV 19,20 SETCV,(ackOp)20, SETBYTE, (ackOp)0, WB,WACK, // ignore dedcoder without cv20 support SETCV,(ackOp)19, SETBYTE, (ackOp)0, WB,WACK, // ignore dedcoder without cv19 support // Turn off long address flag SETCV,(ackOp)29, SETBIT,(ackOp)5, W0,WACK, V0,WACK,NAKFAIL, SETCV, (ackOp)1, SETBYTEL, // low byte of word WB,WACK,ITC1, // If ACK, we are done - callback(1) means Ok VB,WACK,ITC1, // Some decoders do not ack and need verify CALLFAIL }; // for CONSIST_ID_PROG the 20,19 values are already calculated const ackOp FLASH CONSIST_ID_PROG[] = { BASELINE, SETCV,(ackOp)20, SETBYTEH, // high byte to CV 20 WB,WACK,ITSKIP, FAIL_IF_NONZERO_NAK, // fail if writing long address to decoder that cant support it SKIPTARGET, SETCV,(ackOp)19, SETBYTEL, // low byte of word WB,WACK,ITC1, // If ACK, we are done - callback(1) means Ok VB,WACK,ITC1, // Some decoders do not ack and need verify CALLFAIL }; const ackOp FLASH LONG_LOCO_ID_PROG[] = { BASELINE, // Clear consist CV 19,20 SETCV,(ackOp)20, SETBYTE, (ackOp)0, WB,WACK, // ignore dedcoder without cv20 support SETCV,(ackOp)19, SETBYTE, (ackOp)0, WB,WACK, // ignore decoder without cv19 support // Turn on long address flag cv29 bit 5 SETCV,(ackOp)29, SETBIT,(ackOp)5, W1,WACK, V1,WACK,NAKFAIL, // Store high byte of address in cv 17 SETCV, (ackOp)17, SETBYTEH, // high byte of word WB,WACK, // do write ITSKIP, // if ACK, jump to SKIPTARGET VB,WACK, // try verify instead ITSKIP, // if ACK, jump to SKIPTARGET CALLFAIL, // if still here, fail SKIPTARGET, // store SETCV, (ackOp)18, SETBYTEL, // low byte of word WB,WACK,ITC1, // If ACK, we are done - callback(1) means Ok VB,WACK,ITC1, // Some decoders do not ack and need verify CALLFAIL }; void DCC::writeCVByte(int16_t cv, byte byteValue, ACK_CALLBACK callback) { DCCACK::Setup(cv, byteValue, WRITE_BYTE_PROG, callback); } void DCC::writeCVBit(int16_t cv, byte bitNum, bool bitValue, ACK_CALLBACK callback) { if (bitNum >= 8) callback(-1); else DCCACK::Setup(cv, bitNum, bitValue?WRITE_BIT1_PROG:WRITE_BIT0_PROG, callback); } void DCC::verifyCVByte(int16_t cv, byte byteValue, ACK_CALLBACK callback) { DCCACK::Setup(cv, byteValue, VERIFY_BYTE_PROG, callback); } void DCC::verifyCVBit(int16_t cv, byte bitNum, bool bitValue, ACK_CALLBACK callback) { if (bitNum >= 8) callback(-1); else DCCACK::Setup(cv, bitNum, bitValue?VERIFY_BIT1_PROG:VERIFY_BIT0_PROG, callback); } void DCC::readCVBit(int16_t cv, byte bitNum, ACK_CALLBACK callback) { if (bitNum >= 8) callback(-1); else DCCACK::Setup(cv, bitNum,READ_BIT_PROG, callback); } void DCC::readCV(int16_t cv, ACK_CALLBACK callback) { DCCACK::Setup(cv, 0,READ_CV_PROG, callback); } void DCC::getDriveawayLocoId(ACK_CALLBACK callback) { DCCACK::Setup(0,0, LOCO_DRIVEAWAY_PROG, callback); } void DCC::getLocoId(ACK_CALLBACK callback) { DCCACK::Setup(0,0, LOCO_READ_ID_PROG, callback); } void DCC::getConsistId(ACK_CALLBACK callback) { DCCACK::Setup(0,0, LOCO_READ_CONSIST_PROG, callback); } void DCC::setLocoId(int id,ACK_CALLBACK callback) { if (id<1 || id>10239) { //0x27FF according to standard callback(-1); return; } if (id<=HIGHEST_SHORT_ADDR) DCCACK::Setup(id, SHORT_LOCO_ID_PROG, callback); else DCCACK::Setup(id | 0xc000,LONG_LOCO_ID_PROG, callback); } void DCC::setConsistId(int id,bool reverse,ACK_CALLBACK callback) { if (id<0 || id>10239) { //0x27FF according to standard callback(-1); return; } byte cv20; byte cv19; if (id<=HIGHEST_SHORT_ADDR) { cv19=id; cv20=0; } else { cv20=id/100; cv19=id%100; } if (reverse) cv19|=0x80; DCCACK::Setup((cv20<<8)|cv19, CONSIST_ID_PROG, callback); } void DCC::forgetLoco(int cab) { // removes any speed reminders for this loco auto slot=LocoSlot::getSlot(cab, false); if (slot) { setThrottleDCC(slot,1); // ESTOP this loco if still on track if (nextLocoReminder==slot) nextLocoReminder=slot->getNext(); // move on if we are about to forget this one if (slot->isConsistLead() || slot->isConsistFollower()) DCCConsist::deleteAnyConsist(cab); // unchain any consist slot->forget(); // no longer used but not end of world CommandDistributor::broadcastForgetLoco(cab); } } void DCC::forgetAllLocos() { // removes all speed reminders setThrottleDCC(nullptr,1); // ESTOP all locos still on track SLOTLOOP { CommandDistributor::broadcastForgetLoco(slot->getLoco()); } LocoSlot::forgetAll(); // will effectively forget all consist chains nextLocoReminder=nullptr; } byte DCC::loopStatus=0; void DCC::loop() { TrackManager::loop(); // power overload checks if (DCCWaveform::mainTrack.isReminderWindowOpen()) { // Now is a good time to choose a packet to be sent // Either highest priority from the queues or a reminder if (!DCCQueue::scheduleNext(false)) { // none pending, issueReminders(); DCCQueue::scheduleNext(true); // send any pending and force an idle if none } } } void DCC::issueReminders() { // note, chainModified is set whenever a loco is added or removed // so we dont accidentally follow a stale pointer. if (LocoSlot::chainModified || nextLocoReminder==nullptr) { LocoSlot::chainModified=false; nextLocoReminder=LocoSlot::getFirst(); // start at the beginning if (nextLocoReminder==nullptr) return; // no locos at all // we have reached the end of the table, so we can move on to // the next loop state and start from the top. // There are 0-9 loop states.. speed,f1,speed,f2,speed,f3,speed,f4,speed,f5 loopStatus++; if (loopStatus>9) loopStatus=0; // reset to 0 } for (auto slot=nextLocoReminder;slot;slot=slot->getNext()) { if (issueReminder(slot)) { nextLocoReminder=slot->getNext(); // remember next one to check return; // reminder sent, exit } } // if we get to her, we have reached the end of the table. // The next call will move on to restart nextLocoReminder=nullptr; } int16_t normalize(byte speed) { if (speed & 0x80) return speed & 0x7F; return 0-1-speed; } byte dccalize(int16_t speed) { if (speed>127) return 0xFF; // 127 forward if (speed<-127) return 0x7F; // 127 reverse if (speed >=0) return speed | 0x80; // negative speeds... -1==dcc 0, -2==dcc 1 return (int16_t)-1 - speed; } bool DCC::issueReminder(LocoSlot * slot) { unsigned long functions=slot->getFunctions(); int loco=slot->getLoco(); byte flags=slot->getGroupFlags(); switch (loopStatus) { case 0: case 2: case 4: case 6: case 8: { // dont remind consist followers here if (slot->isConsistFollower()) break; // calculate any momentum change going on auto sc=slot->getSpeedCode(); if (slot->getTargetSpeed() != sc) { // calculate new speed code auto now=millis(); int16_t delay=now-slot->getMomentumBase(); auto millisPerNotch=MOMENTUM_FACTOR * (int16_t)getMomentum(slot); // allow for momentum change to 0 while accelerating/slowing auto ticks=(millisPerNotch>0)?(delay/millisPerNotch):500; if (ticks>0) { auto current=normalize(sc); // -128..+127 auto target=normalize(slot->getTargetSpeed()); // DIAG(F("Momentum l=%d ti=%d sc=%d c=%d t=%d"),loco,ticks,sc,current,target); if (currenttarget) current=target; } else { // slow current-=ticks; if (currentsetSpeedCode(sc); if (!estopIsLocked) TrackManager::setDCSignal(loco,sc); // in case this is a dcc track on this addr slot->setMomentumBase(now); } } // DIAG(F("Reminder %d speed %d"),loco,slot->speedCode); setThrottle2(slot, sc); // includes consist followers } return true; // reminder sent case 1: // remind function group 1 (F0-F4) if (flags & FN_GROUP_1) { setFunctionInternal(loco,1,0, 128 | ((functions>>1)& 0x0F) | ((functions & 0x01)<<4)); // 100D DDDD return true; // reminder sent } break; case 3: // remind function group 2 F5-F8 if (flags & FN_GROUP_2) { setFunctionInternal(loco,2,0, 176 | ((functions>>5)& 0x0F)); // 1011 DDDD return true; // reminder sent } break; case 5: // remind function group 3 F9-F12 if (flags & FN_GROUP_3) { setFunctionInternal(loco,3,0, 160 | ((functions>>9)& 0x0F)); // 1010 DDDD return true; // reminder sent } break; case 7: // remind function group 4 F13-F20 if (flags & FN_GROUP_4) { setFunctionInternal(loco,4,222, ((functions>>13)& 0xFF)); return true; } break; case 9: // remind function group 5 F21-F28 if (flags & FN_GROUP_5) { setFunctionInternal(loco,5,223, ((functions>>21)& 0xFF)); return true; // reminder sent } break; } return false; // no reminder sent } ///// Private helper functions below here ///////////////////// byte DCC::cv1(byte opcode, int cv) { cv--; return (highByte(cv) & (byte)0x03) | opcode; } byte DCC::cv2(int cv) { cv--; return lowByte(cv); } bool DCC::setMomentum(int locoId,int16_t accelerating, int16_t decelerating) { if (locoId<0) return false; if (locoId==0) { if (accelerating<0 || decelerating<0) return false; defaultMomentumA=accelerating/MOMENTUM_FACTOR; defaultMomentumD=decelerating/MOMENTUM_FACTOR; return true; } // -1 is ok and means this loco should use the default. if (accelerating<-1 || decelerating<-1) return false; if (accelerating/MOMENTUM_FACTOR >= MOMENTUM_USE_DEFAULT || decelerating/MOMENTUM_FACTOR >= MOMENTUM_USE_DEFAULT) return false; // Values stored are 255=MOMENTUM_USE_DEFAULT, or millis/MOMENTUM_FACTOR. // This is to keep the values in a byte rather than int16 // thus saving 2 bytes RAM per loco slot. auto slot=LocoSlot::getSlot(locoId,true); if (!slot) return false; // speed table full, can not do anything slot->setMomentumA((accelerating<0)? MOMENTUM_USE_DEFAULT: (accelerating/MOMENTUM_FACTOR)); slot->setMomentumD((decelerating<0)? MOMENTUM_USE_DEFAULT: (decelerating/MOMENTUM_FACTOR)); return true; } // ESTOP functions: // estopAll() - estop all locos (broadcast dcc) and set their reminders // to speed 0 with their current direction preserved. // Throttles will be told, but can immediately start driving again. // estopLock(true) - estop all locos (broadcast dcc) and lock the estop state. // While locked, no loco can be moved because any throttle packets will // be blocked at the DCC/DC level and replaced by the estop broadcast packet. // Reminders are unchanged so retain the original speed/direction ready for the restart. // Throttles will show original speed and can be changed to affect the speed that // will be used when the estop is unlocked. // estopLock(false) - unlocks the estop state and all locos will resume their // previous (or changed since locking) speeds as the reminder loop continues. void DCC::estopAll() { setThrottleDCC(nullptr,1); // estop all locos TrackManager::setDCSignal(0,1); // remind stop/estop but dont change direction for (auto slot=LocoSlot::getFirst();slot;slot=slot->getNext()) { byte newspeed=(slot->getTargetSpeed() & 0x80) | 0x01; slot->setSpeedCode(newspeed); slot->setTargetSpeed(newspeed); CommandDistributor::broadcastLoco(slot); } } bool DCC::estopIsLocked=false; bool DCC::isEstopLocked() { return estopIsLocked; } void DCC::estopLock( bool lock) { // see notes above about estop functions. if (estopIsLocked==lock) return; // no change estopIsLocked=lock; if (lock) { setThrottleDCC(nullptr, 1); // broadcast estop to DCC TrackManager::setDCSignal(0, 1); // stop DC signal on all tracks } CommandDistributor::broadcastEstopLock(estopIsLocked); // tell throttle users } LocoSlot * DCC::nextLocoReminder = nullptr; void DCC::displayCabList(Print * stream) { LocoSlot::dumpTable(stream); StringFormatter::send(stream,F("<* Default momentum=%d/%d *>\n"), DCC::defaultMomentumA,DCC::defaultMomentumD); } ================================================ FILE: DCC.h ================================================ /* * © 2021 Mike S * © 2021 Fred Decker * © 2021 Herb Morton * © 2020-2021 Harald Barth * © 2020-2025 Chris Harlow * All rights reserved. * * This file is part of DCC-EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef DCC_h #define DCC_h #include #include "MotorDriver.h" #include "MotorDrivers.h" #include "FSH.h" #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" #include "LocoSlot.h" const uint16_t LONG_ADDR_MARKER = 0x4000; class DCC { public: static inline void setShieldName(const FSH * motorShieldName) { shieldName=(FSH *)motorShieldName; }; static void begin(); static void loop(); // Public DCC API functions static bool setThrottle(uint16_t cab, uint8_t tSpeed, bool tDirection); static void estopAll(); static void estopLock(bool lock); static bool isEstopLocked(); static int8_t getThrottleSpeed(int cab); static uint8_t getThrottleSpeedByte(int cab); static uint8_t getLocoSpeedByte(int cab); // may lag throttle static uint8_t getThrottleFrequency(int cab); static bool getThrottleDirection(int cab); static void writeCVByteMain(int cab, int cv, byte bValue); static void readCVByteMain(int cab, int cv, ACK_CALLBACK callback); static void writeCVBitMain(int cab, int cv, byte bNum, bool bValue); static void setFunction(int cab, byte fByte, byte eByte); static bool setFn(int cab, int16_t functionNumber, bool on); static void changeFn(int cab, int16_t functionNumber); static int8_t getFn(int cab, int16_t functionNumber); static uint32_t getFunctionMap(int cab); static void setDCFreq(int cab,byte freq); static void updateGroupflags(LocoSlot * slot , int16_t functionNumber); static void setAccessory(int address, byte port, bool gate, byte onoff = 2); static bool setExtendedAccessory(int16_t address, int16_t value, byte repeats=3); static bool writeTextPacket(byte *b, int nBytes); // 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 static void writeCVByte(int16_t cv, byte byteValue, ACK_CALLBACK callback); static void writeCVBit(int16_t cv, byte bitNum, bool bitValue, ACK_CALLBACK callback); static void verifyCVByte(int16_t cv, byte byteValue, ACK_CALLBACK callback); static void verifyCVBit(int16_t cv, byte bitNum, bool bitValue, ACK_CALLBACK callback); static bool setTime(uint16_t minutes,uint8_t speed, bool suddenChange); static void getDriveawayLocoId(ACK_CALLBACK callback); static void getLocoId(ACK_CALLBACK callback); static void getConsistId(ACK_CALLBACK callback); static void setLocoId(int id,ACK_CALLBACK callback); static void setConsistId(int id,bool reverse,ACK_CALLBACK callback); // Enhanced API functions static void forgetLoco(int cab); // removes any speed reminders for this loco static void forgetAllLocos(); // removes all speed reminders static void saveSpeed(int cab); // saves speed for later restore static void restoreSpeed(int cab); // restores saved speed static void displayCabList(Print *stream); static FSH *getMotorShieldName(); static inline void setGlobalSpeedsteps(byte s) { globalSpeedsteps = s; }; static inline byte getGlobalSpeedsteps() { return globalSpeedsteps; }; static const int16_t MOMENTUM_FACTOR=7; static bool linearAcceleration; static byte cv1(byte opcode, int cv); static byte cv2(int cv); static bool setMomentum(int locoId,int16_t accelerating, int16_t decelerating); static byte getMomentum(LocoSlot * slot); private: static byte loopStatus; static byte defaultMomentumA; // Accelerating static byte defaultMomentumD; // Accelerating static void setThrottle2(LocoSlot * slot, uint8_t speedCode); static void setThrottleDCC(LocoSlot * slot, uint8_t speedCode); static void setFunctionInternal(int cab, byte group, byte fByte, byte eByte); static bool issueReminder(LocoSlot * slot); static LocoSlot * nextLocoReminder; static FSH *shieldName; static byte globalSpeedsteps; static bool estopIsLocked; static void issueReminders(); static void callback(int value); // NMRA codes # static const byte SET_SPEED = 0x3f; static const byte WRITE_BYTE_MAIN = 0xEC; static const byte READ_BYTE_MAIN = 0xE4; static const byte WRITE_BIT_MAIN = 0xE8; 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; }; #endif ================================================ FILE: DCCACK.cpp ================================================ /* * © 2021 M Steve Todd * © 2021 Mike S * © 2021 Fred Decker * © 2020-2025 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 . */ #include "DCCACK.h" #include "DIAG.h" #include "DCC.h" #include "DCCWaveform.h" #include "TrackManager.h" unsigned long DCCACK::minAckPulseDuration = 2000; // micros unsigned long DCCACK::maxAckPulseDuration = 20000; // micros MotorDriver * DCCACK::progDriver=NULL; ackOp const * DCCACK::ackManagerProg; ackOp const * DCCACK::ackManagerProgStart; byte DCCACK::ackManagerByte; byte DCCACK::ackManagerByteVerify; byte DCCACK::ackManagerStash; int DCCACK::ackManagerWord; byte DCCACK::ackManagerRetry; byte DCCACK::ackRetry = 2; int16_t DCCACK::ackRetrySum; int16_t DCCACK::ackRetryPSum; int DCCACK::ackManagerCv; byte DCCACK::ackManagerBitNum; bool DCCACK::ackReceived; bool DCCACK::ackManagerRejoin; volatile uint8_t DCCACK::numAckGaps=0; volatile uint8_t DCCACK::numAckSamples=0; uint8_t DCCACK::trailingEdgeCounter=0; unsigned long DCCACK::ackPulseDuration; // micros unsigned long DCCACK::ackPulseStart; // micros volatile bool DCCACK::ackDetected; unsigned long DCCACK::ackCheckStart; // millis volatile bool DCCACK::ackPending; bool DCCACK::autoPowerOff; int DCCACK::ackThreshold; int DCCACK::ackLimitmA = 50; int DCCACK::ackMaxCurrent; unsigned int DCCACK::ackCheckDuration; // millis CALLBACK_STATE DCCACK::callbackState=READY; ACK_CALLBACK DCCACK::ackManagerCallback; void DCCACK::Setup(int cv, byte byteValueOrBitnum, ackOp const program[], ACK_CALLBACK callback) { // On ESP32 the joined track is hidden from sight (it has type MAIN) // and because of that we need first check if track was joined and // then unjoin if necessary. This requires that the joined flag is // cleared when the prog track is removed. ackManagerRejoin=TrackManager::isJoined(); //DIAG(F("Joined is %d"), ackManagerRejoin); if (ackManagerRejoin) { // Change from JOIN must zero resets packet. TrackManager::setJoin(false); DCCWaveform::progTrack.clearResets(); } progDriver=TrackManager::getProgDriver(); //DIAG(F("Progdriver is %d"), progDriver); if (progDriver==NULL) { if (ackManagerRejoin) { DIAG(F("Joined but no Prog track")); TrackManager::setJoin(false); } callback(-3); // we dont have a prog track! return; } if (!progDriver->canMeasureCurrent()) { TrackManager::setJoin(ackManagerRejoin); callback(-2); // our prog track cant measure current return; } autoPowerOff=false; if (progDriver->getPower() == POWERMODE::OFF) { autoPowerOff=true; // power off afterwards if (Diag::ACK) DIAG(F("Auto Prog power on")); progDriver->setPower(POWERMODE::ON); /* TODO !!! in MotorDriver surely! if (MotorDriver::commonFaultPin) DCCWaveform::mainTrack.setPowerMode(POWERMODE::ON); DCCWaveform::progTrack.clearResets(); **/ } ackManagerCv = cv; ackManagerProg = program; ackManagerProgStart = program; ackManagerRetry = ackRetry; ackManagerByte = byteValueOrBitnum; ackManagerByteVerify = byteValueOrBitnum; ackManagerBitNum=byteValueOrBitnum; ackManagerCallback = callback; } void DCCACK::Setup(int wordval, ackOp const program[], ACK_CALLBACK callback) { ackManagerWord=wordval; Setup(0, 0, program, callback); } const byte RESET_MIN=8; // tuning of reset counter before sending message // checkRessets return true if the caller should yield back to loop and try later. bool DCCACK::checkResets(uint8_t numResets) { return DCCWaveform::progTrack.getResets() < numResets; } // Operations applicable to PROG track ONLY. // (yes I know I could have subclassed the main track but...) void DCCACK::setAckBaseline() { int baseline=progDriver->getCurrentRaw(); ackThreshold= baseline + progDriver->mA2raw(ackLimitmA); if (Diag::ACK) DIAG(F("ACK baseline=%d/%dmA Threshold=%d/%dmA Duration between %lus and %lus"), baseline,progDriver->raw2mA(baseline), ackThreshold,progDriver->raw2mA(ackThreshold), minAckPulseDuration, maxAckPulseDuration); } void DCCACK::setAckPending() { ackMaxCurrent=0; ackPulseStart=0; ackPulseDuration=0; ackDetected=false; ackCheckStart=millis(); numAckSamples=0; numAckGaps=0; ackPending=true; // interrupt routines will now take note } byte DCCACK::getAck() { if (ackPending) return (2); // still waiting if (Diag::ACK) DIAG(F("%S after %dmS max=%d/%dmA pulse=%luS samples=%d gaps=%d"),ackDetected?F("ACK"):F("NO-ACK"), ackCheckDuration, ackMaxCurrent,progDriver->raw2mA(ackMaxCurrent), ackPulseDuration, numAckSamples, numAckGaps); if (ackDetected) return (1); // Yes we had an ack return(0); // pending set off but not detected means no ACK. } #ifndef DISABLE_PROG void DCCACK::loop() { while (ackManagerProg) { byte opcode=GETFLASH(ackManagerProg); // breaks from this switch will step to next prog entry // returns from this switch will stay on same entry // (typically waiting for a reset counter or ACK waiting, or when all finished.) switch (opcode) { case BASELINE: if (progDriver->getPower()==POWERMODE::OVERLOAD) return; if (checkResets(autoPowerOff || ackManagerRejoin ? 20 : 3)) return; setAckBaseline(); callbackState=AFTER_READ; break; case W0: // write 0 bit case W1: // write 1 bit { if (checkResets(RESET_MIN)) return; if (Diag::ACK) DIAG(F("W%d cv=%d bit=%d"),opcode==W1, ackManagerCv,ackManagerBitNum); byte instruction = WRITE_BIT | (opcode==W1 ? BIT_ON : BIT_OFF) | ackManagerBitNum; byte message[] = {DCC::cv1(BIT_MANIPULATE, ackManagerCv), DCC::cv2(ackManagerCv), instruction }; DCCWaveform::progTrack.schedulePacket(message, sizeof(message), PROG_REPEATS); setAckPending(); callbackState=AFTER_WRITE; } break; case WB: // write byte { if (checkResets( RESET_MIN)) return; if (Diag::ACK) DIAG(F("WB cv=%d value=%d"),ackManagerCv,ackManagerByte); byte message[] = {DCC::cv1(WRITE_BYTE, ackManagerCv), DCC::cv2(ackManagerCv), ackManagerByte}; DCCWaveform::progTrack.schedulePacket(message, sizeof(message), PROG_REPEATS); setAckPending(); callbackState=AFTER_WRITE; } break; case VB: // Issue validate Byte packet { if (checkResets( RESET_MIN)) return; if (Diag::ACK) DIAG(F("VB cv=%d value=%d"),ackManagerCv,ackManagerByte); byte message[] = { DCC::cv1(VERIFY_BYTE, ackManagerCv), DCC::cv2(ackManagerCv), ackManagerByte}; DCCWaveform::progTrack.schedulePacket(message, sizeof(message), PROG_REPEATS); setAckPending(); } break; case V0: case V1: // Issue validate bit=0 or bit=1 packet { if (checkResets(RESET_MIN)) return; if (Diag::ACK) DIAG(F("V%d cv=%d bit=%d"),opcode==V1, ackManagerCv,ackManagerBitNum); byte instruction = VERIFY_BIT | (opcode==V0?BIT_OFF:BIT_ON) | ackManagerBitNum; byte message[] = {DCC::cv1(BIT_MANIPULATE, ackManagerCv), DCC::cv2(ackManagerCv), instruction }; DCCWaveform::progTrack.schedulePacket(message, sizeof(message), PROG_REPEATS); setAckPending(); } break; case WACK: // wait for ack (or absence of ack) { byte ackState=2; // keep polling ackState=getAck(); if (ackState==2) return; // keep polling ackReceived=ackState==1; break; // we have a genuine ACK result } case ITC0: case ITC1: // If True Callback(0 or 1) (if prevous WACK got an ACK) if (ackReceived) { callback(opcode==ITC0?0:1); return; } break; case ITCB: // If True callback(byte) if (ackReceived) { callback(ackManagerByte); return; } break; case ITCBV: // If True callback(byte) - Verify if (ackReceived) { if (ackManagerByte == ackManagerByteVerify) { ackRetrySum ++; LCD(1, F("v %d %d Sum=%d"), ackManagerCv, ackManagerByte, ackRetrySum); } callback(ackManagerByte); return; } break; case ITCB7: // If True callback(byte & 0x7F) if (ackReceived) { callback(ackManagerByte & 0x7F); return; } break; case NAKFAIL: // If nack callback(-1) if (!ackReceived) { callback(-1); return; } break; case CALLFAIL: // callback(-1) callback(-1); return; case BIV: // ackManagerByte initial value ackManagerByte = ackManagerByteVerify; break; case STARTMERGE: ackManagerBitNum=7; ackManagerByte=0; break; case MERGE: // Merge previous Validate zero wack response with byte value and update bit number (use for reading CV bytes) ackManagerByte <<= 1; // ackReceived means bit is zero. if (!ackReceived) ackManagerByte |= 1; ackManagerBitNum--; break; case SETBIT: ackManagerProg++; ackManagerBitNum=GETFLASH(ackManagerProg); break; case SETCV: ackManagerProg++; ackManagerCv=GETFLASH(ackManagerProg); break; case SETBYTE: ackManagerProg++; ackManagerByte=GETFLASH(ackManagerProg); break; case SETBYTEH: ackManagerByte=highByte(ackManagerWord); break; case SETBYTEL: ackManagerByte=lowByte(ackManagerWord); break; case STASHLOCOID: ackManagerStash=ackManagerByte; // stash value from CV17 break; case COMBINELOCOID: // ackManagerStash is cv17, ackManagerByte is CV 18 callback( LONG_ADDR_MARKER | ( ackManagerByte + ((ackManagerStash - 192) << 8))); return; case COMBINE1920: // ackManagerStash is cv20, ackManagerByte is CV 19 // This will not be called if cv20==0 ackManagerByte &= 0x7F; // ignore direction marker ackManagerByte %=100; // take last 2 decimal digits callback( ackManagerStash*100+ackManagerByte); return; case ITSKIP: if (!ackReceived) break; // SKIP opcodes until SKIPTARGET found while (opcode!=SKIPTARGET) { ackManagerProg++; opcode=GETFLASH(ackManagerProg); } break; case NAKSKIP: if (ackReceived) break; // SKIP opcodes until SKIPTARGET found while (opcode!=SKIPTARGET) { ackManagerProg++; opcode=GETFLASH(ackManagerProg); } break; case BAD20SKIP: if (ackManagerByte > 120) { // skip to SKIPTARGET if cv20 is >120 (some decoders respond with 255) if (Diag::ACK) DIAG(F("XX cv20=%d "),ackManagerByte); while (opcode!=SKIPTARGET) { ackManagerProg++; opcode=GETFLASH(ackManagerProg); } } break; case FAIL_IF_NONZERO_NAK: // fail if writing long address to decoder that cant support it if (ackManagerByte==0) break; callback(-4); return; case SKIPTARGET: break; default: DIAG(F("ackOp %d FAULT"),opcode); callback( -1); return; } // end of switch ackManagerProg++; } } void DCCACK::callback(int value) { // check for automatic retry if (value == -1 && ackManagerRetry > 0) { ackRetrySum ++; LCD(0, F("Retry %d %d Sum=%d"), ackManagerCv, ackManagerRetry, ackRetrySum); ackManagerRetry --; ackManagerProg = ackManagerProgStart; return; } static unsigned long callbackStart; // We are about to leave programming mode // Rule 1: If we have written to a decoder we must maintain power for 100mS // Rule 2: If we are re-joining the main track we must power off for 30mS const FSH *off30ms = F("OFF 30mS"); switch (callbackState) { case AFTER_READ: if (ackManagerRejoin && !autoPowerOff) { progDriver->setPower(POWERMODE::OFF); callbackStart=millis(); callbackState=WAITING_30; if (Diag::ACK) DIAG(off30ms); } 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(off30ms); } break; case WAITING_30: // waiting for 30mS with power off if (millis()-callbackStart < 30) break; //power has been off for 30mS progDriver->setPower(POWERMODE::ON); callbackState=READY; break; case READY: // ready after read, or write after power delay and off period. // power off if we powered it on if (autoPowerOff) { if (Diag::ACK) DIAG(F("Auto Prog power off")); progDriver->setPower(POWERMODE::OFF); /* TODO if (MotorDriver::commonFaultPin) DCCWaveform::mainTrack.setPowerMode(POWERMODE::OFF); **/ } // Restore <1 JOIN> to state before BASELINE if (ackManagerRejoin) { TrackManager::setJoin(true); if (Diag::ACK) DIAG(F("Auto JOIN")); } ackManagerProg=NULL; // no more steps to execute if (Diag::ACK) DIAG(F("Callback(%d)"),value); (ackManagerCallback)( value); } } #endif void DCCACK::checkAck(byte sentResetsSincePacket) { if (!ackPending) return; // This function operates in interrupt() time so must be fast and can't DIAG if (sentResetsSincePacket > 6) { //ACK timeout ackCheckDuration=millis()-ackCheckStart; ackPending = false; return; } int current=progDriver->getCurrentRaw(true); // true means "from interrupt" numAckSamples++; if (current > ackMaxCurrent) ackMaxCurrent=current; // An ACK is a pulse lasting between minAckPulseDuration and maxAckPulseDuration uSecs (refer @haba) if (current>ackThreshold) { if (trailingEdgeCounter > 0) { numAckGaps++; trailingEdgeCounter = 0; } if (ackPulseStart==0) ackPulseStart=micros(); // leading edge of pulse detected return; } // not in pulse if (ackPulseStart==0) return; // keep waiting for leading edge // if we reach to this point, we have // detected trailing edge of pulse if (trailingEdgeCounter == 0) { ackPulseDuration=micros()-ackPulseStart; } // but we do not trust it yet and return (which will force another // measurement) and first the third time around with low current // the ack detection will be finalized. if (trailingEdgeCounter < 2) { trailingEdgeCounter++; return; } trailingEdgeCounter = 0; if (ackPulseDuration>=minAckPulseDuration && (ackPulseDuration<=maxAckPulseDuration || maxAckPulseDuration == 0)) { 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 } ================================================ FILE: DCCACK.h ================================================ /* * © 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 . */ #ifndef DCCACK_h #define DCCACK_h #include "MotorDriver.h" typedef void (*ACK_CALLBACK)(int16_t result); enum ackOp : byte { // Program opcodes for the ack Manager BASELINE, // ensure enough resets sent before starting and obtain baseline current W0, W1, // issue write bit (0..1) packet WB, // issue write byte packet VB, // Issue validate Byte packet V0, // Issue validate bit=0 packet V1, // issue validate bit=1 packlet WACK, // wait for ack (or absence of ack) ITC1, // If True Callback(1) (if prevous WACK got an ACK) ITC0, // If True callback(0); ITCB, // If True callback(byte) ITCBV, // If True callback(byte) - end of Verify Byte ITCB7, // If True callback(byte &0x7F) NAKFAIL, // if false callback(-1) CALLFAIL, // callback(-1) BIV, // Set ackManagerByte to initial value for Verify retry STARTMERGE, // Clear bit and byte settings ready for merge pass MERGE, // Merge previous wack response with byte value and decrement bit number (use for readimng CV bytes) SETBIT, // sets bit number to next prog byte SETCV, // sets cv number to next prog byte SETBYTE, // sets current byte to next prog byte SETBYTEH, // sets current byte to word high byte SETBYTEL, // sets current byte to word low byte STASHLOCOID, // keeps current byte value for later COMBINELOCOID, // combines current value with stashed value and returns it ITSKIP, // skip to SKIPTARGET if ack true NAKSKIP, // skip to SKIPTARGET if ack false COMBINE1920, // combine cvs 19 and 20 and callback BAD20SKIP, // skip to SKIPTARGET if cv20 is >120 (some decoders respond with 255) FAIL_IF_NONZERO_NAK, // fail if writing long address to decoder that cant support it SKIPTARGET = 0xFF // jump to target }; enum CALLBACK_STATE : byte { AFTER_READ, // Start callback sequence after something was read from the decoder AFTER_WRITE, // Start callback sequence after something was written to the decoder WAITING_100, // Waiting for 100mS of stable power WAITING_30, // waiting to 30ms of power off gap. READY, // Ready to complete callback }; class DCCACK { public: static byte getAck(); //prog track only 0=NACK, 1=ACK 2=keep waiting static void checkAck(byte sentResetsSincePacket); // Interrupt time ack checker static inline void setAckLimit(int mA) { ackLimitmA = mA; } static inline void setMinAckPulseDuration(unsigned long i) { minAckPulseDuration = i; } static inline void setMaxAckPulseDuration(unsigned long i) { maxAckPulseDuration = i; } static void Setup(int cv, byte byteValueOrBitnum, ackOp const program[], ACK_CALLBACK callback); static void Setup(int wordval, ackOp const program[], ACK_CALLBACK callback); static void loop(); static bool isActive() { return ackManagerProg!=NULL;} static inline int16_t setAckRetry(byte retry) { ackRetry = retry; ackRetryPSum = ackRetrySum; ackRetrySum = 0; // reset running total return ackRetryPSum; }; private: static const byte SET_SPEED = 0x3f; static const byte WRITE_BYTE = 0x7C; static const byte VERIFY_BYTE = 0x74; static const byte BIT_MANIPULATE = 0x78; static const byte WRITE_BIT = 0xF0; static const byte VERIFY_BIT = 0xE0; static const byte BIT_ON = 0x08; static const byte BIT_OFF = 0x00; static void setAckBaseline(); static void setAckPending(); static void callback(int value); static const int PROG_REPEATS = 8; // repeats of programming commands (some decoders need at least 8 to be reliable) // ACK management (Prog track only) static void checkAck(); static bool checkResets(uint8_t numResets); static volatile bool ackPending; static volatile bool ackDetected; static int ackThreshold; static int ackLimitmA; static int ackMaxCurrent; static unsigned long ackCheckStart; // millis static unsigned int ackCheckDuration; // millis static unsigned long ackPulseDuration; // micros static unsigned long ackPulseStart; // micros static unsigned long minAckPulseDuration ; // micros static unsigned long maxAckPulseDuration ; // micros static MotorDriver* progDriver; static volatile uint8_t numAckGaps; static volatile uint8_t numAckSamples; static uint8_t trailingEdgeCounter; static ackOp const * ackManagerProg; static ackOp const * ackManagerProgStart; static byte ackManagerByte; static byte ackManagerByteVerify; static byte ackManagerStash; static int ackManagerWord; static byte ackManagerRetry; static byte ackRetry; static int16_t ackRetrySum; static int16_t ackRetryPSum; static int ackManagerCv; static byte ackManagerBitNum; static bool ackReceived; static bool ackManagerRejoin; static bool autoPowerOff; static CALLBACK_STATE callbackState; static ACK_CALLBACK ackManagerCallback; }; #endif ================================================ FILE: DCCConsist.cpp ================================================ #include "DCCConsist.h" #include "LocoSlot.h" #include "StringFormatter.h" #include "DIAG.h" bool DCCConsist::parse(Print * stream, byte params, int16_t p[]) { if (params==0) { for (auto slot=LocoSlot::getFirst();slot;slot=slot->getNext()) { if (slot->isConsistLead()) { StringFormatter::send(stream,F("<^")); for (auto cslot=slot;cslot;cslot=cslot->getConsistNext()) { StringFormatter::send(stream, cslot->isConsistReverse() ? F(" -%d") : F(" %d"), cslot->getLoco()); } StringFormatter::send(stream,F(" >\n")); } } return true; } // Detect any invalid locoids or duplicates for (byte i=0;i10239) { StringFormatter::send(stream,F("<* Invalid locoid %d *>"),p[i]); return false; } for (byte j=i+1;j"),p[i]); return false; } } } // Cross check other consists // if p[0] is a consist lead, kill its consist first auto slot=LocoSlot::getSlot(abs(p[0]),false); if (slot && slot->isConsistLead()) { DCCConsist::deleteAnyConsist(p[0]); } if (params<2) return true; // we only had to delete for (byte i=0;iisConsistLead() || slot->isConsistFollower())) { StringFormatter::send(stream,F("<* Loco %d in another consist *>"),abs(p[i])); return false; } } auto leadLoco=LocoSlot::getSlot(abs(p[0]),true); leadLoco->setConsistReverse(p[0]<0); LocoSlot * prev=leadLoco; for (byte i=1;isetConsistLead(leadLoco); slot->setConsistReverse(p[i]<0); prev->setConsistNext(slot); prev=slot; } return true; } void DCCConsist::deleteAnyConsist(int16_t locoid) { locoid=abs(locoid); // in case of (valid) negative auto slot=LocoSlot::getSlot(locoid,false); if (!slot) return; // no such loco, nothing to do if (!slot->isConsistLead()) slot=slot->getConsistLead(); if (!slot) return; // not in consist, nothing to do while(slot) { auto next=slot->getConsistNext(); slot->setConsistLead(nullptr); slot->setConsistNext(nullptr); slot->setConsistReverse(false); slot=next; } } bool DCCConsist::addLocoToConsist(uint16_t consistId,uint16_t locoId, bool revesed) { if (consistId<1 || consistId>10239) return false; if (locoId<1 || locoId>10239) return false; if (locoId==consistId) return true; // cant add lead to itself auto leadSlot=LocoSlot::getSlot(consistId,true); if (!leadSlot) return false; // no ram // back up to lead of existing consist while(leadSlot->getConsistLead()) { leadSlot=leadSlot->getConsistLead(); } // find tail of consist auto tailSlot=leadSlot; while(tailSlot->getConsistNext()) { tailSlot=tailSlot->getConsistNext(); } auto addSlot=LocoSlot::getSlot(locoId,true); if (!addSlot) return false; // no ram if (addSlot->isConsistLead() || addSlot->isConsistFollower()) { DIAG(F("Loco %d already in a consist"),locoId); return false; // already in consist } // All OK so chain in. (belt and braces prevent self reference loop) addSlot->setConsistReverse(revesed); if (addSlot!=leadSlot) addSlot->setConsistLead(leadSlot); if (tailSlot!=addSlot) tailSlot->setConsistNext(addSlot); return true; } ================================================ FILE: DCCConsist.h ================================================ #ifndef DCCConsist_h #define DCCConsist_h #include class DCCConsist { public: static bool parse(Print * stream, byte paramCount, int16_t p[]); // deteles any consist chain containing locoid static void deleteAnyConsist(int16_t locoid); //add loco anywhere in consist (may create consist) see EXRAIL. static bool addLocoToConsist(uint16_t consistId,uint16_t locoid, bool revesed); }; #endif ================================================ FILE: DCCDecoder.cpp ================================================ /* * © 2025 Harald Barth * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifdef ARDUINO_ARCH_ESP32 #include "DCCDecoder.h" #include "LocoSlot.h" #include "DCCEXParser.h" #include "DIAG.h" #include "DCC.h" bool DCCDecoder::parse(DCCPacket &p) { if (!active) return false; const byte DECODER_MOBILE = 1; const byte DECODER_ACCESSORY = 2; byte decoderType = 0; // use 0 as none byte *d = p.data(); byte *instr = 0; // will be set to point to the instruction part of the DCC packet (instr[0] to instr[n]) uint16_t addr; // will be set to decoder addr (long/shor mobile or accessory) bool locoInfoChanged = false; if (d[0] == 0B11111111) { // Idle packet return false; } // CRC verification here byte checksum = 0; for (byte n = 0; n < p.len(); n++) checksum ^= d[n]; if (checksum) { // Result should be zero, if not it's an error! if (Diag::SNIFFER) { DIAG(F("Checksum error:")); p.print(); } return false; } /* Serial.print("< "); for(int n=0; n<8; n++) { Serial.print(d[0]&(1<"); */ if (bitRead(d[0],7) == 0) { // bit7 == 0 => loco short addr decoderType = DECODER_MOBILE; instr = d+1; addr = d[0]; } else { if (bitRead(d[0],6) == 1) { // bit7 == 1 and bit6 == 1 => loco long addr decoderType = DECODER_MOBILE; instr = d+2; addr = 256 * (d[0] & 0B00111111) + d[1]; } else { // bit7 == 1 and bit 6 == 0 decoderType = DECODER_ACCESSORY; instr = d+1; addr = d[0] & 0B00111111; } } if (decoderType == DECODER_MOBILE) { switch (instr[0] & 0xE0) { case 0x20: // 001x-xxxx Extended commands if (instr[0] == 0B00111111) { // 128 speed steps if ((locoInfoChanged = updateLoco(addr, instr[1])) == true) { byte speed = instr[1] & 0B01111111; byte direction = instr[1] & 0B10000000; DCC::setThrottle(addr, speed, direction); //DIAG(F("UPDATE")); // send speed change to DCCEX here } } break; case 0x40: // 010x-xxxx 28 (or 14 step) speed we assume 28 case 0x60: // 011x-xxxx if ((locoInfoChanged = updateLoco(addr, instr[0] & 0B00111111)) == true) { byte speed = instr[0] & 0B00001111; // first only look at 4 bits if (speed > 1) { // neither stop nor emergency stop, recalculate speed speed = ((instr[0] & 0B00001111) << 1) + bitRead(instr[0], 4); // reshuffle bits speed = (speed - 3) * 9/2; } byte direction = instr[0] & 0B00100000; DCC::setThrottle(addr, speed, direction); } break; case 0x80: // 100x-xxxx Function group 1 if ((locoInfoChanged = updateFunc(addr, instr[0], 1)) == true) { byte normalized = (instr[0] << 1 & 0x1e) | (instr[0] >> 4 & 0x01); DCCEXParser::funcmap(addr, normalized, 0, 4); } break; case 0xA0: // 101x-xxxx Function group 3 and 2 { byte low, high; if (bitRead(instr[0], 4)) { low = 5; high = 8; } else { low = 9; high = 12; } if ((locoInfoChanged = updateFunc(addr, instr[0], low)) == true) { DCCEXParser::funcmap(addr, instr[0], low, high); } } break; case 0xC0: // 110x-xxxx Extended (here are functions F13 and up switch (instr[0] & 0B00011111) { case 0B00011110: // F13-F20 Function Control if ((locoInfoChanged = updateFunc(addr, instr[0], 13)) == true) { DCCEXParser::funcmap(addr, instr[1], 13, 20); } if ((locoInfoChanged = updateFunc(addr, instr[0], 17)) == true) { DCCEXParser::funcmap(addr, instr[1], 13, 20); } break; case 0B00011111: // F21-F28 Function Control if ((locoInfoChanged = updateFunc(addr, instr[1], 21)) == true) { DCCEXParser::funcmap(addr, instr[1], 21, 28); } // updateFunc handles only the 4 low bits as that is the most common case if ((locoInfoChanged = updateFunc(addr, instr[1]>>4, 25)) == true) { DCCEXParser::funcmap(addr, instr[1], 21, 28); } break; /* do that later case 0B00011000: // F29-F36 Function Control break; case 0B00011001: // F37-F44 Function Control break; case 0B00011010: // F45-F52 Function Control break; case 0B00011011: // F53-F60 Function Control break; case 0B00011100: // F61-F68 Function Control break; */ } break; case 0xE0: // 111x-xxxx Config vars break; } return locoInfoChanged; } if (decoderType == DECODER_ACCESSORY) { if (instr[0] & 0B10000000) { // Basic Accessory addr = (((~instr[0]) & 0B01110000) << 2) + addr; byte port = (instr[0] & 0B00000110) >> 1; byte activate = (instr[0] & 0B00001000) >> 3; byte coil = (instr[0] & 0B00000001); locoInfoChanged = true; //(void)addr; (void)port; (void)coil; (void)activate; //DIAG(F("HL=%d LL=%d C=%d A=%d"), addr, port, coil, activate); DCC::setAccessory(addr, port, coil, activate); } else { // Accessory Extended NMRA spec, do we need to decode this? /* addr = (addr << 5) + ((instr[0] & 0B01110000) >> 2) + ((instr[0] & 0B00000110) >> 1); */ } return locoInfoChanged; } return false; } // returns false only if loco existed but nothing was changed bool DCCDecoder::updateLoco(uint16_t loco, byte speedCode) { if (loco==0) return true; // its a broadcast // determine speed reg for this loco auto slot=LocoSlot::getSlot(loco, true); if (speedCode == slot->getSnifferSpeedCode()) { return false; // nothing changed } slot->setSnifferSpeedCode(speedCode); return true; // loco speed changed } bool DCCDecoder::updateFunc(uint16_t loco, byte func, int shift) { unsigned long previous; unsigned long newfunc; auto slot= LocoSlot::getSlot(loco, true); previous=slot->getSnifferFunctions(); newfunc=previous; if(shift == 1) { // special case for light newfunc &= ~1UL; newfunc |= ((func & 0B10000) >> 4); } newfunc &= ~(0B1111UL << shift); newfunc |= ((func & 0B1111) << shift); if (newfunc == previous) return false; // nothing changed slot->setSnifferFunctions(newfunc); return true; } #endif // ARDUINO_ARCH_ESP32 ================================================ FILE: DCCDecoder.h ================================================ /* * © 2025 Harald Barth * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifdef ARDUINO_ARCH_ESP32 #include #include "DCCPacket.h" class DCCDecoder { public: static bool parse(DCCPacket &p); static inline void onoff(bool on) {active = on;}; private: static bool active; static bool updateLoco(uint16_t loco, byte speedCode); static bool updateFunc(uint16_t loco, byte func, int shift); }; #endif // ARDUINO_ARCH_ESP32 ================================================ FILE: DCCEX.h ================================================ /* * © 2021 Fred Decker * © 2020-2021 Harald Barth * © 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 . */ // This include is intended to visually simplify the .ino for the end users. // If there were any #ifdefs required they are much better handled in here. #ifndef DCCEX_h #define DCCEX_h #include "defines.h" #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 "Display_Implementation.h" #include "LCN.h" #include "IODevice.h" #include "Turnouts.h" #include "Sensors.h" #include "Outputs.h" #include "CommandDistributor.h" #include "TrackManager.h" #include "DCCTimer.h" #include "KeywordHasher.h" #include "EXRAIL.h" #endif ================================================ FILE: DCCEXParser.cpp ================================================ /* * © 2022 Paul M Antoine * © 2021 Neil McKechnie * © 2021 Mike S * © 2021-2025 Herb Morton * © 2020-2025 Harald Barth * © 2020-2021 M Steve Todd * © 2020-2021 Fred Decker * © 2020-2025 Chris Harlow * © 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 . */ /* List of single character OPCODEs in use for reference. When determining a new OPCODE for a new feature, refer to this list as the source of truth. Once a new OPCODE is decided upon, update this list. Character, Usage /, |EX-R| interactive commands -, Remove from reminder table =, |TM| configuration !, Emergency stop @, LCD messages to/from JMRI #, Request number of supported cabs/locos; heartbeat +, WiFi AT commands ?, Reserved for future use ^, Consist commands 0, Track power off 1, Track power on a, DCC accessory control A, DCC extended accessory control b, Write CV bit on main B, Write CV bit c, Request current command C, configure the CS d, D, Diagnostic commands e, Erase EEPROM E, Store configuration in EEPROM f, Loco decoder function control (deprecated) F, Loco decoder function control g, G, h, H, Turnout state broadcast i, Server details string I, Turntable object command, control, and broadcast j, Throttle responses J, Throttle queries k, Block exit (Railcom) K, Block enter (Railcom) l, Loco speedbyte/function map broadcast L, Reserved for LCC interface (implemented in EXRAIL) m, message to throttles (broadcast output) m, set momentum M, Write DCC packet n, Reserved for SensorCam N, Reserved for Sensorcam o, Neopixel driver (see also IO_NeoPixel.h) O, Output broadcast p, Broadcast power state P, Write DCC packet q, Sensor deactivated Q, Sensor activated r, Broadcast address read on programming track R, Read CVs s, Display status S, Sensor configuration t, Cab/loco update command T, Turnout configuration/control u, Reserved for user commands U, Reserved for user commands v, V, Verify CVs w, Write CV on main W, Write CV x, X, Invalid command response y, Output Sound Y, Output broadcast z, Direct output Z, Output configuration/control */ #include "StringFormatter.h" #include "DCCEXParser.h" #include "DCC.h" #include "DCCWaveform.h" #include "Turnouts.h" #include "Outputs.h" #include "Sensors.h" #include "GITHUB_SHA.h" #include "version.h" #include "defines.h" #include "CommandDistributor.h" #include "EEStore.h" #include "DIAG.h" #include "TrackManager.h" #include "DCCTimer.h" #include "EXRAIL2.h" #include "Turntables.h" #include "version.h" #include "KeywordHasher.h" #include "CamParser.h" #include "Stash.h" #include "DCCConsist.h" #ifdef ARDUINO_ARCH_ESP32 #include "WifiESP32.h" #include "DCCDecoder.h" #endif // 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==INT16_MAX) break; \ StringFormatter::send(stream,F(" %d"),value); \ } 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. // 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. int16_t DCCEXParser::splitValues(int16_t result[MAX_COMMAND_PARAMS], byte *cmd, bool usehex) { byte state = 1; byte parameterCount = 0; int16_t runningValue = 0; byte *remainingCmd = cmd + 1; // skips the opcode bool signNegative = false; // 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') return -1; if (hot == '>') { *remainingCmd = '\0'; // terminate the cmd string with 0 instead of '>' return parameterCount; } state = 2; continue; case 2: // checking sign or quoted string #ifdef HAS_ENOUGH_MEMORY if (hot == '"') { // this inserts an extra parameter 0x7777 in front // of each string parameter as a marker that can // be checked that a string parameter follows // This clashes of course with the real value // 0x7777 which we hope is used seldom result[parameterCount] = (int16_t)0x7777; parameterCount++; result[parameterCount] = (int16_t)(remainingCmd - cmd + 1); parameterCount++; state = 4; break; } #endif signNegative = false; runningValue = 0; state = 3; if (hot != '-') continue; signNegative = true; break; case 3: // building a parameter if (hot >= '0' && hot <= '9') { runningValue = (usehex?16:10) * runningValue + (hot - '0'); break; } if (hot >= 'a' && hot <= 'z') hot=hot-'a'+'A'; // uppercase a..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 runningValue = ((runningValue << 5) + runningValue) ^ hot; break; } result[parameterCount] = runningValue * (signNegative ? -1 : 1); parameterCount++; state = 1; continue; #ifdef HAS_ENOUGH_MEMORY case 4: // skipover text if (hot == '\0') // We did run to end of buffer without finding the " return -1; if (hot == '"') { *remainingCmd = '\0'; // overwrite " in command buffer with the end-of-string state = 1; } break; #endif } remainingCmd++; } return parameterCount; } extern __attribute__((weak)) void myFilter(Print * stream, byte & opcode, byte & paramCount, int16_t p[]); FILTER_CALLBACK DCCEXParser::filterCallback = myFilter; FILTER_CALLBACK DCCEXParser::filterRMFTCallback = 0; FILTER_CALLBACK DCCEXParser::filterCamParserCallback = 0; AT_COMMAND_CALLBACK DCCEXParser::atCommandCallback = 0; // deprecated void DCCEXParser::setFilter(FILTER_CALLBACK filter) { filterCallback = filter; } void DCCEXParser::setRMFTFilter(FILTER_CALLBACK filter) { filterRMFTCallback = filter; } void DCCEXParser::setCamParserFilter(FILTER_CALLBACK filter) { filterCamParserCallback = filter; } void DCCEXParser::setAtCommandCallback(AT_COMMAND_CALLBACK callback) { atCommandCallback = callback; } // Parse an F() string void DCCEXParser::parse(const FSH * cmd) { DIAG(F("SETUP(\"%S\")"),cmd); int size=STRLEN_P((char *)cmd)+1; char buffer[size]; 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) { // This function can get stings of the form "" or "C OMM AND>" // found is true first after the leading "<" has been passed which results // in parseOne() getting c="C OMM AND>" byte *cForLater = NULL; bool found = (com[0] != '<'); for (byte *c=com; c[0] != '\0'; c++) { if (found) { cForLater = c; found=false; } if (c[0] == '<') { if (cForLater) parseOne(stream, cForLater, ringStream); found = true; } } if (cForLater) parseOne(stream, cForLater, ringStream); } void DCCEXParser::parseOne(Print *stream, byte *com, RingStream * ringStream) { #ifdef DISABLE_PROG (void)ringStream; #endif #ifndef DISABLE_EEPROM (void)EEPROM; // tell compiler not to warn this is unused #endif byte params = 0; 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 opcode = com[0]; int16_t splitnum = splitValues(p, com, opcode=='M' || opcode=='P'); if (splitnum < 0 || splitnum >= MAX_COMMAND_PARAMS) // if arguments are broken, leave but via printing goto out; // Because of check above we are now inside byte size params = splitnum; if (filterCallback) filterCallback(stream, opcode, params, p); if (filterRMFTCallback && opcode!='\0') filterRMFTCallback(stream, opcode, params, p); if (filterCamParserCallback && opcode!='\0') filterCamParserCallback(stream, opcode, params, p); // Functions return from this switch if complete, break from switch implies error to send switch (opcode) { case '\0': return; // filterCallback asked us to ignore case 't': // THROTTLE { int16_t cab; int16_t tspeed; int16_t direction; if (params==1) { // display state if (p[0]<0 || p[0]>10239) break; // beyond DCC range // send current state of this cab auto slot=LocoSlot::getSlot(p[0],false); if (slot) CommandDistributor::broadcastLoco(slot); else // send dummy state speed 0 fwd no functions. StringFormatter::send(stream,F("\n"),p[0]); return; } if (params == 4) { // // ignore register p[0] cab = p[1]; tspeed = p[2]; direction = p[3]; } else if (params == 3) { // cab = p[0]; tspeed = p[1]; direction = p[2]; } else break; // Convert DCC-EX protocol speed steps where // -1=emergency stop, 0-126 as speeds // to DCC 0=stop, 1= emergency stop, 2-127 speeds if (tspeed > 126 || tspeed < -1) break; // invalid JMRI speed code if (tspeed < 0) tspeed = 1; // emergency stop DCC speed else if (tspeed > 0) tspeed++; // map 1-126 -> 2-127 if (cab == 0 && tspeed > 1) break; // ignore broadcasts of speed>1 if (direction < 0 || direction > 1) break; // invalid direction code if (cab > 10239 || cab < 0) break; // beyond DCC range if (DCC::setThrottle(cab, tspeed, direction)) { if (params == 4) // send obsolete format T response StringFormatter::send(stream, F("\n"), p[0], p[2], p[3]); // speed change will be broadcast anyway in new format return; } else { break; // setThrottle() failed means slot table was full. } } case 'f': // FUNCTION if (parsef(stream, params, p)) return; break; case 'a': // ACCESSORY or { int address; byte subaddress; byte activep; byte onoff; if (params==2) { // address=(p[0] - 1) / 4 + 1; subaddress=(p[0] - 1) % 4; activep=1; onoff=2; // send both } else if (params==3) { // address=p[0]; subaddress=p[1]; activep=2; onoff=2; // send both } else if (params==4) { // 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] > 1) || (p[activep] < 0) // invalid activate 0|1 ) break; // Honour the configuration option (config.h) which allows the command to be reversed // Because of earlier confusion we need to do the same thing under both defines #if defined(DCC_ACCESSORY_COMMAND_REVERSE) DCC::setAccessory(address, subaddress,p[activep]==0,onoff); #else DCC::setAccessory(address, subaddress,p[activep]==1,onoff); #endif } return; case 'A': // EXTENDED ACCESSORY // Note: if this happens to match a defined EXRAIL // DCCX_SIGNAL, then EXRAIL will have intercepted // this command alrerady. if (params==2 && DCC::setExtendedAccessory(p[0],p[1])) return; break; case 'T': // TURNOUT if (parseT(stream, params, p)) return; break; #ifndef IO_NO_HAL case 'o': // Neopixel pin manipulation if (p[0]==0) break; { VPIN vpin=p[0]>0 ? p[0]:-p[0]; bool setON=p[0]>0; if (params==1) { // IODevice::write(vpin,setON); return; } if (params==2) { // IODevice::writeRange(vpin,setON,p[1]); return; } if (params==4 || params==5) { // auto count=p[4]?p[4]:1; if (p[1]<0 || p[1]>0xFF) break; if (p[2]<0 || p[2]>0xFF) break; if (p[3]<0 || p[3]>0xFF) break; // strange parameter mangling... see IO_NeoPixel.h NeoPixel::_writeAnalogue int colour_RG=(p[1]<<8) | p[2]; uint16_t colour_B=p[3]; IODevice::writeAnalogueRange(vpin,colour_RG,setON,colour_B,count); return; } } break; #endif case 'z': // direct pin manipulation if (p[0]==0) break; if (params==1) { // if (p[0]>0) IODevice::write(p[0],HIGH); else IODevice::write(-p[0],LOW); return; } if (params>=2 && params<=4) { // // unused params default to 0 IODevice::writeAnalogue(p[0],p[1],p[2],p[3]); return; } break; case 'y': // OUTPUT SOUND if (parsey(stream, params, p)) return; break; case 'Z': // OUTPUT if (parseZ(stream, params, p)) return; break; case 'S': // SENSOR if (parseS(stream, params, p)) return; break; #ifndef DISABLE_PROG case 'w': // WRITE CV on MAIN if (params != 3) break; DCC::writeCVByteMain(p[0], p[1], p[2]); return; #ifdef HAS_ENOUGH_MEMORY case 'r': // READ CV on MAIN Requires Railcom if (params != 2) break; if (!DCCWaveform::isRailcom()) break; if (!stashCallback(stream, p, ringStream)) break; DCC::readCVByteMain(p[0], p[1],callback_r); return; #endif case 'b': // WRITE CV BIT ON MAIN if (params != 4) break; DCC::writeCVBitMain(p[0], p[1], p[2], p[3]); return; #endif case 'm': // // if (params==1) { if (p[0]=="LINEAR"_hk) DCC::linearAcceleration=true; else if (p[0]=="POWER"_hk) DCC::linearAcceleration=false; else break; return; } if (params<2 || params>3) break; if (params==2) p[2]=p[1]; if (DCC::setMomentum(p[0],p[1],p[2])) return; break; case 'M': // WRITE TRANSPARENT DCC PACKET MAIN #ifndef DISABLE_PROG case 'P': // WRITE TRANSPARENT DCC PACKET PROG

<#> <-> <- cabid> EEPROM commands These commands exist for backwards JMRI compatibility. You are strongly discouraged from maintaining your configuration settings in EEPROM. Diagnostic commands <+ cmd> <+> User defined filter commands Track Management <=> <= track DCC|PROG|OFF> <= track DC|DCX cabid> Turntable interface Fast clock interface Advanced Throttle access to features ******************* EXRAIL Commands ******************* Obsolete commands/formats V command is much faster if prediction is correct. V command is much faster if prediction is correct. (use (use Diagnostic responses These are not meant to be software readable. They contain diagnostic information for programmers to identify issues. <* ... *> ================================================ FILE: Release_Notes/Exrail mods.txt ================================================ // 5.2.49 Which is a more efficient than the AT/AFTER/IF methods of handling buttons and switches, especially on MIMIC panels. ONBUTTON(vpin) handles debounce and starts a task if a button is used to short a pin to ground. for example: ONBUTTON(30) TOGGLE_TURNOUT(30) DONE ONSENSOR(vpin) handles debounce and starts a task if the pin changes. You may want to check the pin state with an IF ... Note the ONBUTTON and ONSENSOR are not generally useful for track sensors and running trains, because you dont know which train triggered the sensor. // 5.2.47 BLINK(vpin, onMs,offMs) which will start a vpin blinking until such time as it is SET, RESET or set by a signal operation such as RED, AMBER, GREEN. BLINK returns immediately, the blinking is autonomous. This means a signal that always blinks amber could be done like this: SIGNAL(30,31,32) ONAMBER(30) BLINK(31,500,500) DONE The RED or GREEN calls will turn off the amber blink automatically. Alternatively a signal that has normal AMBER and flashing AMBER could be like this: #define FLASHAMBER(signal) \ AMBER(signal) \ BLINK(signal+1,500,500) (Caution: this assumes that the amber pin is redpin+1) == FTOGGLE(function) Toggles the current loco function (see FON and FOFF) XFTOGGLE(loco,function) Toggles the function on given loco. (See XFON, XFOFF) TOGGLE_TURNOUT(id) Toggles the turnout (see CLOSE, THROW) STEALTH_GLOBAL(code) ADVANCED C++ users only. Inserts code such as static variables and functions that may be utilised by multiple STEALTH operations. // 5.2.34 - Command fopr DCC Extended Accessories. This command sends an extended accessory packet to the track, Normally used to set a signal aspect. Aspect numbers are undefined as sdtandards except for 0 which is always considered a stop. // - Exrail ASPECT(address,aspect) for above. The ASPECT command sents an aspect to a DCC accessory using the same logic as . // - EXRAIL DCCX_SIGNAL(Address,redAspect,amberAspect,greenAspect) This defines a signal (with id same as dcc address) that can be operated by the RED/AMBER/GREEN commands. In each case the command uses the signal address to refer to the signal and the aspect chosen depends on the use of the RED AMBER or GREEN command sent. Other aspects may be sent but will require the direct use of the ASPECT command. The IFRED/IFAMBER/IFGREEN and ONRED/ONAMBER/ONGREEN commands contunue to operate as for any other signal type. It is important to be aware that use of the ASPECT or commands will correctly set the IF flags and call the ON handlers if ASPECT is used to set one of the three aspects defined in the DCCX_SIGNAL command. Direct use of other aspects does not affect the signal flags. ASPECT and can be used withput defining any signal if tyhe flag management or ON event handlers are not required. // 5.2.33 - Exrail CONFIGURE_SERVO(vpin,pos1,pos2,profile) This macro offsers a more convenient way of performing the HAL call in halSetup.h In halSetup.h --- IODevice::configureServo(101,300,400,PCA9685::slow); In myAutomation.h --- CONFIGURE_SERVO(101,300,400,slow) // 5.2.32 - Railcom Cutout (Initial trial Mega2560 only) This cutout will only work on a Mega2560 with a single EX8874 motor shield configured in the normal way with the main track brake pin on pin 9. Turns on the cutout mechanism. Tirns off the cutout. (This is the default) ONLY to be used by developers used for waveform diagnostics. (In DEBUG mode the main track idle packets are replaced with reset packets, This makes it far easier to see the preambles and cutouts on a logic analyser or scope.) // 5.2.31 - Exrail JMRI_SENSOR(vpin [,count]) creates types. This Macro causes the creation of JMRI type sensors in a way that is simpler than repeating lines of commands. JMRI_SENSOR(100) is equenvelant to JMRI_SENSOR(100,16) will create type sensors for vpins 100-115. // 5.2.26 - Silently ignore overridden HAL defaults // - include HAL_IGNORE_DEFAULTS macro in EXRAIL The HAL_IGNORE_DEFAULTS command, anywhere in myAutomation.h will prevent the startup code from trying the default I2C sensors/servos. // 5.2.24 - Exrail macro asserts to catch // : duplicate/missing automation/route/sequence/call ids // : latches and reserves out of range // : speeds out of range Causes compiler time messages for EXRAIL issues that would normally only be discovered by things going wrong at run time. // 5.2.13 - EXRAIL STEALTH Permits a certain level of C++ code to be embedded as a single step in an exrail sequence. Serious engineers only. // 5.2.9 - EXRAIL STASH feature // - Added ROUTE_DISABLED macro in EXRAIL ================================================ FILE: Release_Notes/IO_Bitmap.md ================================================ Virtual Bitmap device pins. a Bitmap device pin is a software representation of a virtual hardware device that has the ability to store a 16bit value. This this is easier to manage than LATCH in EXRAIL as they can be explicitely set and tested without interfering with underlying hardware or breaching the 255 limit. Virtual pins may be set, reset and tested in the same way as any other pin. Unlike sensors and leds, these device pins are both INPUT and OUTPUT These can be used in many ways: As a simple digital flag to assist in inter-thread communication. A flag or value that can be set from commands and tested in EXRAIL.(e.g. to stop a sequence) As a counter for looping or occupancy counts such as trains passing over a multi track road crossing. As a collection of 16 digital bits that can be set, reset, toggled, masked and tested. Existing <> and exrail commands for vpins work on these pins. Virtual pin creation: HAL(Bitmap,firstpin,npins) creates 1 or more virtual pins in software. (RAM requirement approximately 2 bytes per pin) e.g. HAL(Bitmap,1000,20) creates pins 1000..1019 Simple use as flags: This uses the traditional digital pin commands SET(1013) RESET(1013) sets value 1 or 0 SET(1000,20) RESET(1000,20) sets/resets a range of pins IF(1000) tests if pin value!=0 Commands can set 1/0 values using as for any digital output. BLINK can be used to set them on/off on a time pattern. In addition, Exrail sensor comands work as if these pins were sensors ONBUTTON(1013) triggers when value changes from 0 to something. ONSENSOR(1013) triggers when value changes to or from 0. and JMRI_SENSOR(1013) report etc. Use as counters: For loop counting, counters can be incremented by BITMAP_INC(1013) and decremented by BITMAP_DEC(1013) and tested with IF/IFNOT/IFGTE etc. Counters be used to automate a multi track crossing where each train entering increments the counter and decrements it on clearing the crossing. Crossing gate automation can be started when the value changes from 0, and be stopped when the counter returns to 0. Detecting the first increment from 0 to 1 can be done with ONBUTTON(1013) and the automation can use IF(1013) or IFNOT(1013) to detect when it needs to reopen the road gates. Use as binary flag groups: Virtual pins (and others that respond to an analog read in order to provide bitmapped digital data, such as SensorCam) can be set and tested with new special EXRAIL commands IFBITMAP_ALL(vpin,mask) Bitwise ANDs the the vpin value with the mask value and is true if ALL the 1 bits in the mask are also 1 bits in the value. e.g. IFBITMAP_ALL(1013,0x0f) would be true if ALL the last 4 bits of the value are 1s. IFBITMAP_ANY(1013,0x0f) would be true if ANY of the last 4 bits are 1s. Modifying bitmap values: BITMAP_SET(voin,value) sets the value BITMAP_AND(vpin,mask) performs a bitwise AND operation. BITMAP_OR(vpin,mask) performa a bitwise OR operation BITMAP_XOR(vpin,mask) performs a bitwise EXCLUSIVE OR (which is basically a toggle) ================================================ FILE: Release_Notes/NeoPixel.md ================================================ NeoPixel support The IO_NeoPixel.h driver supports the adafruit neopixel seesaw board. It turns each pixel into an individual VPIN which can be given a colour and turned on or off using the new command or the NEOPIXEL Exrail macro. Exrail SIGNALS can also drive a single pixel signal or multiple separate pixels. 1. Defining the hardware driver: Add a driver definition in myAutomation.h for each adafruit I2C driver. HAL(neoPixel, firstVpin, numberOfPixels [, mode [, i2caddress]) Where mode is selected from the various pixel string types which have varying colour order or refresh frequency. For MOST strings this mode will be NEO_GRB but for others refer to the comments in IO_NeoPixel.h If omitted the node and i2caddress default to NEO_GRB, 0x60. HAL(NeoPixel,1000,20) This is a NeoPixel driver defaulting to I2C aqddress 0x60 for a GRB pixel string. Pixels are given vpin numbers from 1000 to 1019. HAL(NeoPixel,1020,20,NEO_GRB,0x61) This is a NeoPixel driver on i2c address 0x61 2. Setting pixels from the < > commands. By default, each pixel in the string is created as white but switched off. Each pixel has a vpin starting from the first vpin in the HAL definitions. switches pixel on (same as ) e.g. switches pixel off (same as ) e.g. (the z commands work on pixels the same as other gpio pins.) switches on/off count pixels starting at vpin. e.g Note: it IS acceptable to switch across 2 strings of pixels if they are contiguous vpin ranges. It is also interesting that this command doesnt care if the vpins are NeoPixel or any other type, so it can be used to switch a range of other pin types. sets the colour and on/off status of a pin or pins. Each colour is 0..255 e.g. sets pin 1005 to bright yellow and ON, <0 -1006 0 0 255 10> sets pins 1006 to 1015 (10 pins) to bright blue but OFF. Note: If you set a pin to a colour, you can turn it on and off without having to reset the colour every time. This is something the adafruit seesaw library can't do and is just one of several reasons why we dont use it. 3. Setting pixels from EXRAIL The new NEOPIXEL macro provides the same functionality as the command above. NEOPIXEL([-]vpin, red, green, blue [,count]) Setting pixels on or off (without colour change) can be done with SET/RESET [currently there is no set range facility but that may be added as a general exrail thing... watch this space] Because the pixels obey set/reset, the BLINK command can also be used to control blinking a pixel. 4. EXRAIL pixel signals. There are two types possible, a mast with separate fixed colour pixels for each aspect, or a mast with one multiple colour pixel for all aspects. For separate pixels, the colours should be established at startup and a normal SIGNALH macro used. AUTOSTART SIGNALH(1010,1011,1012) NEOPIXEL(1010,255,0,0) NEOPIXEL(1011,128,128,0) NEOPIXEL(1012,0,255,0) RED(1010) // force signal state otherwise all 3 lights will be on DONE For signals with 1 pixel, the NEOPIXEL_SIGNAL macro will create a signal NEOPIXEL_SIGNAL(vpin,redfx,amberfx,greenfx) ** Changed... **** The fx values above can be created by the NeoRGB macro so a bright red would be NeoRGB(255,0,0) bright green NeoRGB(0,255,0) and amber something like NeoRGB(255,100,0) NeoRGB creates a single int32_t value so it can be used in several ways as convenient. // create 1-lamp signal with NeoRGB colours NEOPIXEL_SIGNAL(1000,NeoRGB(255,0,0),NeoRGB(255,100,0),NeoRGB(0,255,0)) // Create 1-lamp signal with named colours. // This is better if you have multiple signals. // (Note: ALIAS is not suitable due to word length defaults) #define REDLAMP NeoRGB(255,0,0) #define AMBERLAMP NeoRGB(255,100,0) #define GREENLAMP NeoRGB(0,255,0) NEOPIXEL_SIGNAL(1001,REDLAMP,AMBERLAMP,GREENLAMP) // Create 1-lamp signal with web type RGB colours // (Using blue for the amber signal , just testing) NEOPIXEL_SIGNAL(1002,0xFF0000,0x0000FF,0x00FF00) ================================================ FILE: Release_Notes/Railcom.md ================================================ Railcom implementation notes, Chris Harlow Oct 2024 Railcom support is in 3 parts 1. Generation of the DCC waveform with a Railcom cutout. 2. Accessing the railcom feedback from a loco using hardware detectors 3. Utilising the feedback to do something useful. DCC Waveform Railcom cutout depends on using suitable motor shields (EX8874 primarily) as the standard Arduino shield is not suitable. (Too high resistance during cutout) The choice of track management also depends on wiring all the MAIN tracks to use the same signal and brake pins. This allows separate track power management but prevents switching a single track from MAIN to PROG or DC... Some CPUs require very specific choice of brake pins etc to match their internal timer register architecture. - MEGA.. The default shield setting for an EX8874 is suitable for Railcom on Channel A (MAIN) - ESP32 .. not yet supported. - Nucleo ... TBA Enabling the Railcom Cutout requires a `` command. This can be added to myAutomation using `PARSE("")` Code to calculate the cutout position and provide synchronization for the sampling is in `DCCWaveform.cpp` (not ESP32) and in general a global search for "railcom" will show all code changes that have been made to support this. Code to actually implement the timing of the cutout is highly cpu dependent and can be found in the various implementations of `DCCTimer.h`. At this time only `DCCTimerAVR.cpp`has implemented this. Reading Railcom data: A new HAL handler (`IO_I2CRailcom.h`) has been added to process input from a 32-block railcom collecter which operates over I2C. The collector and its readers sit between the CS and the track and collect railcom data from locos during the cutout. The Collector device removes 99.9% of the railcom traffic and returns just a summary of what has changed since the last cutout. After the cutout the HAL driver reads the Collector summary over I2C and passes the raw data to the CS logic (`Railcom.cpp`) for analysis. Each 32-block reader is described in myAutomation like `HAL(I2CRailcom,10000,32,0x08)` which will assign 32 blocks on i2c address 0x08 with vpin numbers 10000 and 10031. If you only use fewer channel in the collector, you can assign fewer pins here. (Implementation notes.. you may have multiple collectors, each one will requite a HAL line to define its i2c address and vpins to represent block numbers.) Making use of Railcom data Exrail has two additional event handlers which can capture locos entering and exiting blocks. These handlers are started with the loco information already set, so for example: ``` ONBLOCKENTER(10000) // a loco has entered block 10000 FON(0) // turn the light on FON(1) // make a lot of noise SPEED(20) // slow down DONE ONBLOCKEXIT(10000) // a loco has left block 10000 FOFF(0) // turn the light off FOFF(1) // stop the noise SPEED(50) // speed up again DONE ``` Note that the Railcom interpretation code is capable of detecting multiple locos in the same block at the same time and will create separate exrail tasks for each one. There is however one minor loophole in the block exit logic... If THREE or more locos are in the same block and ONE of them leaves, then ONBLOCKEXIT will not fire until EITHER - The leaving loco enters another railcom block OR - only ONE loco remains in the block just left. To further support block management in railcom, two additional serial commands are available `` to simulate a loco entering a block, and trigger any ONBLOCKENTER `` to simulate a loco leaving a block, and trigger and ONBLOCKEXIT Reading CV values on MAIN. Railcom allows for the facility to read loco cv values while on the main track. This is considerably faster than PROG track access but depends on the loco being in a Railcom monitored block. To read from PROG Track we use `` response is `` To read from MAIN track use `` response is `` ================================================ FILE: Release_Notes/Stash.md ================================================ # The STASH feature of exrail. STASH is used for scenarios where it is helpful to relate a loco id to where it is parked. For example a fiddle yard may have 10 tracks and it's much easier for the operator to select a train to depart by using the track number, or pressing a button relating to that track, rather than by knowing the loco id which may be difficult to see. Automated yard parking can use the stash to determine which tracks are empty without the need for block occupancy detectors. Note that a negative locoid may be stashed to indicate that the loco will operate with inverted direction. For example a loco facing backwards, with the INVERT_DRECTION state may be stashed by exrail and the invert state will be restored along with the loco id when using the PICKUP_STASH. CLEAR_ANY_STASH will clear all references to the loco regardless of direction. The following Stash commands are available: | EXRAIL command | Serial protocol | function | | -------------- | --------------- | -------- | | STASH(s) | `` | Save the current loco id in the stash array element s. | | CLEAR_STASH(s) | `` | Sets stash array element s to zero. | | CLEAR_ALL_STASH | `` | sets all stash entries to zero | | CLEAR_ANY_STASH | `` | removes current loco from all stash elements | | PICKUP_STASH(s) | N/A | sets current loco to stash element s | | IFSTASH(s) | N/A | True if stash element s is not zero | | N/A | `` | query all stashes (returns `` where loco is not zero) | N/A | `` | Query loco in stash (returns ``) ================================================ FILE: Release_Notes/TCA8418.md ================================================ ## TCA8418 ## The TCA8418 IC from Texas Instruments is a low cost and very capable GPIO and keyboard scanner. Used as a keyboard scanner, it has 8 rows of 10 columns of IO pins which allow encoding of up to 80 buttons. The IC is available on an Adafruit board with Qwiic I2C interconnect called the "Adafruit TCA8418 Keypad Matrix and GPIO Expander Breakout" and available here for the modest sum of $US6 or so: https://www.adafruit.com/product/4918 The great advantage of this IC is that the keyboard scanning is done continuously, and it has a 10-element event queue, so even if you don't get to the interrupt immediately, keypress and release events will be held for you. Since it's I2C its very easy to use with any DCC-EX command station. The TCA8418 driver presently configures the IC in the full 8x10 keyboard scanning mode, and then maps each key down/key up event to the state of a single vpin for extremely easy use from within EX-RAIL and JMRI as each key looks like an individual sensor. This is ideal for mimic panels where you may need a lot of buttons, but with this board you can use just 18 wires to handle as many as 80 buttons. By adding a simple HAL statement to myAutomation.h it creates between 1 and 80 buttons it will report back. `HAL(TCA8418, firstVpin, numPins, I2CAddress, interruptPin)` For example: `HAL(TCA8418, 300, 80, 0x34)` Creates VPINs 300-379 which you can monitor with EX-RAIL, JMRI sensors etc. With an 8x10 key event matrix, the events are numbered using the Rn row pins and Cn column pins as such: C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 ======================================== R0| 0 1 2 3 4 5 6 7 8 9 R1| 10 11 12 13 14 15 16 17 18 19 R2| 20 21 22 23 24 25 26 27 28 29 R3| 30 31 32 33 34 35 36 37 38 39 R4| 40 41 42 43 44 45 46 47 48 49 R5| 50 51 52 53 54 55 56 57 58 59 R6| 60 61 62 63 64 65 66 67 68 69 R7| 70 71 72 73 74 75 76 77 78 79 So if you start with the first pin definition being VPIN 300, R0/C0 will be 300 + 0, and R7/C9 will be 300+79 or 379. Use something like this on a multiplexor, and with up to 8 of the 8-way multiplexors you could have 64 different TCA8418 boards: `HAL(TCA8418, 400, 80, {SubBus_1, 0x34})` And if needing an Interrupt pin to speed up operations: `HAL(TCA8418, 300, 80, 0x34, 21)` Note that using an interrupt pin speeds up button press acquisition considerably (less than a millisecond vs 10-100), but even with interrupts enabled the code presently checks every 100ms in case the interrupt pin becomes disconnected. Use any available Arduino pin for interrupt monitoring. ================================================ FILE: Release_Notes/TM1638.md ================================================ ## TM1638 ## The TM1638 board provides a very cheap way of implementing 8 buttons, 8 leds and an 8 digit 7segment display in a package requiring just 5 Dupont wires (vcc, gnd + 3 GPIO pins) from the command station without soldering. This is ideal for prototyping and testing, simulating sensors and signals, displaying states etc. For a built layout, this could provide a control for things that are not particularly suited to throttle 'route' buttons, perhaps lineside automations or fiddle yard lane selection. By adding a simple HAL statement to myAutomation.h it creates 8 buttons/sensors and 8 leds. `HAL(TM1638,500,29,31,33)` Creates VPINs 500-507 And desscribes the GPIO pins used to connect the clk,dio,stb pins on the TM1638 board. Setting each of the VPINs will control the associated LED (using for example SET, RESET or BLINK in Exrail or ` from a command). Unlike most pins, you can also read the same pin number and get the button state, using Exrail IF/AT/ONBUTTON etc. For example: ` HAL(TM1638,500,29,31,33) ` All the folowing examples assume you are using VPIN 500 as the first, leftmost, led/button on the TM1638 board. `ONBUTTON(500) SET(500) // light the first led BLINK(501,500,500) // blink the second led SETLOCO(3) FWD(50) // set a loco going AT(501) STOP // press second button to stop RESET(500) RESET(501) // turn leds off DONE ` Buttons behave like any other sensor, so using `` will cause the command station to issue `` and `` messages when the first button is pressed or released. Exrail `JMRI_SENSOR(500,8)` will create ```` 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. `````` 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 `````` ````` requests info on turnout 17. e.g. response `````` or `````` (T=thrown, C=closed) or `````` indicating turnout description not given. or `````` 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. `````` Returns a list of Automations/Routes e.g. `````` Indicates route/automation ids. Information on each route needs to be obtained by `````` returns e.g. `````` for a route or `````` for an automation. or `````` 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 ``````. 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. `````` Roster Information: The `````` command requests a list of cab ids from the roster. e.g. responding `````` or for none. Each Roster entry had a name and function map obtained by: `````` reply like ``` Refer to EXRAIL ROSTER command for function map format. Obtaining throttle status. `````` Requests a deliberate update on the cab speed/functions in the same format as the cab broadcast. `````` 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 `````` Use `````` `````` Just drop the slot number `````` other than `````` `````` `````` ================================================ FILE: Release_Notes/TrackManager.md ================================================ # 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. ================================================ FILE: Release_Notes/consists.md ================================================ # Consist develeopment spec/checklist ## creating and managing - ```<^ leadId followerId [id...] >``` creates a CS consist up to (parser limit) locos with first id being lead loco. [DONE] - check each parameter is valid dcc range. [DONE] - must catch same loco in list twice [DONE] - negative loco ids in consist mean direction reversed so setting the flag in locoslot. [DONE] - lead loco could be real or virtual, we couldnt tell but functions would be sent to lead loco address.[DONE] - <^ leadid> means delete consist led by this loco - If any follower is already in another consist, error.[DONE] - all locos in consist are estopped during consist construction. - ` on existing consist lead deletes the consist chain (doesnt create a 1 loco consist :) [DONE] - ```<^>``` lists all consists [DONE] - `````` includes consist chains - consist deletion will estop all locos in consist. - Locoslots contain nextConsist, leadConsist, consistInvertedDirection [DONE] - lead loco has null leadConsist but !null nextConsist[DONE] - Throttle commands to following locos are routed to the lead. [NO] becaused its impossible to know whether the sent command has allowed for the reversal of the addressed loco or not. - Instead, throttle commands to the followers are ignored.[DONE] - Throttle commands to lead loco are reflected directly to the targetSpeed of the followers. [DONE] - Broadcast of lead loco broadcasts all followers [DONE] - Multi loco broadcast should be transmission per throttle rather then one per loco per throttle. - Following locos do NOT issue DCC speed packets.[DONE] - Lead loco throttle commands / reminders etc queue DCC packets for all locos simultaneoulsy. [DONE] - reminder loop ignores following loco speed reminders. [DONE] (Lead reminder will be sent to all follower addresses, allowing for reversed locos.) - momentum, speed limits etc will effectively come from the lead loco.[DONE] - Functions to lead loco are not mapped to followers...[DONE] (Or do we want a way of configuring this) ================================================ FILE: Release_Notes/duinoNodes.md ================================================ 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. ================================================ FILE: Release_Notes/momentum.md ================================================ New Momentum feature notes: The command station can apply momentum to throttle movements in the same way that a standards compliant DCC decoder can be set to do. This momentum can be defaulted system wide and overridden on individual locos. It does not use or alter the loco CV values and so it also works when driving DC locos. The momentum is applied regardless of the throttle type used (or even EXRAIL). Momentum is specified in mS / throttle_step. There is a new command `` where the brake value defaults to the accelerating value. For example: `` sets loco 3 to no momentum. `` sets loco 3 to 21 mS/step. `` sets loco 3 to 21 mS/step accelerating and 42 mS/step when decelerating. `` sets the default momentum to 21mS/Step for all current and future locos that have not been specifically set. `` sets loco 3 to track the default momentum value. EXRAIL A new macro `MOMENTUM(accel [, decel])` sets the momentum value of the current tasks loco ot the global default if loco=0. Note: Setting Momentum 7,14,21 etc is similar in effect to setting a decoder CV03/CV04 to 1,2,3. As an additional option, the momentum calculation is based on the difference in throttle setting and actual speed. For example, the time taken to reach speed 50 from a standing start would be less if the throttle were set to speed 100, thus increasing the acceleration. `` - acceleration is uniform up to selected throttle speed. `` - acceleration depends on difference between loco speed and selected throttle speed. ================================================ FILE: Release_Notes/release_notes_v3.0.0.md ================================================ The DCC-EX Team is pleased to release CommandStation-EX-v3.0.0 as a Production Release. This release is a major re-write of earlier versions. We've re-architected the code-base so that it can better handle new features going forward. Download the compressed files here: **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/files/5611333/CommandStation-EX.zip) [CommandStation-EX.tar.gz](https://github.com/DCC-EX/CommandStation-EX/files/5611335/CommandStation-EX.tar.gz) **Known Bugs:** - **Consisting through JMRI** - currently does not work in this release. A number of testers were able to develop a work around. If interested enter a Support Ticket. - **Wi-Fi** - works, but can be challenging to use if you want to switch between AP mode and STA station mode. - **Pololu Motor Shield** - is supported with this release, but the user may have to play around with some timings to enable programming mode due to limitation in its current sensing circuitry **Summary of the key new features added to CommandStation-EX V3.0.0:** - **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 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** - `````` command allows setting functions based on their number, not based on a code as in `````` - **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 - **Diagnostic `````` 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 managment** - slot variable in throttle/function commands are ignored and slot management is taken care of automatically. `````` command added to release locos from memory. **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) - Fred Decker - Holly Springs, North Carolina, USA (FlightRisk) - Dave Cutting - Logan, Utah, USA (Dave Cutting/ David Cutting) - M Steve Todd - - Engine Driver and JMRI Interface - Scott Catalanno - Pennsylvania - Gregor Baues - Île-de-France, France (grbba) **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 - (KCSmith) **Beta Testing / Release Management / Support** - Larry Dribin - Release Management - Keith Ledbetter - BradVan der Elst - Andrew Pye - Mike Bowers - Randy McKenzie - Roberto Bravin - Sim 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/files/5611333/CommandStation-EX.zip) [CommandStation-EX.tar.gz](https://github.com/DCC-EX/CommandStation-EX/files/5611335/CommandStation-EX.tar.gz) ================================================ FILE: Release_Notes/release_notes_v3.1.0.md ================================================ The DCC-EX Team is pleased to release CommandStation-EX-v3.1.0 as a Production Release. Release v3.1.0 is a minor release that adds additional features and fixes a number of bugs. With the number of new features, this could have easily been a major release. The team is continually 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.0.1 to v3.0.16. **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/v3.1.0-Prod/CommandStation-EX.zip) [CommandStation-EX.tar.gz](https://github.com/DCC-EX/CommandStation-EX/releases/download/v3.1.0-Prod/CommandStation-EX.tar.gz) **Known Issues** - **Wi-Fi** - works, but requires sending 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 limitation in its current sensing circuitry #### Summary of 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 - `` 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 `` 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 `` 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** - `` command allows setting functions based on their number, not based on a code as in `` - **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 `` 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 - - 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) **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) - Keith Ledbetter - BradVan der Elst - Andrew Pye - Mike Bowers - Randy McKenzie - Roberto Bravin - Sim 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/v3.1.0-Prod/CommandStation-EX.zip) [CommandStation-EX.tar.gz](https://github.com/DCC-EX/CommandStation-EX/releases/download/v3.1.0-Prod/CommandStation-EX.tar.gz) ================================================ FILE: Release_Notes/release_notes_v4.0.0.md ================================================ 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 `` 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 `` 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 `` 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 `` command and `` 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 - `` 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 `` 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 `` 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** - `` command allows setting functions based on their number, not based on a code as in `` - **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 `` 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) ================================================ FILE: Release_Notes/websocketTester.html ================================================ This is a minimalist test page for the DCCEX websocket API. It demonstrates the Websocket connection and how to send or receive websocket traffic. The connection string must be edited to address your command station correctly.

================================================ FILE: RingStream.cpp ================================================ /* * © 2020-2021 Chris Harlow * All rights reserved. * * This file is part of DCC-EX 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 . */ // NOTE: The use of a marker byte without an escape algorithm means // RingStream is unsuitable for binary data. Should binary data need to be // streamed it will be necessary to implementr an escape strategy to handle the // marker char when embedded in data. #include "RingStream.h" #include "DIAG.h" const byte FLASH_INSERT_MARKER=0xff; RingStream::RingStream( const uint16_t len) { _len=len; _buffer=new byte[len]; _pos_write=0; _pos_read=0; _buffer[0]=0; _overflow=false; _mark=0; _count=0; _flashInsert=0; } size_t RingStream::write(uint8_t b) { if (_overflow) return 0; _buffer[_pos_write] = b; ++_pos_write; if (_pos_write==_len) _pos_write=0; if (_pos_write==_pos_read) { _overflow=true; return 0; } _count++; return 1; } // Ideally, I would prefer to override the Print:print(_FlashStringHelper) function // but the library authors omitted to make this virtual. // Therefore we obveride the only other simple function that has no side effects // in order that StringFormatter can recognise a RingStream and call its // printFlash() directly. int RingStream::availableForWrite() { return THIS_IS_A_RINGSTREAM; } size_t RingStream::printFlash(const FSH * flashBuffer) { // This function does not work on a 32 bit processor where the runtime // sometimes misrepresents the pointer size in uintptr_t. // In any case its not really necessary in a 32 bit processor because // we have adequate ram. if (sizeof(void*)>2) return print(flashBuffer); // We are about to add a PROGMEM string to the buffer. // To save RAM we can insert a marker and the // progmem address into the buffer instead. // The buffer reading code must recognise this marker and // silently extract the progmem bytes. // In addition, we must make the count correct as if the // string had been embedded so that things like the wifi code // can read the expected count before reading the buffer. // Establish the actual length of the progmem string. char * flash=(char *)flashBuffer; int16_t plength=STRLEN_P(flash); if (plength==0) return 0; // just ignore empty string // Retain the buffer count as it will be modified by the marker+address insert int prevCount=_count; write(FLASH_INSERT_MARKER); // write the marker uintptr_t iFlash=reinterpret_cast(flash); // expect size match with pointer // write address bytes LSB first (size depends on CPU) for (byte f=0;f>=8; } // correct the buffer count to reflect the flash length, not the marker/addr. _count=prevCount+plength; return plength; } int RingStream::read() { if (_flashInsert) { // we are reading out of a flash string byte fb=GETFLASH(_flashInsert); _flashInsert++; if (fb) return fb; // we have a byte from the flash // flash insert complete, clear and drop through to next buffer byte _flashInsert=NULL; } if ((_pos_read==_pos_write) && !_overflow) return -1; // empty byte b=readRawByte(); if (b!=FLASH_INSERT_MARKER) return b; // Detected a flash insert if (sizeof(void*)>2) { DIAG(F("Detected invalid flash insert marker at pos %d"),_pos_read); return '?'; } // read address bytes LSB first (size depends on CPU) uintptr_t iFlash=0; for (byte f=0; f( iFlash); // and try again... so will read the first byte of the insert. return read(); } byte RingStream::readRawByte() { byte b=_buffer[_pos_read]; _pos_read++; if (_pos_read==_len) _pos_read=0; _overflow=false; return b; } int RingStream::count() { return (readRawByte()<<8) | readRawByte(); } int RingStream::freeSpace() { // allow space for client flag and length bytes if (_pos_read>_pos_write) return _pos_read-_pos_write-3; else return _len - _pos_write + _pos_read-3; } // mark start of message with client id (0...9) void RingStream::mark(uint8_t b) { //DIAG(F("RS mark client %d at %d core %d"), b, _pos_write, xPortGetCoreID()); _ringClient = b; _mark=_pos_write; write(b); // client id write((uint8_t)0); // count MSB placemarker write((uint8_t)0); // count LSB placemarker _count=0; } // peekTargetMark is used by the parser stash routines to know which client // to send a callback response to some time later. uint8_t RingStream::peekTargetMark() { return _ringClient; } void RingStream::info() { DIAG(F("Info len=%d count=%d pr=%d pw=%d m=%d"),_len, _count,_pos_read,_pos_write,_mark); } bool RingStream::commit() { _flashInsert=NULL; // prepared for first read if (_overflow) { //DIAG(F("RingStream(%d) commit(%d) OVERFLOW"),_len, _count); // just throw it away _pos_write=_mark; _overflow=false; return false; // commit failed } if (_count==0) { //DIAG(F("RS commit count=0 rewind back to %d core %d"), _mark, xPortGetCoreID()); // ignore empty response _pos_write=_mark; _ringClient = NO_CLIENT; //XXX make else clause later return true; // true=commit ok } // Go back to the _mark and inject the count 1 byte later _mark++; if (_mark==_len) _mark=0; _buffer[_mark]=highByte(_count); _mark++; if (_mark==_len) _mark=0; _buffer[_mark]=lowByte(_count); _ringClient = NO_CLIENT; return true; // commit worked } void RingStream::flush() { _pos_write=0; _pos_read=0; _buffer[0]=0; _flashInsert=NULL; // prepared for first read _ringClient = NO_CLIENT; } ================================================ FILE: RingStream.h ================================================ #ifndef RingStream_h #define RingStream_h /* * © 2020-2021 Chris Harlow * All rights reserved. * * This file is part of DCC-EX 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 . */ #include #include "FSH.h" class RingStream : public Print { public: RingStream( const uint16_t len); static const int THIS_IS_A_RINGSTREAM=777; virtual size_t write(uint8_t b); // This availableForWrite function is subverted from its original intention so that a caller // can destinguish between a normal stream and a RingStream. // The Arduino compiler does not support runtime dynamic cast to perform // an instranceOf check. // This is necessary since the Print functions are mostly not virtual so // we cant override the print(__FlashStringHelper *) function. virtual int availableForWrite() override; using Print::write; size_t printFlash(const FSH * flashBuffer); int read(); int count(); int freeSpace(); void mark(uint8_t b); bool commit(); uint8_t peekTargetMark(); void flush(); void info(); byte readRawByte(); inline int peek() { if ((_pos_read==_pos_write) && !_overflow) return -1; // empty return _buffer[_pos_read]; }; static const byte NO_CLIENT=255; private: int _len; int _pos_write; int _pos_read; bool _overflow; int _mark; int _count; byte * _buffer; char * _flashInsert; byte _ringClient = NO_CLIENT; }; #endif ================================================ FILE: SSD1306Ascii.cpp ================================================ /* Based on Arduino SSD1306Ascii Library, Copyright (C) 2015 by William Greiman * Modifications (C) 2021 Neil McKechnie * * This file is part of CommandStation-EX * * This Library 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. * * This Library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with the Arduino SSD1306Ascii Library. If not, see * . */ #include "SSD1306Ascii.h" #include "I2CManager.h" #include "FSH.h" //============================================================================== // SSD1306/SSD1106 I2C command bytes //------------------------------------------------------------------------------ /** Set Lower Column Start Address for Page Addressing Mode. */ static const uint8_t SSD1306_SETLOWCOLUMN = 0x00; /** Set Higher Column Start Address for Page Addressing Mode. */ static const uint8_t SSD1306_SETHIGHCOLUMN = 0x10; /** Set Memory Addressing Mode. */ static const uint8_t SSD1306_MEMORYMODE = 0x20; /** Set display RAM display start line register from 0 - 63. */ static const uint8_t SSD1306_SETSTARTLINE = 0x40; /** Set Display Contrast to one of 256 steps. */ static const uint8_t SSD1306_SETCONTRAST = 0x81; /** Enable or disable charge pump. Follow with 0X14 enable, 0X10 disable. */ static const uint8_t SSD1306_CHARGEPUMP = 0x8D; /** Set Segment Re-map between data column and the segment driver. */ static const uint8_t SSD1306_SEGREMAP = 0xA0; /** Resume display from GRAM content. */ static const uint8_t SSD1306_DISPLAYALLON_RESUME = 0xA4; /** Force display on regardless of GRAM content. */ static const uint8_t SSD1306_DISPLAYALLON = 0xA5; /** Set Normal Display. */ static const uint8_t SSD1306_NORMALDISPLAY = 0xA6; /** Set Inverse Display. */ static const uint8_t SSD1306_INVERTDISPLAY = 0xA7; /** Set Multiplex Ratio from 16 to 63. */ static const uint8_t SSD1306_SETMULTIPLEX = 0xA8; /** Set Display off. */ static const uint8_t SSD1306_DISPLAYOFF = 0xAE; /** Set Display on. */ static const uint8_t SSD1306_DISPLAYON = 0xAF; /**Set GDDRAM Page Start Address. */ static const uint8_t SSD1306_SETSTARTPAGE = 0xB0; /** Set COM output scan direction normal. */ static const uint8_t SSD1306_COMSCANINC = 0xC0; /** Set COM output scan direction reversed. */ static const uint8_t SSD1306_COMSCANDEC = 0xC8; /** Set Display Offset. */ static const uint8_t SSD1306_SETDISPLAYOFFSET = 0xD3; /** Sets COM signals pin configuration to match the OLED panel layout. */ static const uint8_t SSD1306_SETCOMPINS = 0xDA; /** This command adjusts the VCOMH regulator output. */ static const uint8_t SSD1306_SETVCOMDETECT = 0xDB; /** Set Display Clock Divide Ratio/ Oscillator Frequency. */ static const uint8_t SSD1306_SETDISPLAYCLOCKDIV = 0xD5; /** Set Pre-charge Period */ static const uint8_t SSD1306_SETPRECHARGE = 0xD9; /** Deactivate scroll */ static const uint8_t SSD1306_DEACTIVATE_SCROLL = 0x2E; /** No Operation Command. */ static const uint8_t SSD1306_NOP = 0xE3; //------------------------------------------------------------------------------ /** Set Pump voltage value: (30H~33H) 6.4, 7.4, 8.0 (POR), 9.0. */ static const uint8_t SH1106_SET_PUMP_VOLTAGE = 0x30; /** First byte of set charge pump mode */ static const uint8_t SH1106_SET_PUMP_MODE = 0xAD; /** Second byte charge pump on. */ static const uint8_t SH1106_PUMP_ON = 0x8B; /** Second byte charge pump off. */ static const uint8_t SH1106_PUMP_OFF = 0x8A; //------------------------------------------------------------------------------ // Sequence of blank pixels, to optimise clearing screen. // Send a maximum of 30 pixels per transmission. const uint8_t FLASH SSD1306AsciiWire::blankPixels[30] = {0x40, // First byte specifies data mode 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0}; //============================================================================== // this section is based on https://github.com/adafruit/Adafruit_SSD1306 /** Initialization commands for a 128x32 or 128x64 SSD1306 oled display. */ const uint8_t FLASH SSD1306AsciiWire::Adafruit128xXXinit[] = { // Init sequence for Adafruit 128x32/64 OLED module 0x00, // Set to command mode SSD1306_DISPLAYOFF, SSD1306_SETDISPLAYCLOCKDIV, 0x80, // the suggested ratio 0x80 SSD1306_SETMULTIPLEX, 0x3F, // ratio 64 (initially) SSD1306_SETDISPLAYOFFSET, 0x0, // no offset SSD1306_SETSTARTLINE | 0x0, // line #0 SSD1306_CHARGEPUMP, 0x14, // internal vcc SSD1306_MEMORYMODE, 0x02, // page mode SSD1306_SEGREMAP | 0x1, // column 127 mapped to SEG0 SSD1306_COMSCANDEC, // column scan direction reversed SSD1306_SETCOMPINS, 0X12, // set COM pins SSD1306_SETCONTRAST, 0x7F, // contrast level 127 SSD1306_SETPRECHARGE, 0xF1, // pre-charge period (1, 15) SSD1306_SETVCOMDETECT, 0x40, // vcomh regulator level SSD1306_DISPLAYALLON_RESUME, SSD1306_NORMALDISPLAY, SSD1306_DISPLAYON }; //------------------------------------------------------------------------------ // This section is based on https://github.com/stanleyhuangyc/MultiLCD /** Initialization commands for a 128x64 SH1106 oled display. */ const uint8_t FLASH SSD1306AsciiWire::SH1106_132x64init[] = { 0x00, // Set to command mode SSD1306_DISPLAYOFF, SSD1306_SETDISPLAYCLOCKDIV, 0X80, // set osc division SSD1306_SETMULTIPLEX, 0x3F, // ratio 64 SSD1306_SETDISPLAYOFFSET, 0X00, // set display offset SSD1306_SETSTARTPAGE | 0X0, // set page address SSD1306_SETSTARTLINE | 0x0, // set start line SH1106_SET_PUMP_MODE, SH1106_PUMP_ON, // set charge pump enable SSD1306_SEGREMAP | 0X1, // set segment remap SSD1306_COMSCANDEC, // Com scan direction SSD1306_SETCOMPINS, 0X12, // set COM pins SSD1306_SETCONTRAST, 0x80, // 128 SSD1306_SETPRECHARGE, 0X1F, // set pre-charge period SSD1306_SETVCOMDETECT, 0x40, // set vcomh SH1106_SET_PUMP_VOLTAGE | 0X2, // 8.0 volts SSD1306_NORMALDISPLAY, // normal / reverse SSD1306_DISPLAYON }; //============================================================================== // SSD1306AsciiWire Method Definitions //------------------------------------------------------------------------------ // Auto-detect address SSD1306AsciiWire::SSD1306AsciiWire(int width, int height) : SSD1306AsciiWire(0, width, height) { } // Constructor with explicit address SSD1306AsciiWire::SSD1306AsciiWire(I2CAddress address, int width, int height) { m_i2cAddr = address; m_displayWidth = width; m_displayHeight = height; // Set size in characters m_charsPerColumn = m_displayHeight / fontHeight; m_charsPerRow = (m_displayWidth+fontWidth-1) / fontWidth; // Round up } bool SSD1306AsciiWire::begin() { I2CManager.begin(); I2CManager.setClock(400000L); // Set max supported I2C speede if (m_i2cAddr == 0) { // Probe for I2C device on 0x3c and 0x3d. for (uint8_t address = 0x3c; address <= 0x3d; address++) { if (I2CManager.exists(address)) { m_i2cAddr = address; break; } } if (m_i2cAddr == 0) DIAG(F("OLED display not found")); } m_col = 0; m_row = 0; m_colOffset = 0; if (m_displayWidth==132 && m_displayHeight==64) { // SH1106 display. This uses 128x64 centered within a 132x64 OLED. m_colOffset = 2; I2CManager.write_P(m_i2cAddr, SH1106_132x64init, sizeof(SH1106_132x64init)); } else if (m_displayWidth==128 && (m_displayHeight==64 || m_displayHeight==32)) { // SSD1306 or SSD1309 128x64 or 128x32 I2CManager.write_P(m_i2cAddr, Adafruit128xXXinit, sizeof(Adafruit128xXXinit)); if (m_displayHeight == 32) I2CManager.write(m_i2cAddr, 5, 0, // Set command mode SSD1306_SETMULTIPLEX, 0x1F, // ratio 32 SSD1306_SETCOMPINS, 0x02); // sequential COM pins, disable remap } else { DIAG(F("OLED configuration option not recognised")); return false; } // Device found DIAG(F("%dx%d OLED display configured on I2C:%s"), m_displayWidth, m_displayHeight, m_i2cAddr.toString()); return true; } /* Clear screen by writing blank pixels. */ void SSD1306AsciiWire::clearNative() { const int maxBytes = sizeof(blankPixels) - 1; // max number of pixel columns (bytes) per transmission for (uint8_t r = 0; r <= m_displayHeight/8 - 1; r++) { setRowNative(r); // Position at start of row to be erased for (uint8_t c = 0; c < m_displayWidth; c += maxBytes) { uint8_t len = m_displayWidth-c; // Number of pixel columns remaining if (len > maxBytes) len = maxBytes; I2CManager.write_P(m_i2cAddr, blankPixels, len+1); // Write command + 'len' blank columns } } } //------------------------------------------------------------------------------ // Set cursor position (by text line) void SSD1306AsciiWire::setRowNative(uint8_t line) { // Calculate pixel position from line number uint8_t row = line*8; if (row < m_displayHeight) { m_row = row; m_col = m_colOffset; // Before using buffer, wait for last request to complete requestBlock.wait(); // Build output buffer for I2C uint8_t len = 0; outputBuffer[len++] = 0x00; // Set to command mode outputBuffer[len++] = SSD1306_SETLOWCOLUMN | (m_col & 0XF); outputBuffer[len++] = SSD1306_SETHIGHCOLUMN | (m_col >> 4); outputBuffer[len++] = SSD1306_SETSTARTPAGE | (m_row/8); I2CManager.write(m_i2cAddr, outputBuffer, len, &requestBlock); } } //------------------------------------------------------------------------------ // Write a character to the OLED size_t SSD1306AsciiWire::writeNative(uint8_t ch) { const uint8_t* base = m_font; #if defined(NOLOWERCASE) // Adjust if lowercase is missing if (ch >= 'a') { if (ch <= 'z') ch = ch - 'a' + 'A'; // Capitalise else ch -= 26; // Allow for missing lowercase letters } #endif if (ch < m_fontFirstChar || ch >= (m_fontFirstChar + m_fontCharCount)) return 0; // Check if character would be partly or wholly off the display if (m_col + fontWidth > m_displayWidth) return 0; ch -= m_fontFirstChar; base += fontWidth * ch; // Before using buffer, wait for last request to complete requestBlock.wait(); // Build output buffer for I2C outputBuffer[0] = 0x40; // set SSD1306 controller to data mode uint8_t bufferPos = 1; // Copy character pixel columns for (uint8_t i = 0; i < fontWidth; i++) { if (m_col++ < m_displayWidth) outputBuffer[bufferPos++] = GETFLASH(base++); } // Write the data to I2C display I2CManager.write(m_i2cAddr, outputBuffer, bufferPos, &requestBlock); return 1; } //------------------------------------------------------------------------------ // Font characters, 6x8 pixels, starting at 0x20. // Lower case characters optionally omitted. const uint8_t FLASH SSD1306AsciiWire::System6x8[] = { // Fixed width; char width table not used !!!! // font data 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // (space) (20) 0x00, 0x00, 0x5F, 0x00, 0x00, 0x00, // ! (21) 0x00, 0x07, 0x00, 0x07, 0x00, 0x00, // " 0x14, 0x7F, 0x14, 0x7F, 0x14, 0x00, // # 0x24, 0x2A, 0x7F, 0x2A, 0x12, 0x00, // $ 0x23, 0x13, 0x08, 0x64, 0x62, 0x00, // % 0x36, 0x49, 0x55, 0x22, 0x50, 0x00, // & 0x00, 0x05, 0x03, 0x00, 0x00, 0x00, // ' 0x00, 0x1C, 0x22, 0x41, 0x00, 0x00, // ( 0x00, 0x41, 0x22, 0x1C, 0x00, 0x00, // ) 0x08, 0x2A, 0x1C, 0x2A, 0x08, 0x00, // * 0x08, 0x08, 0x3E, 0x08, 0x08, 0x00, // + 0x00, 0x50, 0x30, 0x00, 0x00, 0x00, // , 0x08, 0x08, 0x08, 0x08, 0x08, 0x00, // - 0x00, 0x60, 0x60, 0x00, 0x00, 0x00, // . 0x20, 0x10, 0x08, 0x04, 0x02, 0x00, // / (47) 0x3E, 0x51, 0x49, 0x45, 0x3E, 0x00, // 0 (48) 0x00, 0x42, 0x7F, 0x40, 0x00, 0x00, // 1 0x42, 0x61, 0x51, 0x49, 0x46, 0x00, // 2 0x21, 0x41, 0x45, 0x4B, 0x31, 0x00, // 3 0x18, 0x14, 0x12, 0x7F, 0x10, 0x00, // 4 0x27, 0x45, 0x45, 0x45, 0x39, 0x00, // 5 0x3C, 0x4A, 0x49, 0x49, 0x30, 0x00, // 6 0x01, 0x71, 0x09, 0x05, 0x03, 0x00, // 7 0x36, 0x49, 0x49, 0x49, 0x36, 0x00, // 8 0x06, 0x49, 0x49, 0x29, 0x1E, 0x00, // 9 (57) 0x00, 0x36, 0x36, 0x00, 0x00, 0x00, // : 0x00, 0x56, 0x36, 0x00, 0x00, 0x00, // ; 0x00, 0x08, 0x14, 0x22, 0x41, 0x00, // < 0x14, 0x14, 0x14, 0x14, 0x14, 0x00, // = 0x41, 0x22, 0x14, 0x08, 0x00, 0x00, // > 0x02, 0x01, 0x51, 0x09, 0x06, 0x00, // ? 0x32, 0x49, 0x79, 0x41, 0x3E, 0x00, // @ (64) 0x7E, 0x11, 0x11, 0x11, 0x7E, 0x00, // A (65) 0x7F, 0x49, 0x49, 0x49, 0x36, 0x00, // B 0x3E, 0x41, 0x41, 0x41, 0x22, 0x00, // C 0x7F, 0x41, 0x41, 0x22, 0x1C, 0x00, // D 0x7F, 0x49, 0x49, 0x49, 0x41, 0x00, // E 0x7F, 0x09, 0x09, 0x01, 0x01, 0x00, // F 0x3E, 0x41, 0x41, 0x51, 0x32, 0x00, // G 0x7F, 0x08, 0x08, 0x08, 0x7F, 0x00, // H 0x00, 0x41, 0x7F, 0x41, 0x00, 0x00, // I 0x20, 0x40, 0x41, 0x3F, 0x01, 0x00, // J 0x7F, 0x08, 0x14, 0x22, 0x41, 0x00, // K 0x7F, 0x40, 0x40, 0x40, 0x40, 0x00, // L 0x7F, 0x02, 0x04, 0x02, 0x7F, 0x00, // M 0x7F, 0x04, 0x08, 0x10, 0x7F, 0x00, // N 0x3E, 0x41, 0x41, 0x41, 0x3E, 0x00, // O 0x7F, 0x09, 0x09, 0x09, 0x06, 0x00, // P 0x3E, 0x41, 0x51, 0x21, 0x5E, 0x00, // Q 0x7F, 0x09, 0x19, 0x29, 0x46, 0x00, // R 0x46, 0x49, 0x49, 0x49, 0x31, 0x00, // S 0x01, 0x01, 0x7F, 0x01, 0x01, 0x00, // T 0x3F, 0x40, 0x40, 0x40, 0x3F, 0x00, // U 0x1F, 0x20, 0x40, 0x20, 0x1F, 0x00, // V 0x7F, 0x20, 0x18, 0x20, 0x7F, 0x00, // W 0x63, 0x14, 0x08, 0x14, 0x63, 0x00, // X 0x03, 0x04, 0x78, 0x04, 0x03, 0x00, // Y 0x61, 0x51, 0x49, 0x45, 0x43, 0x00, // Z (90) 0x00, 0x00, 0x7F, 0x41, 0x41, 0x00, // [ 0x02, 0x04, 0x08, 0x10, 0x20, 0x00, // "\" 0x41, 0x41, 0x7F, 0x00, 0x00, 0x00, // ] 0x04, 0x02, 0x01, 0x02, 0x04, 0x00, // ^ 0x40, 0x40, 0x40, 0x40, 0x40, 0x00, // _ 0x00, 0x01, 0x02, 0x04, 0x00, 0x00, // ' (96) #ifndef NOLOWERCASE 0x20, 0x54, 0x54, 0x54, 0x78, 0x00, // a (97) 0x7F, 0x48, 0x44, 0x44, 0x38, 0x00, // b 0x38, 0x44, 0x44, 0x44, 0x20, 0x00, // c 0x38, 0x44, 0x44, 0x48, 0x7F, 0x00, // d 0x38, 0x54, 0x54, 0x54, 0x18, 0x00, // e 0x08, 0x7E, 0x09, 0x01, 0x02, 0x00, // f 0x08, 0x14, 0x54, 0x54, 0x3C, 0x00, // g 0x7F, 0x08, 0x04, 0x04, 0x78, 0x00, // h 0x00, 0x44, 0x7D, 0x40, 0x00, 0x00, // i 0x20, 0x40, 0x44, 0x3D, 0x00, 0x00, // j 0x00, 0x7F, 0x10, 0x28, 0x44, 0x00, // k 0x00, 0x41, 0x7F, 0x40, 0x00, 0x00, // l 0x7C, 0x04, 0x18, 0x04, 0x78, 0x00, // m 0x7C, 0x08, 0x04, 0x04, 0x78, 0x00, // n 0x38, 0x44, 0x44, 0x44, 0x38, 0x00, // o 0x7C, 0x14, 0x14, 0x14, 0x08, 0x00, // p 0x08, 0x14, 0x14, 0x18, 0x7C, 0x00, // q 0x7C, 0x08, 0x04, 0x04, 0x08, 0x00, // r 0x48, 0x54, 0x54, 0x54, 0x20, 0x00, // s 0x04, 0x3F, 0x44, 0x40, 0x20, 0x00, // t 0x3C, 0x40, 0x40, 0x20, 0x7C, 0x00, // u 0x1C, 0x20, 0x40, 0x20, 0x1C, 0x00, // v 0x3C, 0x40, 0x30, 0x40, 0x3C, 0x00, // w 0x44, 0x28, 0x10, 0x28, 0x44, 0x00, // x 0x0C, 0x50, 0x50, 0x50, 0x3C, 0x00, // y 0x44, 0x64, 0x54, 0x4C, 0x44, 0x00, // z (122) #endif 0x00, 0x08, 0x36, 0x41, 0x00, 0x00, // { (123) 0x00, 0x00, 0x7F, 0x00, 0x00, 0x00, // | 0x00, 0x41, 0x36, 0x08, 0x00, 0x00, // } 0x08, 0x08, 0x2A, 0x1C, 0x08, 0x00, // -> 0x08, 0x1C, 0x2A, 0x08, 0x08, 0x00, // <- (127) #ifndef NO_EXTENDED_CHARACTERS // Extended characters - based on "DOS Western Europe" characters // International characters not yet implemented. 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x80 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x90 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x38, 0x44, 0xc6, 0x44, 0x20, 0x00, // cent 0x9b 0x44, 0x6e, 0x59, 0x49, 0x62, 0x00, // £ 0x9c 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0xa0 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x10, 0x28, 0x54, 0x28, 0x44, 0x00, // << 0x44, 0x28, 0x54, 0x28, 0x10, 0x00, // >> // Extended characters 176-180 0x92, 0x00, 0x49, 0x00, 0x24, 0x00, // Light grey 0xb0 0xaa, 0x44, 0xaa, 0x11, 0xaa, 0x55, // Mid grey 0xb1 0x6d, 0xff, 0xb6, 0xff, 0xdb, 0xff, // Dark grey 0xb2 0x00, 0x00, 0x00, 0xff, 0x00, 0x00, // Vertical line 0xb3 0x08, 0x08, 0x08, 0xff, 0x00, 0x00, // Vertical line with left spur 0xb4 0x14, 0x14, 0x14, 0xff, 0x00, 0x00, // Vertical line with double left spur 0xb5 0x08, 0x08, 0xff, 0x00, 0xff, 0x00, // Double vertical line with single left spur 0x08, 0x08, 0xf8, 0x08, 0xf8, 0x00, // Top right corner, single horiz, double vert 0x14, 0x14, 0x14, 0xfc, 0x00, 0x00, // Top right corner, double horiz, single vert // Extended characters 185-190 0x14, 0x14, 0xf7, 0x00, 0xff, 0x00, // Double vertical line with double left spur 0xb9 0x00, 0x00, 0xff, 0x00, 0xff, 0x00, // Double vertical line 0xba 0x14, 0x14, 0xf4, 0x04, 0xfc, 0x00, // Double top right corner 0xbb 0x14, 0x14, 0x17, 0x10, 0x1f, 0x00, // Double bottom right corner 0xbc 0x08, 0x08, 0x0f, 0x08, 0x0f, 0x00, // Bottom right corner, single horiz, double vert 0xbd 0x14, 0x14, 0x14, 0x1f, 0x00, 0x00, // Bottom right corner, double horiz, single vert 0xbe // Extended characters 191-199 0x08, 0x08, 0x08, 0xf8, 0x00, 0x00, // Top right corner 0xbf 0x00, 0x00, 0x00, 0x0f, 0x08, 0x08, // Bottom left corner 0xc0 0x08, 0x08, 0x08, 0x0f, 0x08, 0x08, // Horizontal line with upward spur 0xc1 0x08, 0x08, 0x08, 0xf8, 0x08, 0x08, // Horizontal line with downward spur 0xc2 0x00, 0x00, 0x00, 0xff, 0x08, 0x08, // Vertical line with right spur 0xc3 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, // Horizontal line 0xc4 0x08, 0x08, 0x08, 0xff, 0x08, 0x08, // Cross 0xc5 0x00, 0x00, 0x00, 0xff, 0x14, 0x14, // Vertical line double right spur 0xc6 0x00, 0x00, 0xff, 0x00, 0xff, 0x08, // Double vertical line single right spur 0xc7 // Extended characters 200-206 0x00, 0x00, 0x1f, 0x10, 0x17, 0x14, // Double bottom left corner 0xc8 0x00, 0x00, 0xfc, 0x04, 0xf4, 0x14, // Double top left corner 0xc9 0x14, 0x14, 0x17, 0x10, 0x17, 0x14, // Double horizontal with double upward spur 0xca 0x14, 0x14, 0xf4, 0x04, 0xf4, 0x14, // Double horizontal with double downward spur 0xcb 0x00, 0x00, 0xff, 0x00, 0xf7, 0x14, // Double vertical line with double right spur 0xcc 0x14, 0x14, 0x14, 0x14, 0x14, 0x14, // Double horizontal line 0xcd 0x14, 0x14, 0xf7, 0x00, 0xf7, 0x14, // Double cross 0xce 0x14, 0x14, 0x14, 0x17, 0x14, 0x14, // Double horizontal line single upward spur 0xcf 0x08, 0x08, 0x0f, 0x08, 0x0f, 0x08, // Horiz single line with double upward spur 0xd0 0x14, 0x14, 0x14, 0xf4, 0x14, 0x14, // Horiz double line with single downward spur 0xd1 0x08, 0x08, 0xf8, 0x08, 0xf8, 0x08, // Horiz single line with double downward spur 0xd2 0x00, 0x00, 0x0f, 0x08, 0x0f, 0x08, // Bottom left corner, double vert single horiz 0xd3 0x00, 0x00, 0x00, 0x1f, 0x14, 0x14, // Bottom left corner, single vert double horiz 0xd4 0x00, 0x00, 0x00, 0xfc, 0x14, 0x14, // Top left corner, single vert double horiz 0xd5 0x00, 0x00, 0xf8, 0x08, 0xf8, 0x08, // Top left corner, double vert single horiz 0xd6 0x08, 0x08, 0xff, 0x00, 0xff, 0x08, // Cross, double vert single horiz 0xd7 0x14, 0x14, 0x14, 0xf7, 0x14, 0x14, // Cross, single vert double horiz 0xd8 // Extended characters 217-223 0x08, 0x08, 0x08, 0x0f, 0x00, 0x00, // Bottom right corner 0xd9 0x00, 0x00, 0x00, 0xf8, 0x08, 0x08, // Top left corner 0xda 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, // Solid block 0xdb 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, // Bottom half block 0xdc 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, // Left half block 0xdd 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, // Right half block 0xde 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, // Top half block 0xdf 0xf0, 0xf0, 0xf0, 0x00, 0x00, 0x00, // Bottom Left block 0xe0 0x00, 0x00, 0x00, 0xf0, 0xf0, 0xf0, // Bottom Right block 0x0f, 0x0f, 0x0f, 0x00, 0x00, 0x00, // Top left block 0x00, 0x00, 0x00, 0x0f, 0x0f, 0x0f, // Top right block 0xe3 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0xf0 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // Not implemented // Extended character 248 0x00, 0x06, 0x09, 0x09, 0x06, 0x00 // degree symbol 0xf8 #endif }; const uint8_t SSD1306AsciiWire::m_fontCharCount = sizeof(System6x8) / 6; ================================================ FILE: SSD1306Ascii.h ================================================ /* Based on Arduino SSD1306Ascii Library, Copyright (C) 2015 by William Greiman * Modifications (C) 2021 Neil McKechnie * * This file is part of CommandStation-EX * * This Library 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. * * This Library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this software. If not, see * . */ #ifndef SSD1306Ascii_h #define SSD1306Ascii_h #include "Arduino.h" #include "FSH.h" #include "Display.h" #include "I2CManager.h" #include "DIAG.h" #include "DisplayInterface.h" // Uncomment to remove lower-case letters to save 108 bytes of flash //#define NOLOWERCASE //------------------------------------------------------------------------------ // Constructor class SSD1306AsciiWire : public DisplayDevice { public: // Constructors SSD1306AsciiWire(int width, int height); // Auto-detects I2C address SSD1306AsciiWire(I2CAddress address, int width, int height); // Initialize the display controller. bool begin(); // Clear the display and set the cursor to (0, 0). void clearNative() override; // Set cursor to start of specified text line void setRowNative(byte line) override; // Write one character to OLED size_t writeNative(uint8_t c) override; bool isBusy() override { return requestBlock.isBusy(); } uint16_t getNumCols() { return m_charsPerRow; } uint16_t getNumRows() { return m_charsPerColumn; } private: // Cursor column. uint8_t m_col; // Cursor RAM row. uint8_t m_row; // Display width. uint8_t m_displayWidth; // Display height. uint8_t m_displayHeight; // Display width in characters uint8_t m_charsPerRow; // Display height in characters uint8_t m_charsPerColumn; // Column offset RAM to SEG. uint8_t m_colOffset = 0; // Current font. const uint8_t* const m_font = System6x8; // Flag to prevent calling begin() twice uint8_t m_initialised = false; // Only fixed size 6x8 fonts in a 6x8 cell are supported. static const uint8_t fontWidth = 6; static const uint8_t fontHeight = 8; static const uint8_t m_fontFirstChar = 0x20; static const uint8_t m_fontCharCount; I2CAddress m_i2cAddr = 0; I2CRB requestBlock; uint8_t outputBuffer[fontWidth+1]; static const uint8_t blankPixels[]; static const uint8_t System6x8[]; static const uint8_t FLASH Adafruit128xXXinit[]; static const uint8_t FLASH SH1106_132x64init[]; }; #endif // SSD1306Ascii_h ================================================ FILE: STM32lwipopts.h.copyme ================================================ /* * © 2024 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 . */ // // Rewrite of the STM32lwipopts.h file from STM // To be copied into where lwipopts_default.h resides // typically into STM32Ethernet/src/STM32lwipopts.h // or STM32Ethernet\src\STM32lwipopts.h // search for `lwipopts_default.h` and copy this file into the // same directory but name it STM32lwipopts.h // #ifndef __STM32LWIPOPTS_H__ #define __STM32LWIPOPTS_H__ // include this here and then override things we do differnet #include "lwipopts_default.h" // we can not include our "defines.h" here // so we need to duplicate that define #define MAX_NUM_TCP_CLIENTS_HERE 9 #ifdef MAX_NUM_TCP_CLIENTS #if MAX_NUM_TCP_CLIENTS != MAX_NUM_TCP_CLIENTS_HERE #error MAX_NUM_TCP_CLIENTS and MAX_NUM_TCP_CLIENTS_HERE must be same #endif #else #define MAX_NUM_TCP_CLIENTS MAX_NUM_TCP_CLIENTS_HERE #endif // increase ARP cache #undef MEMP_NUM_APR_QUEUE #define MEMP_NUM_ARP_QUEUE MAX_NUM_TCP_CLIENTS+3 // one for each client (all on different HW) and a few extra // Example for debug //#define LWIP_DEBUG 1 //#define TCP_DEBUG LWIP_DBG_ON // NOT STRICT NECESSARY ANY MORE BUT CAN BE USED TO SAVE RAM #undef MEM_LIBC_MALLOC #define MEM_LIBC_MALLOC 1 // use the same malloc as for everything else #undef MEMP_MEM_MALLOC #define MEMP_MEM_MALLOC 1 // uses malloc which means no pools which means slower but not mean 32KB up front #undef MEMP_NUM_TCP_PCB #define MEMP_NUM_TCP_PCB MAX_NUM_TCP_CLIENTS+1 // one extra so we can reject number N+1 from our code #define MEMP_NUM_TCP_PCB_LISTEN 6 #undef MEMP_NUM_TCP_SEG #define MEMP_NUM_TCP_SEG MAX_NUM_TCP_CLIENTS #undef MEMP_NUM_SYS_TIMEOUT #define MEMP_NUM_SYS_TIMEOUT MAX_NUM_TCP_CLIENTS+2 #undef PBUF_POOL_SIZE #define PBUF_POOL_SIZE MAX_NUM_TCP_CLIENTS #undef LWIO_ICMP #define LWIP_ICMP 1 #undef LWIP_RAW #define LWIP_RAW 1 /* PING changed to 1 */ #undef DEFAULT_RAW_RECVMBOX_SIZE #define DEFAULT_RAW_RECVMBOX_SIZE 3 /* for ICMP PING */ #undef LWIP_DHCP #define LWIP_DHCP 1 #undef LWIP_UDP #define LWIP_UDP 1 /* The STM32F4x7 allows computing and verifying the IP, UDP, TCP and ICMP checksums by hardware: - To use this feature let the following define uncommented. - To disable it and process by CPU comment the the checksum. */ #if CHECKSUM_GEN_TCP == 1 #error On STM32 TCP checksum should be in HW #endif #undef LWIP_IGMP #define LWIP_IGMP 1 //#define SO_REUSE 1 //#define SO_REUSE_RXTOALL 1 #endif /* __STM32LWIPOPTS_H__ */ ================================================ FILE: SensorGroup.cpp ================================================ #include "SensorGroup.h" #include "CommandDistributor.h" #ifdef EXRAIL_ACTIVE // called in loop to check sensors void SensorGroup::checkAll() { doExrailSensorGroup(GroupProcess::check, & USB_SERIAL); } // called by command to get sensor list void SensorGroup::printAll(Print * serial) { (void)serial; // suppress unused warning doExrailSensorGroup(GroupProcess::print,serial); } void SensorGroup::prepareAll() { doExrailSensorGroup(GroupProcess::prepare, & USB_SERIAL); } void SensorGroup::dumpAll(Print * stream) { doExrailSensorGroup(GroupProcess::dump, stream); } #else // if EXRAIL is not active, these functions are empty void SensorGroup::checkAll() {} void SensorGroup::printAll(Print * serial) {(void)serial;} void SensorGroup::prepareAll() {} void SensorGroup::dumpAll(Print * stream) {(void)stream;} #endif // called by EXRAIL constructed doExrailSensorGroup for each group void SensorGroup::doSensorGroup(VPIN firstVpin, int nPins, byte* statebits, GroupProcess action, Print * serial, bool pullup) { // Loop through the pins in the group for (auto i=0;i\n"), (statebits[stateByte]&stateMask)?'Q':'q', vpin); break; case GroupProcess::dump: StringFormatter::send(serial, F("\n"), vpin, vpin, pullup?'1':'0'); break; } } } ================================================ FILE: SensorGroup.h ================================================ #ifndef SensorGroup_h #define SensorGroup_h #include #include "defines.h" #include "IODevice.h" #include "StringFormatter.h" // reference to the optional exrail built function which contains the // calls to SensorGroup::doSensorGroup enum GroupProcess:byte {prepare,print,check,dump}; class SensorGroup { public: static void checkAll(); static void printAll(Print * serial); static void prepareAll(); static void dumpAll(Print* serial); // doSensorGroup is called from the automatically // built doExrailSensorGroup, once for each user defined group. static void doSensorGroup(VPIN vpin, int nPins, byte* statebits, GroupProcess action, Print * serial, bool pullup=false); private: static void doExrailSensorGroup(GroupProcess action, Print * stream); }; #endif // SensorGroup_h ================================================ FILE: Sensors.cpp ================================================ /* * © 2021 Neil McKechnie * © 2020-2021 Harald Barth * © 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 . */ /********************************************************************** DCC++ BASE STATION supports Sensor inputs that can be connected to any Arduino Pin not in use by this program. Sensors can be of any type (infrared, magentic, mechanical...). The only requirement is that when "activated" the Sensor must force the specified Arduino Pin LOW (i.e. to ground), and when not activated, this Pin should remain HIGH (e.g. 5V), or be allowed to float HIGH if use of the Arduino Pin's internal pull-up resistor is specified. To ensure proper voltage levels, some part of the Sensor circuitry MUST be tied back to the same ground as used by the Arduino. The Sensor code below utilises "de-bounce" logic to remove spikes generated by mechanical switches and transistors. This avoids the need to create smoothing circuitry for each sensor. You may need to change the parameters through trial and error for your specific sensors. To have this sketch monitor one or more Arduino pins for sensor triggers, first define/edit/delete sensor definitions using the following variation of the "S" command: : creates a new sensor ID, with specified PIN and PULLUP if sensor ID already exists, it is updated with specificed PIN and PULLUP returns: if successful and if unsuccessful (e.g. out of memory) : deletes definition of sensor ID returns: if successful and if unsuccessful (e.g. ID does not exist) : lists all defined sensors returns: for each defined sensor or if no sensors defined where ID: the numeric ID (0-32767) of the sensor PIN: the arduino pin number the sensor is connected to PULLUP: 1=use internal pull-up resistor for PIN, 0=don't use internal pull-up resistor for PIN Once all sensors have been properly defined, use the command to store their definitions to EEPROM. If you later make edits/additions/deletions to the sensor definitions, you must invoke the command if you want those new definitions updated in the EEPROM. You can also clear everything stored in the EEPROM by invoking the command. All sensors defined as per above are repeatedly and sequentially checked within the main loop of this sketch. If a Sensor Pin is found to have transitioned from one state to another, one of the following serial messages are generated: - for transition of Sensor ID from HIGH state to LOW state (i.e. the sensor is triggered) - for transition of Sensor ID from LOW state to HIGH state (i.e. the sensor is no longer triggered) Depending on whether the physical sensor is acting as an "event-trigger" or a "detection-sensor," you may decide to ignore the return and only react to triggers. **********************************************************************/ #include "StringFormatter.h" #include "CommandDistributor.h" #include "Sensors.h" #ifndef DISABLE_EEPROM #include "EEStore.h" #endif #include "IODevice.h" /////////////////////////////////////////////////////////////////////////////// // checks a number of defined sensors per entry and prints _changed_ sensor state // to stream unless stream is NULL in which case only internal // state is updated. Then advances to next sensor which will // be checked at next invocation. Each cycle of reading all sensors will // be initiated no more frequently than the time set by 'cycleInterval' microseconds. // // The list of sensors is divided such that the first part of the list // contains sensors that support change notification via callback, and the second // part of the list contains sensors that require cyclic polling. The start of the // second part of the list is determined from by the 'firstPollSensor' pointer. /////////////////////////////////////////////////////////////////////////////// void Sensor::checkAll(){ SensorGroup::checkAll(); uint16_t sensorCount = 0; #ifdef USE_NOTIFY // Register the event handler ONCE! if (!inputChangeCallbackRegistered) IONotifyCallback::add(inputChangeCallback); inputChangeCallbackRegistered = true; #endif if (firstSensor == NULL) return; // No sensors to be scanned if (readingSensor == NULL) { // Not currently scanning sensor list unsigned long thisTime = micros(); if (thisTime - lastReadCycle >= cycleInterval) { // Required time elapsed since last read cycle started, // so initiate new scan through the sensor list readingSensor = firstSensor; lastReadCycle = thisTime; } } // Loop until either end of list is encountered or we pause for some reason bool pause = false; while (readingSensor != NULL && !pause) { // Where the sensor is attached to a pin, read pin status. For sources such as LCN, // which don't have an input pin to read, the LCN class calls setState() to update inputState when // a message is received. The IODevice::read() call returns 1 for active pins (0v) and 0 for inactive (5v). // Also, on HAL drivers that support change notifications, the driver calls the notification callback // routine when an input signal change is detected, and this updates the inputState directly, // so these inputs don't need to be polled here. VPIN pin = readingSensor->data.pin; if (readingSensor->pollingRequired && pin != VPIN_NONE) readingSensor->inputState = IODevice::read(pin); // Check if changed since last time, and process changes. if (readingSensor->inputState == readingSensor->active) { // no change readingSensor->latchDelay = minReadCount; // Reset counter } else if (readingSensor->latchDelay > 0) { // change detected, but first decrement delay readingSensor->latchDelay--; } else { // change validated, act on it. readingSensor->active = readingSensor->inputState; readingSensor->latchDelay = minReadCount; // Reset counter CommandDistributor::broadcastSensor(readingSensor->data.snum,readingSensor->active); pause = true; // Don't check any more sensors on this entry } // Move to next sensor in list. readingSensor = readingSensor->nextSensor; // Currently process max of 16 sensors per entry. // Performance measurements taken during development indicate that, with 128 sensors configured // on 8x 16-pin MCP23017 GPIO expanders with polling (no change notification), all inputs can be read from the devices // within 1.4ms (400Mhz I2C bus speed), and a full cycle of checking 128 sensors for changes takes under a millisecond. sensorCount++; if (sensorCount >= 16) pause = true; } } // Sensor::checkAll #ifdef USE_NOTIFY // Callback from HAL (IODevice class) when a digital input change is recognised. // Updates the inputState field, which is subsequently scanned for changes in the checkAll // method. Ideally the / message should be sent from here, instead of waiting for // the checkAll method, but the output stream is not available at this point. void Sensor::inputChangeCallback(VPIN vpin, int state) { Sensor *tt; // This bit is not ideal since it has, potentially, to look through the entire list of // sensors to find the one that has changed. Ideally this should be improved somehow. for (tt=firstSensor; tt!=NULL ; tt=tt->nextSensor) { if (tt->data.pin == vpin) break; } if (tt != NULL) { // Sensor found tt->inputState = (state != 0); } } #endif /////////////////////////////////////////////////////////////////////////////// // // prints all sensor states to stream // /////////////////////////////////////////////////////////////////////////////// void Sensor::printAll(Print *stream){ if (stream == NULL) return; // Nothing to do SensorGroup::printAll(stream); for(Sensor * tt=firstSensor;tt!=NULL;tt=tt->nextSensor){ StringFormatter::send(stream, F("<%c %d>\n"), tt->active ? 'Q' : 'q', tt->data.snum); } } void Sensor::dumpAll(Print *stream){ if (stream == NULL) return; // Nothing to do SensorGroup::dumpAll(stream); for(Sensor * tt=firstSensor;tt!=NULL;tt=tt->nextSensor){ StringFormatter::send(stream, F("\n"), tt->data.snum, tt->data.pin,tt->data.pullUp); } } // Sensor::dumpAll /////////////////////////////////////////////////////////////////////////////// // Static Function to create/find Sensor object. Sensor *Sensor::create(int snum, VPIN pin, int pullUp){ Sensor *tt; if (pin > VPIN_MAX && pin != VPIN_NONE) return NULL; remove(snum); // Unlink and free any existing sensor with the same id, before creating the new one. tt = (Sensor *)calloc(1,sizeof(Sensor)); if (!tt) return tt; // memory allocation failure if (pin == VPIN_NONE) tt->pollingRequired = false; #ifdef USE_NOTIFY else if (IODevice::hasCallback(pin)) tt->pollingRequired = false; #endif else tt->pollingRequired = true; // Add to the start of the list tt->nextSensor = firstSensor; firstSensor = tt; tt->data.snum = snum; tt->data.pin = pin; tt->data.pullUp = pullUp; tt->active = 0; tt->inputState = 0; tt->latchDelay = minReadCount; if (pin != VPIN_NONE) IODevice::configureInput(pin, pullUp); // Generally, internal pull-up resistors are not, on their own, sufficient // for external infrared sensors --- each sensor must have its own 1K external pull-up resistor return tt; } // Creet multiple eponymous sensors based on vpin alone. void Sensor::createMultiple(VPIN firstPin, byte count) { for (byte i=0;idata.snum!=n;tt=tt->nextSensor); return tt ; } /////////////////////////////////////////////////////////////////////////////// bool Sensor::remove(int n){ Sensor *tt,*pp=NULL; for(tt=firstSensor;tt!=NULL && tt->data.snum!=n;pp=tt,tt=tt->nextSensor); if (tt==NULL) return false; // Unlink the sensor from the list if(tt==firstSensor) firstSensor=tt->nextSensor; else pp->nextSensor=tt->nextSensor; #ifdef USE_NOTIFY if (tt==lastSensor) lastSensor = pp; if (tt==firstPollSensor) firstPollSensor = tt->nextSensor; #endif // Check if the sensor being deleted is the next one to be read. If so, // make the following one the next one to be read. if (readingSensor==tt) readingSensor=tt->nextSensor; free(tt); return true; } /////////////////////////////////////////////////////////////////////////////// #ifndef DISABLE_EEPROM void Sensor::load(){ struct SensorData data; Sensor *tt; uint16_t i=EEStore::eeStore->data.nSensors; while(i--){ EEPROM.get(EEStore::pointer(),data); tt=create(data.snum, data.pin, data.pullUp); EEStore::advance(sizeof(tt->data)); } } /////////////////////////////////////////////////////////////////////////////// void Sensor::store(){ Sensor *tt; tt=firstSensor; EEStore::eeStore->data.nSensors=0; while(tt!=NULL){ EEPROM.put(EEStore::pointer(),tt->data); EEStore::advance(sizeof(tt->data)); tt=tt->nextSensor; EEStore::eeStore->data.nSensors++; } } #endif /////////////////////////////////////////////////////////////////////////////// Sensor *Sensor::firstSensor=NULL; Sensor *Sensor::readingSensor=NULL; unsigned long Sensor::lastReadCycle=0; #ifdef USE_NOTIFY Sensor *Sensor::firstPollSensor = NULL; Sensor *Sensor::lastSensor = NULL; bool Sensor::inputChangeCallbackRegistered = false; #endif ================================================ FILE: Sensors.h ================================================ /* * © 2021 Neil McKechnie * © 2020-2021 Harald Barth * © 2020-2021 Chris Harlow * 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 . */ #ifndef Sensor_h #define Sensor_h #include "Arduino.h" #include "IODevice.h" #include "SensorGroup.h" // Uncomment the following #define statement to use callback notification // where the driver supports it. // The principle of callback notification is to avoid the Sensor class // having to poll the device driver cyclically for input values, and then scan // for changes. Instead, when the driver scans the inputs, if it detects // a change it invokes a callback function in the Sensor class. In the current // implementation, the advantages are limited because (a) the Sensor class // performs debounce checks, and (b) the Sensor class does not have a // static reference to the output stream for sending / messages // when a change is detected. These restrictions mean that the checkAll() // method still has to iterate through all of the Sensor objects looking // for changes. #define USE_NOTIFY struct SensorData { int snum; VPIN pin; uint8_t pullUp; }; class Sensor{ // The sensor list is a linked list where each sensor's 'nextSensor' field points to the next. // The pointer is null in the last on the list. public: SensorData data; struct { uint8_t active:1; uint8_t inputState:1; uint8_t latchDelay:6; }; // bit 7=active; bit 6=input state; bits 5-0=latchDelay static Sensor *firstSensor; #ifdef USE_NOTIFY static Sensor *firstPollSensor; static Sensor *lastSensor; #endif // readingSensor points to the next sensor to be polled, or null if the poll cycle is completed for // the period. static Sensor *readingSensor; // Constructor Sensor(); Sensor *nextSensor; void setState(int state); #ifndef DISABLE_EEPROM static void load(); static void store(); #endif static Sensor *create(int id, VPIN vpin, int pullUp); static void createMultiple(VPIN firstPin, byte count=1); static Sensor* get(int id); static bool remove(int id); static void checkAll(); static void printAll(Print *stream); static void dumpAll(Print* stream); static unsigned long lastReadCycle; // value of micros at start of last read cycle static const unsigned int cycleInterval = 10000; // min time between consecutive reads of each sensor in microsecs. // should not be less than device scan cycle time. static const unsigned int minReadCount = 1; // number of additional scans before acting on change // E.g. 1 means that a change is ignored for one scan and actioned on the next. // Max value is 63 bool pollingRequired = true; #ifdef USE_NOTIFY static void inputChangeCallback(VPIN vpin, int state); static bool inputChangeCallbackRegistered; #endif }; // Sensor #endif ================================================ FILE: SerialManager.cpp ================================================ /* * © 2022 Paul M. Antoine * © 2021 Chris Harlow * © 2022 2024 Harald Barth * All rights reserved. * * 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 . */ #include "SerialManager.h" #include "DCCEXParser.h" #include "StringFormatter.h" #include "DIAG.h" #ifdef ARDUINO_ARCH_ESP32 #ifdef SERIAL_BT_COMMANDS #include //#include #if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED) #error No Bluetooth library available #endif //ENABLED BluetoothSerial SerialBT; //BleSerial SerialBT; #endif //COMMANDS #endif //ESP32 static const byte PAYLOAD_FALSE = 0; static const byte PAYLOAD_NORMAL = 1; static const byte PAYLOAD_STRING = 2; SerialManager * SerialManager::first=NULL; SerialManager::SerialManager(Stream * myserial) { serial=myserial; next=first; first=this; bufferLength=0; inCommandPayload=PAYLOAD_FALSE; } void SerialManager::init() { USB_SERIAL.begin(115200); while (!USB_SERIAL && millis() < 5000); // wait max 5s for Serial to start new SerialManager(&USB_SERIAL); #ifdef SERIAL6_COMMANDS Serial6.begin(115200); new SerialManager(&Serial6); #endif #ifdef SERIAL5_COMMANDS Serial5.begin(115200); new SerialManager(&Serial5); #endif #ifdef SERIAL4_COMMANDS Serial4.begin(115200); new SerialManager(&Serial4); #endif #ifdef SERIAL3_COMMANDS Serial3.begin(115200); new SerialManager(&Serial3); #endif #ifdef SERIAL2_COMMANDS #ifdef ARDUINO_ARCH_ESP32 Serial2.begin(115200, SERIAL_8N1, 16, 17); // GPIO 16 RXD2; GPIO 17 TXD2 on ESP32 #else // not ESP32 Serial2.begin(115200); #endif // ESP32 new SerialManager(&Serial2); #endif #ifdef SERIAL1_COMMANDS Serial1.begin(115200); new SerialManager(&Serial1); #endif #ifdef SERIAL_BT_COMMANDS { //SerialBT.setPin("6666"); // choose other pin uint64_t chipid = ESP.getEfuseMac(); char idstr[16] = {0}; snprintf(idstr, 15, "DCCEX-%08X", __builtin_bswap32((uint32_t)(chipid>>16))); SerialBT.begin(idstr); new SerialManager(&SerialBT); delay(1000); } #endif #ifdef SABERTOOTH #ifdef ARDUINO_ARCH_ESP32 Serial2.begin(9600, SERIAL_8N1, 16, 17); // GPIO 16 RXD2; GPIO 17 TXD2 on ESP32 #else Serial2.begin(9600); #endif #endif } void SerialManager::broadcast(char * stringBuffer) { for (SerialManager * s=first;s;s=s->next) s->broadcast2(stringBuffer); } void SerialManager::broadcast2(char * stringBuffer) { serial->print(stringBuffer); } void SerialManager::loop() { for (SerialManager * s=first;s;s=s->next) s->loop2(); } void SerialManager::loop2() { while (serial->available()) { char ch = serial->read(); if (!inCommandPayload) { if (ch == '<') { inCommandPayload = PAYLOAD_NORMAL; bufferLength = 0; buffer[0] = '\0'; } } else { // if (inCommandPayload) if (bufferLength < (COMMAND_BUFFER_SIZE-1)) { buffer[bufferLength++] = ch; // advance bufferLength if (inCommandPayload > PAYLOAD_NORMAL) { if (inCommandPayload > COMMAND_BUFFER_SIZE/2) { // String way too long, see SerialManager.h ch = '>'; // we end this nonsense inCommandPayload = PAYLOAD_NORMAL; DIAG(F("Parse error: Unbalanced string")); // fall through to ending parsing below } else if (ch == '"') { // String end inCommandPayload = PAYLOAD_NORMAL; continue; // do not fall through } else inCommandPayload++; } if (inCommandPayload == PAYLOAD_NORMAL) { if (ch == '>') { buffer[bufferLength] = '\0'; // This \0 is after the '>' DCCEXParser::parse(serial, buffer, NULL); // buffer parsed with trailing '>' inCommandPayload = PAYLOAD_FALSE; break; } else if (ch == '"') { inCommandPayload = PAYLOAD_STRING; } } } else { DIAG(F("Parse error: input buffer overflow")); inCommandPayload = PAYLOAD_FALSE; } } } } ================================================ FILE: SerialManager.h ================================================ /* * © 2021 Chris Harlow * All rights reserved. * * 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 . */ #ifndef SerialManager_h #define SerialManager_h #include "Arduino.h" #include "defines.h" // We size this to keep max two commands of maximum lenght // in the COMMAND_BUFFER. Most commands are shorter, the // can be 106 bytes. We do not // support that on AVR // AVR: 32bytes+32bytes // // Other: 128bytes+128bytes // #ifndef COMMAND_BUFFER_SIZE #ifdef ARDUINO_ARCH_AVR #define COMMAND_BUFFER_SIZE 64 #else #define COMMAND_BUFFER_SIZE 256 #endif #endif class SerialManager { public: static void init(); static void loop(); static void broadcast(char * stringBuffer); private: static SerialManager * first; SerialManager(Stream * myserial); void loop2(); void broadcast2(char * stringBuffer); Stream * serial; SerialManager * next; byte bufferLength; byte buffer[COMMAND_BUFFER_SIZE]; byte inCommandPayload; }; #endif ================================================ FILE: SerialUsbLog.cpp ================================================ /* * © 2026 Chris Harlow * © 2026 Paul M. Antoine * All rights reserved. * * This file is part of DCC-EX 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 . */ /* * SerialUsbLog.cpp * * This code acts as a serial output log collector. * This is pointed to by defines.h as the USB_SERIAL object so that the remainder * of the code does not have to be aware of the difference. * * All output to the serial log is collected in a rolling buffer that can be: * - dumped as a one-shot stream (streamOut) * - or streamed incrementally via a lightweight HTTP endpoint * * ESP32 Web UI improvements: * - Small HTML “console” page at "/" (no giant page reloads) * - Incremental log feed at "/log?from=&chunk= * - Nicer UX: Follow (tail) behaviour only when user is at bottom, Pause/Resume, * Wrap toggle, Clear, Copy, simple Filter. * * Notes: * - For incremental output, the buffer includes < > & chars as plain text */ #include "defines.h" #ifdef ENABLE_SERIAL_LOG // This entire file is ignored if ENABLE_SERIAL_LOG is not defined in defines.h. #include "Arduino.h" #include "DIAG.h" #include "SerialUsbLog.h" #include "StringBuffer.h" #include "DCCEXParser.h" #if WIFI_ON #include WiFiServer server(80); #else #include EthernetServer server(80); #endif #include "SerialUsbLog.h" // Log buffer size. You you have RAM to spare on thyese devices, so feel free to bump this. // Keep it sensible; very large buffers make /dump and filter operations heavier. #ifndef LOG_BUFFER #define LOG_BUFFER 8192 #endif // Maximum bytes returned per /log request (upper safety bound) #ifndef LOG_CHUNK_MAX #define LOG_CHUNK_MAX 1000 #endif // Global instance SerialUsbLog SerialLog(LOG_BUFFER, &Serial); StringBuffer dummyClient(2048); // buffering client for response construction // --------------------------- Small helpers (ESP32 only) --------------------------- static inline bool startsWithNoCase(const String& s, const char* prefix) { int n = (int)strlen(prefix); if ((int)s.length() < n) return false; for (int i = 0; i < n; i++) { char a = s[i]; char b = prefix[i]; if (a >= 'A' && a <= 'Z') a = (char)(a - 'A' + 'a'); if (b >= 'A' && b <= 'Z') b = (char)(b - 'A' + 'a'); if (a != b) return false; } return true; } static String urlPathOnly(const String& uri) { int q = uri.indexOf('?'); return (q >= 0) ? uri.substring(0, q) : uri; } static String queryParamRaw(const String& uri, const char* key, String defaultValue) { int q = uri.indexOf('?'); if (q < 0) return defaultValue; String qs = uri.substring(q + 1); String k = String(key) + "="; int p = qs.indexOf(k); if (p < 0) return defaultValue; int vStart = p + k.length(); int amp = qs.indexOf('&', vStart); String v = (amp >= 0) ? qs.substring(vStart, amp) : qs.substring(vStart); v.trim(); if (!v.length()) return defaultValue; return v; } static int queryParamInt(const String& uri, const char* key, int defaultValue) { String v = queryParamRaw(uri, key, ""); if (v.length() == 0) return defaultValue; return v.toInt(); } static String uriDecode(const String& str) { String result; for (int i = 0; i < str.length(); i++) { if (str[i] == '%' && i + 2 < str.length()) { // hex decode: %20 → space, %2B → + char hex[3] = { str[i+1], str[i+2], 0 }; char c = (char)strtol(hex, NULL, 16); result += c; i += 2; } else if (str[i] == '+') { result += ' '; } else { result += str[i]; } } return result; } static String queryParamString(const String& uri, const char* key, String defaultValue) { String v = queryParamRaw(uri, key, ""); if (v.length() == 0) return defaultValue; return uriDecode(v); } static void drainHttpHeaders(Client& client) { // Read until blank line. Keep it short to avoid blocking too long. uint32_t start = millis(); while (client.connected() && (millis() - start) < 50) { String line = client.readStringUntil('\n'); if (line.length() == 0 || line == "\r") break; } } /** * Constructor * @param len Maximum length of the log buffer * @param serialPort underlying serial port (eg. &Serial) */ SerialUsbLog::SerialUsbLog(const uint16_t len, HardwareSerial* serialPort) { _bufferSize = len; _buffer = new byte[len]; _pos_write = 0; _overflow = false; _serialPort = serialPort; // Monotonic write sequence counter (increments per byte stored into the ring). _seq_write = 0; } /** * Write a single byte to the log buffer and to the underlying serial port. */ size_t SerialUsbLog::write(uint8_t b) { _serialPort->write(b); // Store directly (no translation) shoveToBuffer(b); return 1; } /** * Internal ring-buffer write (single byte). * On ESP32 we guard ring/seq updates with a critical section. */ void SerialUsbLog::shoveToBuffer(uint8_t b) { // #if defined(ARDUINO_ARCH_ESP32) // portENTER_CRITICAL(&_mux); // #endif if (_pos_write >= _bufferSize) { _overflow = true; _pos_write = 0; } _buffer[_pos_write++] = b; _seq_write++; // #if defined(ARDUINO_ARCH_ESP32) // portEXIT_CRITICAL(&_mux); // #endif } /** * Stream the entire log buffer contents to a target Print stream. * This is the legacy one-shot dump of the current ring buffer snapshot. */ void SerialUsbLog::streamOut(Print* targetStream) { if (targetStream == nullptr) return; // #if defined(ARDUINO_ARCH_ESP32) // portENTER_CRITICAL(&_mux); // #endif if (_overflow) { // output from current position to end, then start to current position targetStream->write(_buffer + _pos_write, _bufferSize - _pos_write); targetStream->write(_buffer, _pos_write); } else { targetStream->write(_buffer, _pos_write); } // #if defined(ARDUINO_ARCH_ESP32) // portEXIT_CRITICAL(&_mux); // #endif } /** * Return current write sequence number. * (Monotonic counter of bytes written into the ring.) */ uint32_t SerialUsbLog::getWriteSeq() const { return _seq_write; } /** * Stream from a given sequence number up to maxBytes (incremental streaming). * * fromSeq: * - Client's last seen sequence number. * - If too old, we fast-forward to earliest available. * * nextSeq (out): * - Updated sequence number after streaming. * * Returns: * - Number of bytes written to targetStream. */ size_t SerialUsbLog::streamOutFrom(Print* targetStream, uint32_t fromSeq, size_t maxBytes, uint32_t& nextSeq) { if (!targetStream) { nextSeq = fromSeq; return 0; } // #if defined(ARDUINO_ARCH_ESP32) // portENTER_CRITICAL(&_mux); // #endif const uint32_t writeSeq = _seq_write; const uint32_t earliest = (writeSeq > (uint32_t)_bufferSize) ? (writeSeq - (uint32_t)_bufferSize) : 0; uint32_t start = fromSeq; if (start < earliest) start = earliest; if (start > writeSeq) start = writeSeq; uint32_t available = writeSeq - start; if (available > (uint32_t)maxBytes) available = (uint32_t)maxBytes; for (uint32_t s = 0; s < available; s++) { const uint32_t seq = start + s; const uint32_t pos = seq % (uint32_t)_bufferSize; targetStream->write(_buffer[pos]); } nextSeq = start + available; // #if defined(ARDUINO_ARCH_ESP32) // portEXIT_CRITICAL(&_mux); // #endif return (size_t)available; } // begin() shim void SerialUsbLog::begin(unsigned long baud) { _serialPort->begin(baud); } // while(!Serial) shim bool SerialUsbLog::operator!() const { return _serialPort == nullptr; } // available() shim int SerialUsbLog::available() { return _serialPort->available(); } // read() shim int SerialUsbLog::read() { return _serialPort->read(); } // peek() shim int SerialUsbLog::peek() { return _serialPort->peek(); } /** * Lightweight HTTP server loop * * Endpoints: * - GET / : HTML log console (polling) * - GET /log?from=N&chunk=M : returns text/plain chunk and X-Next-Seq header */ void SerialUsbLog::loop() { static bool started = false; if (!started) { server.begin(); started = true; return; } auto client = server.available(); if (!client) return; // Read request line: "GET /path?... HTTP/1.1" String reqLine = client.readStringUntil('\r'); if (reqLine.length() == 0) { client.stop(); return; } if (Diag::WIFI || Diag::ETHERNET) { StringFormatter::send(_serialPort,F("<* http: %s *>\n"), reqLine.c_str()); } int sp1 = reqLine.indexOf(' '); int sp2 = reqLine.indexOf(' ', sp1 + 1); if (sp1 < 0 || sp2 < 0) { client.stop(); return; } String method = reqLine.substring(0, sp1); String uri = reqLine.substring(sp1 + 1, sp2); String path = urlPathOnly(uri); // Drain the rest of the headers to keep the TCP state clean-ish. drainHttpHeaders(client); dummyClient.flush(); if (method != "GET") { dummyClient.println( "HTTP/1.1 405 Method Not Allowed\r\n" "Connection: close\r\n\r\n" ); } // ----------------------------- /log incremental feed ----------------------------- else if (path == "/log") { String cmd= queryParamString(uri, "cmd", ""); if (cmd.length()>0) { DCCEXParser::parse(cmd.c_str()); } uint32_t from = (uint32_t)queryParamInt(uri, "from", 0); int chunk = queryParamInt(uri, "chunk", 1024); if (chunk < 64) chunk = 64; if (chunk > LOG_CHUNK_MAX) chunk = LOG_CHUNK_MAX; // Compute next seq (for header) using the same logic as streamOutFrom. uint32_t writeSeq = SerialLog.getWriteSeq(); uint32_t earliest = (writeSeq > (uint32_t)_bufferSize) ? (writeSeq - (uint32_t)_bufferSize) : 0; uint32_t start = from; if (start < earliest) start = earliest; if (start > writeSeq) start = writeSeq; uint32_t avail = writeSeq - start; if (avail > (uint32_t)chunk) avail = (uint32_t)chunk; uint32_t next = start + avail; dummyClient.print( "HTTP/1.1 200 OK\r\n" "Content-Type: text/plain; charset=utf-8\r\n" "Cache-Control: no-store\r\n" "Connection: close\r\n" "X-Next-Seq: " ); dummyClient.print(next); dummyClient.print("\r\n\r\n"); uint32_t nextSeqOut = from; SerialLog.streamOutFrom(&dummyClient, from, (size_t)chunk, nextSeqOut); } // --------------------------------- / HTML shell --------------------------------- else if (path == "/" ) { dummyClient.print( "HTTP/1.1 200 OK\r\n" "Content-Type: text/html; charset=utf-8\r\n" "Cache-Control: no-store\r\n" "Connection: close\r\n\r\n" #include "SerialUsbLog.html.h" ); } else if (path == "/style.css" ) { dummyClient.print( "HTTP/1.1 200 OK\r\n" "Content-Type: text/css; charset=utf-8\r\n" "Cache-Control: no-store\r\n" "Connection: close\r\n\r\n" #include "SerialUsbLog.style.css.h" ); } else if (path == "/script1.js" ) { dummyClient.print( "HTTP/1.1 200 OK\r\n" "Content-Type: text/javascript; charset=utf-8\r\n" "Cache-Control: no-store\r\n" "Connection: close\r\n\r\n" #include "SerialUsbLog.script1.js.h" ); } else if (path == "/script2.js" ) { dummyClient.print( "HTTP/1.1 200 OK\r\n" "Content-Type: text/javascript; charset=utf-8\r\n" "Cache-Control: no-store\r\n" "Connection: close\r\n\r\n" #include "SerialUsbLog.script2.js.h" ); } else { // --------------------------------- 404 --------------------------------- dummyClient.print( "HTTP/1.1 404 Not Found\r\n" "Connection: close\r\n\r\n" ); } if (Diag::WIFI || Diag::ETHERNET) { StringFormatter::send(_serialPort,F("<* http:replyLength %d *>\n"), dummyClient.getLength()); } client.print(dummyClient.getString()); client.stop(); } // --------------------------- End of SerialUsbLog.cpp --------------------------- #endif // ENABLE_SERIAL_LOG ================================================ FILE: SerialUsbLog.h ================================================ /* * © 2026 Chris Harlow * © 2026 Paul M. Antoine * All rights reserved. * * This file is part of DCC-EX 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 . */ #ifdef ENABLE_SERIAL_LOG #ifndef SerialUsbLog_h #define SerialUsbLog_h #include #include "FSH.h" class SerialUsbLog : public Stream { public: SerialUsbLog( const uint16_t len, HardwareSerial* serialPort ); void begin( unsigned long baud ); virtual size_t write(uint8_t b); using Print::write; void streamOut(Print * targetStream); // NEW: incremental streaming support uint32_t getWriteSeq() const; size_t streamOutFrom(Print* targetStream, uint32_t fromSeq, size_t maxBytes, uint32_t& nextSeq); bool operator!() const; void shoveToBuffer(uint8_t b); virtual int available(); virtual int read(); virtual int peek(); void loop(); private: HardwareSerial * _serialPort; int _pos_write; bool _overflow; byte * _buffer; int _bufferSize; // NEW volatile uint32_t _seq_write; #if defined(ARDUINO_ARCH_ESP32) // protect buffer/seq from concurrent access portMUX_TYPE _mux = portMUX_INITIALIZER_UNLOCKED; #endif }; extern SerialUsbLog SerialLog; #endif #endif // ENABLE_SERIAL_LOG ================================================ FILE: SerialUsbLog.html.h ================================================ R"???( DCC-EX Server Log

DCC-EX Server Log

Command:
)???" ================================================ FILE: SerialUsbLog.script1.js.h ================================================ R"???( function dog(tag) {return document.getElementById(tag);} const logEl=dog('log'); const pauseBtn=dog('pause'); const clearBtn=dog('clear'); const wrapCb=dog('wrap'); const followCb=dog('follow'); const filterIn=dog('filter'); const stat=dog('stat'); const cmdInput = dog('cmd'); const cmdButton = dog('cmdButton'); let paused=false, seq=0, buf='',cmdWaiting=false; let userScrolled=false; function atBottom(){return (logEl.scrollHeight-logEl.scrollTop-logEl.clientHeight)<8;} logEl.addEventListener('scroll',()=>{userScrolled=!atBottom();}); wrapCb.addEventListener('change',()=>{logEl.style.whiteSpace=wrapCb.checked?'pre-wrap':'pre';}); pauseBtn.onclick=()=>{paused=!paused; pauseBtn.textContent=paused?'Resume':'Pause';}; clearBtn.onclick=()=>{buf=''; logEl.value=''; seq=0;}; cmdButton.onclick=()=>{cmdWaiting=true;}; function applyFilter(text){ const f=filterIn.value.trim(); if(!f) return text; return text.split('\n').filter(l=>l.includes(f)).join('\n'); } filterIn.addEventListener('input',()=>{logEl.value=applyFilter(buf); if(followCb.checked&&!userScrolled){logEl.scrollTop=logEl.scrollHeight;}}); cmdInput?.addEventListener('keydown', e=>{ if(e.key==='Enter'){ e.preventDefault(); cmdButton.click(); }}); )???" ================================================ FILE: SerialUsbLog.script2.js.h ================================================ R"???( async function tick(){ try{ if(!paused && logEl.selectionStart===logEl.selectionEnd){ const chunk=2048; let cmd=cmdWaiting ? cmdInput.value.trim() : ''; cmdWaiting=false; if (cmd.length>0 && cmd[0]!='<') cmd='<' + cmd + '>'; const cmdpart = cmd.length>0 ? ("&cmd="+encodeURIComponent(cmd)) : ""; const uri='/log?from='+seq+'&chunk='+chunk+cmdpart; console.log("Fetching URI:", uri); const r=await fetch(uri,{cache:'no-store'}); if(r.ok){ const t=await r.text(); const nxt=r.headers.get('X-Next-Seq'); if(nxt) seq=parseInt(nxt,10)||seq; if(t && t.length){ buf+=t; logEl.textContent=applyFilter(buf); if(followCb.checked&&!userScrolled) logEl.scrollTop=logEl.scrollHeight; } stat.textContent=(paused?'paused':'live')+' • seq '+seq+' • '+buf.length+' chars'; } else { stat.textContent='http '+r.status; } } else { stat.textContent='paused • seq '+seq+' • '+buf.length+' chars'; } }catch(e){ stat.textContent='offline'; } setTimeout(tick, 400); } tick(); )???" ================================================ FILE: SerialUsbLog.style.css.h ================================================ R"???( html,body{height:100%;margin:0;font-family:system-ui,-apple-system,Segoe UI,Roboto,Arial} body{background:#0f1115;color:#d7dae0;display:flex;flex-direction:column} header{display:flex;flex-wrap:wrap;gap:.5rem;align-items:center;padding:.6rem .75rem;border-bottom:1px solid #2a2d34} header h1{font-size:1rem;margin:0;flex:1;min-width:220px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis} button,input,textarea,label,a.btn{background:#181a1f;color:#d7dae0;border:1px solid #2a2d34;border-radius:10px;padding:.35rem .6rem;text-decoration:none} button:hover,input:hover,label:hover,a.btn:hover{border-color:#3a3f4a} #wrapLbl{display:flex;align-items:center;gap:.35rem;opacity:.9} #followLbl{display:flex;align-items:center;gap:.35rem;opacity:.9} #log{flex:1;overflow:auto;padding:.75rem;font:12px/1.35 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;white-space:pre;tab-size:2} #stat{opacity:.75;font-size:.85rem;min-width:160px;text-align:right} .dim{opacity:.75} )???" ================================================ FILE: Sniffer.cpp ================================================ /* * © 2025 Harald Barth * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifdef ARDUINO_ARCH_ESP32 #include "Sniffer.h" #include "DIAG.h" //extern Sniffer *DCCSniffer; static void packeterror() { #ifndef WIFI_LED #ifdef SNIFFER_LED digitalWrite(SNIFFER_LED,HIGH); #endif #endif } static void clear_packeterror() { #ifndef WIFI_LED #ifdef SNIFFER_LED digitalWrite(SNIFFER_LED,LOW); #endif #endif } static bool halfbits2byte(uint16_t b, byte *dccbyte) { /* if (b!=0 && b!=0xFFFF) { Serial.print("[ "); for(int n=0; n<16; n++) { Serial.print(b&(1<>2; } return true; } static void IRAM_ATTR blink_diag(int limit) { #ifndef WIFI_LED #ifdef SNIFFER_LED delay(500); for (int n=0 ; ncap_edge == MCPWM_BOTH_EDGE) { // should not happen at all // delays here might crash sketch blink_diag(2); return 0; } if (user_data) ((Sniffer *)user_data)->processInterrupt(edata->cap_value, edata->cap_edge == MCPWM_POS_EDGE); //if (DCCSniffer) DCCSniffer->processInterrupt(edata->cap_value, edata->cap_edge == MCPWM_POS_EDGE); return 0; } Sniffer::Sniffer(byte snifferpin) { mcpwm_gpio_init(MCPWM_UNIT_0, MCPWM_CAP_0, snifferpin); // set capture edge, BIT(0) - negative edge, BIT(1) - positive edge // MCPWM_POS_EDGE|MCPWM_NEG_EDGE should be 3. //mcpwm_capture_enable(MCPWM_UNIT_0, MCPWM_SELECT_CAP0, MCPWM_POS_EDGE|MCPWM_NEG_EDGE, 0); //mcpwm_isr_register(MCPWM_UNIT_0, sniffer_isr_handler, NULL, ESP_INTR_FLAG_IRAM, NULL); //MCPWM0.int_ena.cap0_int_ena = 1; // Enable interrupt on CAP0 signal mcpwm_capture_config_t MCPWM_cap_config = { //Capture channel configuration .cap_edge = MCPWM_BOTH_EDGE, // according to mcpwm.h .cap_prescale = 1, // 1 to 256 (see .h file) .capture_cb = cap_ISR_cb, // user defined ISR/callback .user_data = (void *)this // user defined argument to callback }; #ifndef WIFI_LED #ifdef SNIFFER_LED pinMode(SNIFFER_LED ,OUTPUT); #endif #endif blink_diag(3); // so that we know we have SNIFFER_LED DIAG(F("Init sniffer on pin %d"), snifferpin); ESP_ERROR_CHECK(mcpwm_capture_enable_channel(MCPWM_UNIT_0, MCPWM_SELECT_CAP0, &MCPWM_cap_config)); } #define SNIFFER_TIMEOUT 100L // 100 Milliseconds bool Sniffer::inputActive(){ unsigned long now = millis(); return ((now - lastendofpacket) < SNIFFER_TIMEOUT); } #define DCC_TOO_SHORT 4000L // 4000 ticks are 50usec #define DCC_ONE_LIMIT 6400L // 6400 ticks are 80usec void IRAM_ATTR Sniffer::processInterrupt(int32_t capticks, bool posedge) { byte bit = 0; diffticks = capticks - lastticks; if (lastedge != posedge) { if (diffticks < DCC_TOO_SHORT) { return; } if (diffticks < DCC_ONE_LIMIT) { bit = 1; } else { bit = 0; } // update state variables for next round lastticks = capticks; lastedge = posedge; bitfield = bitfield << (uint64_t)1; bitfield = bitfield + (uint64_t)bit; // now the halfbit is in the bitfield. Analyze... if ((bitfield & 0xFFFFFF) == 0xFFFFFC){ // This looks at the 24 last halfbits // and detects a preamble if // 22 are ONE and 2 are ZERO which is a // preabmle of 11 ONES and one ZERO if (inpacket) { // if we are already inpacket here we // got a preamble in the middle of a // packet packeterror(); } else { clear_packeterror(); // everything fine again at end of preable after good packet } currentbyte = 0; dcclen = 0; inpacket = true; halfbitcounter = 18; // count 18 steps from 17 to 0 and then look at the byte return; } if (inpacket) { halfbitcounter--; if (halfbitcounter) { return; // wait until we have full byte } else { // have reached end of byte //if (currentbyte == 2) debugfield = bitfield; byte twohalfbits = bitfield & 0x03; switch (twohalfbits) { case 0x01: case 0x02: // broken bits inpacket = false; packeterror(); return; break; case 0x00: case 0x03: // byte end uint16_t b = (bitfield & 0x3FFFF)>>2; // take 18 halfbits and use 16 of them if (!halfbits2byte(b, dccbytes + currentbyte)) { // broken halfbits inpacket = false; packeterror(); return; } if (twohalfbits == 0x03) { // end of packet marker inpacket = false; dcclen = currentbyte+1; debugfield = bitfield; // We have something we want to give to the outpacket queue // Check length of outpacket queue if (outpacket.size() > 3) { // not good, these should have been fetched // the arbitraty number to check is THREE (see the holy grail) // blink_diag(1); DO NOT DO THIS HERE -> will crash packeterror(); // or what to do better? // take emergency action: while (!outpacket.empty()) { outpacket.pop_front(); } } lastendofpacket = millis(); DCCPacket temppacket(dccbytes, dcclen); if (!(temppacket == prevpacket)) { // we have something new to offer to the fetch routine // put it into the outpacket queue outpacket.push_back(temppacket); prevpacket = temppacket; } return; } break; } halfbitcounter = 18; currentbyte++; // everything done for this end of byte if (currentbyte >= MAXDCCPACKETLEN) { inpacket = false; // this is an error because we should have retured above packeterror(); // when endof packet marker was active } } } } else { // lastedge == posedge // this should not happen, check later } } /* static void IRAM_ATTR sniffer_isr_handler(void *) { DCCSniffer.processInterrupt(); } */ #endif // ESP32 ================================================ FILE: Sniffer.h ================================================ /* * © 2025 Harald Barth * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifdef ARDUINO_ARCH_ESP32 #include #include #include "driver/mcpwm.h" #include "soc/mcpwm_struct.h" #include "soc/mcpwm_reg.h" #define MAXDCCPACKETLEN 8 #include "DCCPacket.h" class Sniffer { public: Sniffer(byte snifferpin); void IRAM_ATTR processInterrupt(int32_t capticks, bool posedge); inline int32_t getTicks() { noInterrupts(); int32_t i = diffticks; interrupts(); return i; }; inline int64_t getDebug() { noInterrupts(); int64_t i = debugfield; interrupts(); return i; }; inline DCCPacket fetchPacket() { // if there is no new data, this will create a // packet with length 0 (which is no packet) DCCPacket p; noInterrupts(); if (!outpacket.empty()) { p = outpacket.front(); outpacket.pop_front(); } interrupts(); return p; }; bool inputActive(); private: // keep these vars in processInterrupt only uint64_t bitfield = 0; uint64_t debugfield = 0; int32_t diffticks; int32_t lastticks; bool lastedge; byte currentbyte = 0; byte dccbytes[MAXDCCPACKETLEN]; byte dcclen = 0; bool inpacket = false; // these vars are used as interface to other parts of sniffer byte halfbitcounter = 0; std::list outpacket; DCCPacket prevpacket; volatile unsigned long lastendofpacket = 0; // timestamp millis }; #endif ================================================ FILE: Stash.cpp ================================================ /* * © 2024 Chris Harlow * All rights reserved. * * 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 . */ #include "Stash.h" #include "StringFormatter.h" Stash::Stash(int16_t stash_id, int16_t loco_id) { this->stashId = stash_id; this->locoId = loco_id; this->next = first; first = this; } void Stash::clearAll() { for (auto s=first;s;s=s->next) { s->locoId = 0; s->stashId =0; } } void Stash::clearAny(int16_t loco_id) { auto lid=abs(loco_id); for (auto s=first;s;s=s->next) if (abs(s->locoId) == lid) { s->locoId = 0; s->stashId =0; } } void Stash::clear(int16_t stash_id) { set(stash_id,0); } int16_t Stash::get(int16_t stash_id) { for (auto s=first;s;s=s->next) if (s->stashId == stash_id) return s->locoId; return 0; } void Stash::set(int16_t stash_id, int16_t loco_id) { // replace any existing stash for (auto s=first;s;s=s->next) if (s->stashId == stash_id) { s->locoId=loco_id; if (loco_id==0) s->stashId=0; // recycle return; } if (loco_id==0) return; // no need to create a zero entry. // replace any empty stash for (auto s=first;s;s=s->next) if (s->locoId == 0) { s->locoId=loco_id; s->stashId=stash_id; return; } // create a new stash new Stash(stash_id, loco_id); } void Stash::list(Print * stream, int16_t stash_id) { bool sent=false; for (auto s=first;s;s=s->next) if ((s->locoId) && (stash_id==0 || s->stashId==stash_id)) { StringFormatter::send(stream,F("\n"), s->stashId,s->locoId); sent=true; } if (!sent) StringFormatter::send(stream,F("\n"), stash_id); } Stash* Stash::first=nullptr; ================================================ FILE: Stash.h ================================================ /* * © 2024 Chris Harlow * All rights reserved. * * 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 . */ #ifndef Stash_h #define Stash_h #include class Stash { public: static void clear(int16_t stash_id); static void clearAll(); static void clearAny(int16_t loco_id); static int16_t get(int16_t stash_id); static void set(int16_t stash_id, int16_t loco_id); static void list(Print * stream, int16_t stash_id=0); // id0 = LIST ALL private: Stash(int16_t stash_id, int16_t loco_id); static Stash* first; Stash* next; int16_t stashId; int16_t locoId; }; #endif ================================================ FILE: StringBuffer.cpp ================================================ /* * © 2022 Chris Harlow * All rights reserved. * * This file is part of DCC-EX 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 . */ #include "StringBuffer.h" #include "DIAG.h" StringBuffer::StringBuffer(int16_t size) { _buffer_max=size-2; // max write offset, allowing for null terminator _buffer=new char[size]; flush(); }; StringBuffer::~StringBuffer() { delete[] _buffer; } char * StringBuffer::getString() { return _buffer; } int16_t StringBuffer::getLength() { return _pos_write; } void StringBuffer::flush() { _pos_write=0; _buffer[0]='\0'; } size_t StringBuffer::write(uint8_t b) { if (_pos_write>=_buffer_max) return 0; // max allows for 2 chars. _buffer[_pos_write] = b; ++_pos_write; _buffer[_pos_write]='\0'; return 1; } ================================================ FILE: StringBuffer.h ================================================ /* * © 2022 Chris Harlow * All rights reserved. * * 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 . */ #ifndef StringBuffer_h #define StringBuffer_h #include class StringBuffer : public Print { public: StringBuffer(int16_t size=64); ~StringBuffer(); // Override Print default virtual size_t write(uint8_t b); void flush(); char * getString(); int16_t getLength(); private: int16_t _buffer_max; int16_t _pos_write; char * _buffer; }; #endif ================================================ FILE: StringFormatter.cpp ================================================ /* * © 2020=2025, Chris Harlow. 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 . */ #include "StringFormatter.h" #include #include "DisplayInterface.h" #include "CommandDistributor.h" bool Diag::ACK=false; bool Diag::CMD=false; bool Diag::WIFI=false; bool Diag::WITHROTTLE=false; bool Diag::ETHERNET=false; bool Diag::LCN=false; bool Diag::RAILCOM=false; bool Diag::WEBSOCKET=false; bool Diag::SNIFFER=false; void StringFormatter::diag( const FSH* input...) { USB_SERIAL.print(F("<* ")); va_list args; va_start(args, input); send2(&USB_SERIAL,input,args); USB_SERIAL.print(F(" *>\n")); } void StringFormatter::lcd(byte row, const FSH* input...) { va_list args; #ifndef DISABLE_VDPY Print * virtualLCD=CommandDistributor::getVirtualLCDSerial(0,row); #else Print * virtualLCD=NULL; #endif // Issue the LCD as a diag first // Unless the same serial is asking for the virtual @ respomnse if (virtualLCD!=&USB_SERIAL) { send(&USB_SERIAL,F("<* LCD%d:"),row); va_start(args, input); send2(&USB_SERIAL,input,args); send(&USB_SERIAL,F(" *>\n")); } #ifndef DISABLE_VDPY // send to virtual LCD collector (if any) if (virtualLCD) { va_start(args, input); send2(virtualLCD,input,args); CommandDistributor::commitVirtualLCDSerial(); } #endif DisplayInterface::setRow(row); va_start(args, input); send2(DisplayInterface::getDisplayHandler(),input,args); } void StringFormatter::lcd2(uint8_t display, byte row, const FSH* input...) { va_list args; // send to virtual LCD collector (if any) #ifndef DISABLE_VDPY Print * virtualLCD=CommandDistributor::getVirtualLCDSerial(display,row); if (virtualLCD) { va_start(args, input); send2(virtualLCD,input,args); CommandDistributor::commitVirtualLCDSerial(); } #endif DisplayInterface::setRow(display, row); va_start(args, input); send2(DisplayInterface::getDisplayHandler(),input,args); } void StringFormatter::send(Print * stream, const FSH* input...) { va_list args; va_start(args, input); send2(stream,input,args); } void StringFormatter::send(Print & stream, const FSH* input...) { va_list args; va_start(args, input); send2(&stream,input,args); } void StringFormatter::send2(Print * stream,const FSH* format, va_list args) { // thanks to Jan Turoň https://arduino.stackexchange.com/questions/56517/formatting-strings-in-arduino-for-output char* flash=(char*)format; for(int i=0; ; ++i) { char c=GETFLASH(flash+i); if (c=='\0') break; // to va_end() if(c!='%') { stream->print(c); continue; } bool formatContinues=false; byte formatWidth=0; bool formatLeft=false; do { formatContinues=false; i++; c=GETFLASH(flash+i); switch(c) { case '%': stream->print('%'); break; case 'c': stream->print((char) va_arg(args, int)); break; case 's': stream->print(va_arg(args, char*)); break; case 'e': printEscapes(stream,va_arg(args, char*)); break; case 'E': printEscapes(stream,(const FSH*)va_arg(args, char*)); break; case 'S': { const FSH* flash= (const FSH*)va_arg(args, char*); #if WIFI_ON | ETHERNET_ON // RingStream has special logic to handle flash strings // but is not implemented unless wifi or ethernet are enabled. // The define prevents RingStream code being added unnecessariliy. if (stream->availableForWrite()==RingStream::THIS_IS_A_RINGSTREAM) ((RingStream *)stream)->printFlash(flash); else #endif stream->print(flash); break; } case 'P': stream->print((uint32_t)va_arg(args, void*), HEX); break; case 'd': printPadded(stream,va_arg(args, int), formatWidth, formatLeft); break; case 'u': printPadded(stream,va_arg(args, unsigned int), formatWidth, formatLeft); break; case 'l': printPadded(stream,va_arg(args, long), formatWidth, formatLeft); break; case 'L': stream->print(va_arg(args, unsigned long), DEC); break; case 'b': stream->print(va_arg(args, int), BIN); break; case 'o': stream->print(va_arg(args, int), OCT); break; case 'x': stream->print((unsigned int)va_arg(args, unsigned int), HEX); break; case 'X': stream->print((unsigned long)va_arg(args, unsigned long), HEX); break; case 'h': printHex(stream,(unsigned int)va_arg(args, unsigned int)); break; case 'M': { // this prints a unsigned long microseconds time in readable format unsigned long time = va_arg(args, long); if (time >= 2000) { time = time / 1000; if (time >= 2000) { printPadded(stream, time/1000, formatWidth, formatLeft); stream->print(F("sec")); } else { printPadded(stream,time, formatWidth, formatLeft); stream->print(F("msec")); } } else { printPadded(stream,time, formatWidth, formatLeft); stream->print(F("usec")); } } break; //case 'f': stream->print(va_arg(args, double), 2); break; //format width prefix case '-': formatLeft=true; formatContinues=true; break; case '0': case '1': case '2': case '3': case '4': case '5': case '6': case '7': case '8': case '9': formatWidth=formatWidth * 10 + (c-'0'); formatContinues=true; break; } } while(formatContinues); } va_end(args); } void StringFormatter::printEscapes(Print * stream,char * input) { if (!stream) return; for(int i=0; ; ++i) { char c=input[i]; printEscape(stream,c); if (c=='\0') return; } } void StringFormatter::printEscapes(Print * stream, const FSH * input) { if (!stream) return; char* flash=(char*)input; for(int i=0; ; ++i) { char c=GETFLASH(flash+i); printEscape(stream,c); if (c=='\0') return; } } void StringFormatter::printEscape( char c) { printEscape(&USB_SERIAL,c); } void StringFormatter::printEscape(Print * stream, char c) { if (!stream) return; switch(c) { case '\n': stream->print(F("\\n")); break; case '\r': stream->print(F("\\r")); break; case '\0': stream->print(F("\\0")); return; case '\t': stream->print(F("\\t")); break; case '\\': stream->print(F("\\\\")); break; default: stream->write(c); } } void StringFormatter::printPadded(Print* stream, long value, byte width, bool formatLeft) { if (width==0) { stream->print(value, DEC); return; } int digits=(value <= 0)? 1: 0; // zero and negative need extra digot long v=value; while (v) { v /= 10; digits++; } if (formatLeft) stream->print(value, DEC); while(digitsprint(' '); digits++; } if (!formatLeft) stream->print(value, DEC); } // printHex prints the full 2 byte hex with leading zeros, unlike print(value,HEX) const char FLASH hexchars[]="0123456789ABCDEF"; void StringFormatter::printHex(Print * stream,uint16_t value) { char result[5]; for (int i=3;i>=0;i--) { result[i]=GETFLASH(hexchars+(value & 0x0F)); value>>=4; } result[4]='\0'; stream->print(result); } ================================================ FILE: StringFormatter.h ================================================ /* * © 2020-2025, Chris Harlow. 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 . */ #ifndef StringFormatter_h #define StringFormatter_h #include #include "FSH.h" #include "RingStream.h" #include "Display.h" class Diag { public: static bool ACK; static bool CMD; static bool WIFI; static bool WITHROTTLE; static bool ETHERNET; static bool LCN; static bool RAILCOM; static bool WEBSOCKET; static bool SNIFFER; }; class StringFormatter { public: static void send(Print * serial, const FSH* input...); static void send(Print & serial, const FSH* input...); static void printEscapes(Print * serial,char * input); static void printEscapes(Print * serial,const FSH* input); static void printEscape(Print * serial, char c); // DIAG support static void diag( const FSH* input...); static void lcd(byte row, const FSH* input...); static void lcd2(uint8_t display, byte row, const FSH* input...); static void printEscapes(char * input); static void printEscape( char c); static void printHex(Print * stream,uint16_t value); private: static void send2(Print * serial, const FSH* input,va_list args); static void printPadded(Print* stream, long value, byte width, bool formatLeft); }; #endif ================================================ FILE: TemplateForEnums.h ================================================ /* * © 2024, Harald Barth. All rights reserved. * * 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 . */ #ifndef TemplateForEnums #define TemplateForEnums template inline T operator~ (T a) { return (T)~(int)a; } template inline T operator| (T a, T b) { return (T)((int)a | (int)b); } template inline T operator& (T a, T b) { return (T)((int)a & (int)b); } template inline T operator^ (T a, T b) { return (T)((int)a ^ (int)b); } #endif ================================================ FILE: TrackManager.cpp ================================================ /* * © 2022-2025 Chris Harlow * © 2022-2024 Harald Barth * © 2023-2024 Paul M. Antoine * © 2024-2025 Herb Morton * © 2023 Colin Murdoch * All rights reserved. * * 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 . */ #include "defines.h" #include "TrackManager.h" #include "FSH.h" #include "DCCWaveform.h" #include "DCC.h" #include "MotorDriver.h" #include "DCCTimer.h" #include "DIAG.h" #include "CommandDistributor.h" #include "DCCEXParser.h" #include "KeywordHasher.h" // Virtualised Motor shield multi-track hardware Interface #define FOR_EACH_TRACK(t) for (byte t=0;t<=lastTrack;t++) #define APPLY_BY_MODE(findmode,function) \ FOR_EACH_TRACK(t) \ if (track[t]->getMode() & findmode) \ track[t]->function; MotorDriver * TrackManager::track[MAX_TRACKS] = { NULL }; int16_t TrackManager::trackDCAddr[MAX_TRACKS] = { 0 }; int16_t TrackManager::trackPwrMA[MAX_TRACKS] = { 0 }; int8_t TrackManager::lastTrack=-1; bool TrackManager::progTrackSyncMain=false; bool TrackManager::progTrackBoosted=false; int16_t TrackManager::joinRelay=UNUSED_PIN; #ifdef ARDUINO_ARCH_ESP32 byte TrackManager::tempProgTrack=MAX_TRACKS+1; // MAX_TRACKS+1 is the unused flag #endif #ifdef ANALOG_READ_INTERRUPT /* * sampleCurrent() runs from Interrupt */ void TrackManager::sampleCurrent() { static byte tr = 0; byte trAtStart = tr; static bool waiting = false; if (waiting) { if (! track[tr]->sampleCurrentFromHW()) { return; // no result, continue to wait } // found value, advance at least one track // for scope debug track[1]->setBrake(0); waiting = false; tr++; if (tr > lastTrack) tr = 0; if (lastTrack < 2 || track[tr]->getMode() & TRACK_MODE_PROG) { return; // We could continue but for prog track we // rather do it in next interrupt beacuse // that gives us well defined sampling point. // For other tracks we care less unless we // have only few (max 2) tracks. } } if (!waiting) { // look for a valid track to sample or until we are around while (true) { if (track[tr]->getMode() & ( TRACK_MODE_MAIN|TRACK_MODE_PROG|TRACK_MODE_DC|TRACK_MODE_BOOST|TRACK_MODE_EXT )) { track[tr]->startCurrentFromHW(); // for scope debug track[1]->setBrake(1); waiting = true; break; } tr++; if (tr > lastTrack) tr = 0; if (tr == trAtStart) // we are through and nothing found to do return; } } } #endif // The setup call is done this way so that the tracks can be in a list // from the config... the tracks default to NULL in the declaration void TrackManager::Setup(const FSH * shieldname, MotorDriver * track0, MotorDriver * track1, MotorDriver * track2, MotorDriver * track3, MotorDriver * track4, MotorDriver * track5, MotorDriver * track6, MotorDriver * track7 ) { addTrack(0,track0); addTrack(1,track1); addTrack(2,track2); addTrack(3,track3); addTrack(4,track4); addTrack(5,track5); addTrack(6,track6); addTrack(7,track7); // Default the first 2 tracks (which may be null) and perform HA waveform check. setTrackMode(0,TRACK_MODE_MAIN); #ifndef DISABLE_PROG setTrackMode(1,TRACK_MODE_PROG); #else setTrackMode(1,TRACK_MODE_MAIN); #endif // Fault pin config for odd motor boards (example pololu) FOR_EACH_TRACK(t) { for (byte s=t+1;s<=lastTrack;s++) { if (track[t]->getFaultPin() != UNUSED_PIN && track[t]->getFaultPin() == track[s]->getFaultPin()) { track[t]->setCommonFaultPin(); track[s]->setCommonFaultPin(); DIAG(F("Common Fault pin tracks %c and %c"), t+'A', s+'A'); } } } DCC::setShieldName(shieldname); } void TrackManager::addTrack(byte t, MotorDriver* driver) { track[t]=driver; if (driver) { track[t]->setPower(POWERMODE::OFF); track[t]->setMode(TRACK_MODE_NONE); track[t]->setTrackLetter('A'+t); lastTrack=t; } } // setDCCSignal(), called from interrupt context // does assume ports are shadowed if they can be void TrackManager::setDCCSignal( bool on) { HAVE_PORTA(shadowPORTA=PORTA); HAVE_PORTB(shadowPORTB=PORTB); HAVE_PORTC(shadowPORTC=PORTC); HAVE_PORTD(shadowPORTD=PORTD); HAVE_PORTE(shadowPORTE=PORTE); HAVE_PORTF(shadowPORTF=PORTF); HAVE_PORTG(shadowPORTG=PORTG); HAVE_PORTH(shadowPORTH=PORTH); APPLY_BY_MODE(TRACK_MODE_MAIN,setSignal(on)); HAVE_PORTA(PORTA=shadowPORTA); HAVE_PORTB(PORTB=shadowPORTB); HAVE_PORTC(PORTC=shadowPORTC); HAVE_PORTD(PORTD=shadowPORTD); HAVE_PORTE(PORTE=shadowPORTE); HAVE_PORTF(PORTF=shadowPORTF); HAVE_PORTG(PORTG=shadowPORTG); HAVE_PORTH(PORTH=shadowPORTH); } // setPROGSignal(), called from interrupt context // does assume ports are shadowed if they can be void TrackManager::setPROGSignal( bool on) { HAVE_PORTA(shadowPORTA=PORTA); HAVE_PORTB(shadowPORTB=PORTB); HAVE_PORTC(shadowPORTC=PORTC); HAVE_PORTD(shadowPORTD=PORTD); HAVE_PORTE(shadowPORTE=PORTE); HAVE_PORTF(shadowPORTF=PORTF); HAVE_PORTG(shadowPORTG=PORTG); HAVE_PORTH(shadowPORTH=PORTH); APPLY_BY_MODE(TRACK_MODE_PROG,setSignal(on)); HAVE_PORTA(PORTA=shadowPORTA); HAVE_PORTB(PORTB=shadowPORTB); HAVE_PORTC(PORTC=shadowPORTC); HAVE_PORTD(PORTD=shadowPORTD); HAVE_PORTE(PORTE=shadowPORTE); HAVE_PORTF(PORTF=shadowPORTF); HAVE_PORTG(PORTG=shadowPORTG); HAVE_PORTH(PORTH=shadowPORTH); } // setDCSignal(), called from normal context // MotorDriver::setDCSignal handles shadowed IO port changes. // with interrupts turned off around the critical section void TrackManager::setDCSignal(int16_t cab, byte speedbyte) { FOR_EACH_TRACK(t) { if (trackDCAddr[t]!=cab && cab != 0) continue; if (track[t]->getMode() & TRACK_MODE_DC) track[t]->setDCSignal(speedbyte, DCC::getThrottleFrequency(trackDCAddr[t])); } } bool TrackManager::setTrackMode(byte trackToSet, TRACK_MODE mode, int16_t dcAddr, bool offAtChange) { if (trackToSet>lastTrack || track[trackToSet]==NULL) return false; // Remember track mode we came from for later TRACK_MODE oldmode = track[trackToSet]->getMode(); //DIAG(F("Track=%c Mode=%d"),trackToSet+'A', mode); // DC tracks require a motorDriver that can set brake! if (mode & TRACK_MODE_DC) { #if defined(ARDUINO_AVR_UNO) DIAG(F("Uno has no PWM timers available for DC")); return false; #endif if (!track[trackToSet]->brakeCanPWM()) { DIAG(F("Brake pin can't PWM: No DC")); return false; } } #ifdef ARDUINO_ARCH_ESP32 // remove pin from MUX matrix and turn it off pinpair p = track[trackToSet]->getSignalPin(); //DIAG(F("Track=%c remove pin %d"),trackToSet+'A', p.pin); gpio_reset_pin((gpio_num_t)p.pin); if (p.invpin != UNUSED_PIN) { //DIAG(F("Track=%c remove ^pin %d"),trackToSet+'A', p.invpin); gpio_reset_pin((gpio_num_t)p.invpin); } #ifdef BOOSTER_INPUT if (mode & TRACK_MODE_BOOST) { //DIAG(F("Track=%c mode boost pin %d"),trackToSet+'A', p.pin); pinMode(BOOSTER_INPUT, INPUT); gpio_matrix_in(BOOSTER_INPUT, SIG_IN_FUNC228_IDX, false); //pads 224 to 228 available as loopback gpio_matrix_out(p.pin, SIG_IN_FUNC228_IDX, false, false); if (p.invpin != UNUSED_PIN) { gpio_matrix_out(p.invpin, SIG_IN_FUNC228_IDX, true /*inverted*/, false); } } else // elseif clause continues #endif if (mode & (TRACK_MODE_MAIN | TRACK_MODE_PROG | TRACK_MODE_DC)) { // gpio_reset_pin may reset to input pinMode(p.pin, OUTPUT); if (p.invpin != UNUSED_PIN) pinMode(p.invpin, OUTPUT); } #endif #ifndef DISABLE_PROG if (mode & TRACK_MODE_PROG) { // only allow 1 track to be prog FOR_EACH_TRACK(t) if ( (track[t]->getMode() & TRACK_MODE_PROG) && t != trackToSet) { track[t]->setPower(POWERMODE::OFF); track[t]->setMode(TRACK_MODE_NONE); track[t]->makeProgTrack(false); // revoke prog track special handling streamTrackState(NULL,t); } track[trackToSet]->makeProgTrack(true); // set for prog track special handling } else { track[trackToSet]->makeProgTrack(false); // only the prog track knows it's type } #endif // When a track is switched, we must clear any side effects of its previous // state, otherwise trains run away or just dont move. // This can be done BEFORE the PWM-Timer evaluation (methinks) if (mode & TRACK_MODE_DC) { if (trackDCAddr[trackToSet] != dcAddr) { // new or changed DC Addr, run the new setup if (trackDCAddr[trackToSet] != 0) { // if we change dcAddr and not only // change from another mode, // first detach old DC signal track[trackToSet]->detachDCSignal(); } #ifdef ARDUINO_ARCH_ESP32 int trackfound = -1; FOR_EACH_TRACK(t) { //DIAG(F("Checking track %c mode %x dcAddr %d"), 'A'+t, track[t]->getMode(), trackDCAddr[t]); if (t != trackToSet // not our track && (track[t]->getMode() & TRACK_MODE_DC) // right mode && trackDCAddr[t] == dcAddr) { // right addr //DIAG(F("Found track %c"), 'A'+t); trackfound = t; break; } } if (trackfound > -1) { DCCTimer::DCCEXanalogCopyChannel(track[trackfound]->getBrakePinSigned(), track[trackToSet]->getBrakePinSigned()); } #endif } // set future DC Addr; trackDCAddr[trackToSet]=dcAddr; } else { // DCC tracks need to have set the PWM to zero or they will not work. track[trackToSet]->detachDCSignal(); track[trackToSet]->setBrake(false); trackDCAddr[trackToSet]=0; // clear that an addr is set for DC as this is not a DC track } track[trackToSet]->setMode(mode); // BOOST: // Leave it as is // otherwise: // EXT is a special case where the signal pin is // turned off. So unless that is set, the signal // pin should be turned on if (!(mode & TRACK_MODE_BOOST)) track[trackToSet]->enableSignal(!(mode & TRACK_MODE_EXT)); #ifndef ARDUINO_ARCH_ESP32 // re-evaluate HighAccuracy mode // We can only do this is all main and prog tracks agree bool canDo=true; FOR_EACH_TRACK(t) { // DC tracks must not have the DCC PWM switched on // so we globally turn it off if one of the PWM // capable tracks is now DC or DCX. if (track[t]->getMode() & TRACK_MODE_DC) { if (track[t]->isPWMCapable()) { canDo=false; // this track is capable but can not run PWM break; // in this mode, so abort and prevent globally below } else { track[t]->trackPWM=false; // this track sure can not run with PWM //DIAG(F("Track %c trackPWM 0 (not capable)"), t+'A'); } } else if (track[t]->getMode() & (TRACK_MODE_MAIN |TRACK_MODE_PROG)) { track[t]->trackPWM = track[t]->isPWMCapable(); // trackPWM is still a guess here //DIAG(F("Track %c trackPWM %d"), t+'A', track[t]->trackPWM); canDo &= track[t]->trackPWM; } } if (canDo) DIAG(F("HA mode")); else { // if we discover that HA mode was globally impossible // we must adjust the trackPWM capabilities FOR_EACH_TRACK(t) { track[t]->trackPWM=false; //DIAG(F("Track %c trackPWM 0 (global override)"), t+'A'); } DCCTimer::clearPWM(); // has to be AFTER trackPWM changes because if trackPWM==true this is undone for that track } DCCWaveform::setRailcomPossible(canDo); #else // For ESP32 we just reinitialize the DCC Waveform DCCWaveform::begin(); // setMode() again AFTER Waveform::begin() of ESP32 fixes INVERTED signal track[trackToSet]->setMode(mode); #endif // This block must be AFTER the PWM-Timer modifications if (mode & TRACK_MODE_DC) { // DC tracks need to be given speed of the throttle for that cab address // otherwise will not match other tracks on same cab. // This also needs to allow for inverted DCX applyDCSpeed(trackToSet); } #ifdef ARDUINO_ARCH_ESP32 #ifndef DISABLE_PROG if (tempProgTrack == trackToSet && oldmode & TRACK_MODE_MAIN && !(mode & TRACK_MODE_PROG)) { // If we just take away the prog track, the join should not // be active either. So do in effect an unjoin //DIAG(F("Unsync")); tempProgTrack = MAX_TRACKS+1; progTrackSyncMain=false; if (joinRelay!=UNUSED_PIN) digitalWrite(joinRelay,LOW); } #endif #endif // Turn off power if we changed the mode of this track if (mode != oldmode && offAtChange) { track[trackToSet]->setPower(POWERMODE::OFF); } streamTrackState(NULL,trackToSet); //DIAG(F("TrackMode=%d"),mode); return true; } void TrackManager::applyDCSpeed(byte t) { track[t]->setDCSignal(DCC::getLocoSpeedByte(trackDCAddr[t]), DCC::getThrottleFrequency(trackDCAddr[t])); } bool TrackManager::parseEqualSign(Print *stream, int16_t params, int16_t p[]) { if (params==0) { // <=> List track assignments FOR_EACH_TRACK(t) streamTrackState(stream,t); return true; } p[0]-="A"_hk; // convert A... to 0.... if (params>1 && (p[0]<0 || p[0]>=MAX_TRACKS)) return false; if (params==2 && p[1]=="MAIN"_hk) // <= id MAIN> return setTrackMode(p[0],TRACK_MODE_MAIN); if (params==2 && p[1]=="MAIN_INV"_hk) // <= id MAIN_INV> return setTrackMode(p[0],TRACK_MODE_MAIN_INV); if (params==2 && p[1]=="MAIN_AUTO"_hk) // <= id MAIN_AUTO> return setTrackMode(p[0],TRACK_MODE_MAIN_AUTO); #ifndef DISABLE_PROG if (params==2 && p[1]=="PROG"_hk) // <= id PROG> return setTrackMode(p[0],TRACK_MODE_PROG); #endif if (params==2 && (p[1]=="OFF"_hk || p[1]=="NONE"_hk)) // <= id OFF> <= id NONE> return setTrackMode(p[0],TRACK_MODE_NONE); if (params==2 && p[1]=="EXT"_hk) // <= id EXT> return setTrackMode(p[0],TRACK_MODE_EXT); #ifdef BOOSTER_INPUT if (TRACK_MODE_BOOST != 0 && // compile time optimization params==2 && p[1]=="BOOST"_hk) // <= id BOOST> return setTrackMode(p[0],TRACK_MODE_BOOST); if (TRACK_MODE_BOOST_INV != 0 && // compile time optimization params==2 && p[1]=="BOOST_INV"_hk) // <= id BOOST_INV> return setTrackMode(p[0],TRACK_MODE_BOOST_INV); if (TRACK_MODE_BOOST_AUTO != 0 && // compile time optimization params==2 && p[1]=="BOOST_AUTO"_hk) // <= id BOOST_AUTO> return setTrackMode(p[0],TRACK_MODE_BOOST_AUTO); #endif if (params==2 && p[1]=="AUTO"_hk) // <= id AUTO> return setTrackMode(p[0], track[p[0]]->getMode() | TRACK_MODIFIER_AUTO); if (params==2 && p[1]=="INV"_hk) // <= id INV> return setTrackMode(p[0], track[p[0]]->getMode() | TRACK_MODIFIER_INV); if (params==3 && p[1]=="DC"_hk && p[2]>0) // <= id DC cab> return setTrackMode(p[0],TRACK_MODE_DC,p[2]); if (params==3 && (p[1]=="DC_INV"_hk || // <= id DC_INV cab> p[1]=="DCX"_hk) && p[2]>0) // <= id DCX cab> return setTrackMode(p[0],TRACK_MODE_DC_INV,p[2]); return false; } const FSH* TrackManager::getModeName(TRACK_MODE tm) { const FSH *modename=F("---"); if (tm & TRACK_MODE_MAIN) { if(tm & TRACK_MODIFIER_AUTO) modename=F("MAIN A"); else if (tm & TRACK_MODIFIER_INV) modename=F("MAIN I"); else modename=F("MAIN"); } #ifndef DISABLE_PROG else if (tm & TRACK_MODE_PROG) modename=F("PROG"); #endif else if (tm & TRACK_MODE_NONE) modename=F("NONE"); else if(tm & TRACK_MODE_EXT) modename=F("EXT"); else if(tm & TRACK_MODE_BOOST) { if(tm & TRACK_MODIFIER_AUTO) modename=F("BOOST A"); else if (tm & TRACK_MODIFIER_INV) modename=F("BOOST I"); else modename=F("BOOST"); } else if (tm & TRACK_MODE_DC) { if (tm & TRACK_MODIFIER_INV) modename=F("DCX"); else modename=F("DC"); } return modename; } // null stream means send to commandDistributor for broadcast void TrackManager::streamTrackState(Print* stream, byte t) { const FSH *format; if (track[t]==NULL) return; TRACK_MODE tm = track[t]->getMode(); if (tm & TRACK_MODE_DC) format=F("<= %c %S %d>\n"); else format=F("<= %c %S>\n"); const FSH *modename=getModeName(tm); if (stream) { // null stream means send to commandDistributor for broadcast StringFormatter::send(stream,format,'A'+t, modename, trackDCAddr[t]); } else { CommandDistributor::broadcastTrackState(format,'A'+t, modename, trackDCAddr[t]); CommandDistributor::broadcastPower(); } } byte TrackManager::nextCycleTrack=MAX_TRACKS; void TrackManager::loop() { DCCWaveform::loop(); #ifndef DISABLE_PROG DCCACK::loop(); #endif bool dontLimitProg=DCCACK::isActive() || progTrackSyncMain || progTrackBoosted; nextCycleTrack++; if (nextCycleTrack>lastTrack) nextCycleTrack=0; if (track[nextCycleTrack]==NULL) return; MotorDriver * motorDriver=track[nextCycleTrack]; bool useProgLimit=dontLimitProg ? false : (bool)(track[nextCycleTrack]->getMode() & TRACK_MODE_PROG); motorDriver->checkPowerOverload(useProgLimit, nextCycleTrack); } MotorDriver * TrackManager::getProgDriver() { FOR_EACH_TRACK(t) if (track[t]->getMode() & TRACK_MODE_PROG) return track[t]; return NULL; } #ifdef ARDUINO_ARCH_ESP32 std::vectorTrackManager::getMainDrivers() { std::vector v; FOR_EACH_TRACK(t) if (track[t]->getMode() & TRACK_MODE_MAIN) v.push_back(track[t]); return v; } #endif // Set track power for all tracks with this mode void TrackManager::setTrackPower(TRACK_MODE trackmodeToMatch, POWERMODE powermode) { bool didChange=false; FOR_EACH_TRACK(t) { MotorDriver *driver=track[t]; TRACK_MODE trackmodeOfTrack = driver->getMode(); if (trackmodeToMatch & trackmodeOfTrack) { if (powermode != driver->getPower()) didChange=true; if (powermode == POWERMODE::ON) { if (trackmodeOfTrack & TRACK_MODE_DC) { driver->setBrake(true); // DC starts with brake on applyDCSpeed(t); // speed match DCC throttles } else { // toggle brake before turning power on - resets overcurrent error // on the Pololu board if brake is wired to ^D2. driver->setBrake(true); driver->setBrake(false); // DCC runs with brake off } } driver->setPower(powermode); } } if (didChange) CommandDistributor::broadcastPower(); } // Set track power for this track, inependent of mode void TrackManager::setTrackPower(POWERMODE powermode, byte t) { MotorDriver *driver=track[t]; if (driver == NULL) { // track is not defined at all DIAG(F("Error: Track %c does not exist"), t+'A'); return; } TRACK_MODE trackmode = driver->getMode(); POWERMODE oldpower = driver->getPower(); if (trackmode & TRACK_MODE_NONE) { driver->setBrake(true); // Track is unused. Brake is good to have. powermode = POWERMODE::OFF; // Track is unused. Force it to OFF } else if (trackmode & TRACK_MODE_DC) { // includes inverted DC (called DCX) if (powermode == POWERMODE::ON) { driver->setBrake(true); // DC starts with brake on applyDCSpeed(t); // speed match DCC throttles } } else /* MAIN PROG EXT BOOST */ { if (powermode == POWERMODE::ON) { // toggle brake before turning power on - resets overcurrent error // on the Pololu board if brake is wired to ^D2. driver->setBrake(true); driver->setBrake(false); // DCC runs with brake off } } driver->setPower(powermode); if (oldpower != driver->getPower()) CommandDistributor::broadcastPower(); } // returns state of the one and only prog track POWERMODE TrackManager::getProgPower() { FOR_EACH_TRACK(t) if (track[t]->getMode() & TRACK_MODE_PROG) return track[t]->getPower(); // optimize: there is max one prog track return POWERMODE::OFF; } // returns on if all are on. returns off otherwise POWERMODE TrackManager::getMainPower() { POWERMODE result = POWERMODE::OFF; FOR_EACH_TRACK(t) { if (track[t]->getMode() & TRACK_MODE_MAIN) { POWERMODE p = track[t]->getPower(); if (p == POWERMODE::OFF) return POWERMODE::OFF; // done and out if (p == POWERMODE::ON) result = POWERMODE::ON; } } return result; } bool TrackManager::getPower(byte t, char s[]) { if (t > lastTrack) return false; if (track[t]) { s[0] = track[t]->getPower() == POWERMODE::ON ? '1' : '0'; s[2] = t + 'A'; return true; } return false; } void TrackManager::reportObsoleteCurrent(Print* stream) { // This function is for backward JMRI compatibility only // It reports the first track only, as main, regardless of track settings. // #ifdef HAS_ENOUGH_MEMORY int maxCurrent=track[0]->raw2mA(track[0]->getRawCurrentTripValue()); StringFormatter::send(stream, F("\n"), track[0]->raw2mA(track[0]->getCurrentRaw(false)), maxCurrent, maxCurrent); #else (void)stream; #endif } void TrackManager::reportCurrent(Print* stream) { StringFormatter::send(stream,F("getPower()==POWERMODE::OVERLOAD) ? -1 : track[t]->raw2mA(track[t]->getCurrentRaw(false))); } StringFormatter::send(stream,F(">\n")); } void TrackManager::reportCurrentLCD(uint8_t display, byte row) { int16_t trackPwrTotalMA = 0; FOR_EACH_TRACK(t) { bool pstate = TrackManager::isPowerOn(t); // checks if power is on or off TRACK_MODE tMode=(TrackManager::getMode(t)); // gets to current power mode int16_t DCAddr=(TrackManager::returnDCAddr(t)); if (pstate) { // if power is on do this section trackPwrMA[t]=(3*trackPwrMA[t]>>2) + ((track[t]->getPower()==POWERMODE::OVERLOAD) ? -1 : track[t]->raw2mA(track[t]->getCurrentRaw(false))); trackPwrTotalMA += trackPwrMA[t]; if (tMode & TRACK_MODE_DC) { // Test if track is in DC or DCX mode SCREEN(display, row+t, F("%c: %S %d %dmA"), t+'A', (TrackManager::getModeName(tMode)),DCAddr, trackPwrMA[t]>>2); } else { // formats without DCAddress SCREEN(display, row+t, F("%c: %S %dmA"), t+'A', (TrackManager::getModeName(tMode)), trackPwrMA[t]>>2); } } else { // if power is off do this section trackPwrMA[t] = 0; if (tMode & TRACK_MODE_DC) { // DC / DCX SCREEN(display, row+t, F("%c: %S %d"), t+'A', (TrackManager::getModeName(tMode)),DCAddr); } else { // Not DC or DCX SCREEN(display, row+t, F("%c: %S"), t+'A', (TrackManager::getModeName(tMode))); } } } SCREEN(display, row+lastTrack+1, F("%d Districts %dmA"), lastTrack+1, trackPwrTotalMA>>2); } void TrackManager::reportGauges(Print* stream) { StringFormatter::send(stream,F("raw2mA(track[t]->getRawCurrentTripValue())); } StringFormatter::send(stream,F(">\n")); } void TrackManager::setJoinRelayPin(byte joinRelayPin) { joinRelay=joinRelayPin; if (joinRelay!=UNUSED_PIN) { pinMode(joinRelay,OUTPUT); digitalWrite(joinRelay,LOW); // LOW is relay disengaged } } void TrackManager::setJoin(bool joined) { #ifdef ARDUINO_ARCH_ESP32 if (joined) { // if we go into joined mode (PROG acts as MAIN) FOR_EACH_TRACK(t) { if (track[t]->getMode() & TRACK_MODE_PROG) { // find PROG track tempProgTrack = t; // remember PROG track setTrackMode(t, TRACK_MODE_MAIN, 0, false); // 0 = no DC loco; false = do not turn off pwr // then in some cases setPower() is called // seperately after the setJoin() as well goto success; // there is only one prog track, done } } return; // no prog track found, can not do more success: /* continue here when prog tack found */; } else { if (tempProgTrack != MAX_TRACKS+1) { // setTrackMode defaults to power off, so we // need to preserve that state. setTrackMode(tempProgTrack, TRACK_MODE_PROG, 0, false); // 0 = no DC loco; false = do not turn off pwr tempProgTrack = MAX_TRACKS+1; } } #endif progTrackSyncMain=joined; if (joinRelay!=UNUSED_PIN) digitalWrite(joinRelay,joined?HIGH:LOW); } bool TrackManager::isPowerOn(byte t) { if (track[t]->getPower()!=POWERMODE::ON) return false; return true; } bool TrackManager::isProg(byte t) { if (track[t]->getMode() & TRACK_MODE_PROG) return true; return false; } TRACK_MODE TrackManager::getMode(byte t) { return (track[t]->getMode()); } int16_t TrackManager::returnDCAddr(byte t) { return (trackDCAddr[t]); } ================================================ FILE: TrackManager.h ================================================ /* * © 2022 Chris Harlow * © 2022-2024 Harald Barth * © 2023 Colin Murdoch * © 2025 Herb Morton * * 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 . */ #ifdef ARDUINO_ARCH_ESP32 #include #endif #ifndef TrackManager_h #define TrackManager_h #include "FSH.h" #include "MotorDriver.h" // Virtualised Motor shield multi-track hardware Interface // These constants help EXRAIL macros say SET_TRACK(2,mode) OR SET_TRACK(C,mode) etc. const byte TRACK_NUMBER_0=0, TRACK_NUMBER_A=0; const byte TRACK_NUMBER_1=1, TRACK_NUMBER_B=1; const byte TRACK_NUMBER_2=2, TRACK_NUMBER_C=2; const byte TRACK_NUMBER_3=3, TRACK_NUMBER_D=3; const byte TRACK_NUMBER_4=4, TRACK_NUMBER_E=4; const byte TRACK_NUMBER_5=5, TRACK_NUMBER_F=5; const byte TRACK_NUMBER_6=6, TRACK_NUMBER_G=6; const byte TRACK_NUMBER_7=7, TRACK_NUMBER_H=7; // These constants help EXRAIL macros convert Track Power e.g. SET_POWER(A ON|OFF). const byte TRACK_POWER_0=0, TRACK_POWER_OFF=0; const byte TRACK_POWER_1=1, TRACK_POWER_ON=1; class TrackManager { public: static void Setup(const FSH * shieldName, MotorDriver * track0=NULL, MotorDriver * track1=NULL, MotorDriver * track2=NULL, MotorDriver * track3=NULL, MotorDriver * track4=NULL, MotorDriver * track5=NULL, MotorDriver * track6=NULL, MotorDriver * track7=NULL ); static void setDCCSignal( bool on); static void setPROGSignal( bool on); static void setDCSignal(int16_t cab, byte speedbyte); static MotorDriver * getProgDriver(); #ifdef ARDUINO_ARCH_ESP32 static std::vectorgetMainDrivers(); #endif static void setPower(POWERMODE mode) {setMainPower(mode); setProgPower(mode);} static void setTrackPower(POWERMODE mode, byte t); static void setTrackPower(TRACK_MODE trackmode, POWERMODE powermode); static void setMainPower(POWERMODE mode) {setTrackPower(TRACK_MODE_MAIN, mode);} static void setProgPower(POWERMODE mode) {setTrackPower(TRACK_MODE_PROG, mode);} static const int16_t MAX_TRACKS=8; static inline int8_t numTracks() { return lastTrack + 1; } static bool setTrackMode(byte track, TRACK_MODE mode, int16_t DCaddr=0, bool offAtChange=true); static bool parseEqualSign(Print * stream, int16_t params, int16_t p[]); static void loop(); static POWERMODE getMainPower(); static POWERMODE getProgPower(); static inline POWERMODE getPower(byte t) { return track[t]->getPower(); } static bool getPower(byte t, char s[]); static void setJoin(bool join); static bool isJoined() { return progTrackSyncMain;} static inline bool isActive (byte tr) { if (tr > lastTrack) return false; return track[tr]->getMode() & (TRACK_MODE_MAIN|TRACK_MODE_PROG|TRACK_MODE_DC|TRACK_MODE_BOOST|TRACK_MODE_EXT);} static void setJoinRelayPin(byte joinRelayPin); static void sampleCurrent(); static void reportGauges(Print* stream); static void reportCurrent(Print* stream); static void reportCurrentLCD(uint8_t display, byte row); static void reportObsoleteCurrent(Print* stream); static void streamTrackState(Print* stream, byte t); static bool isPowerOn(byte t); static bool isProg(byte t); static TRACK_MODE getMode(byte t); static int16_t returnDCAddr(byte t); static const FSH* getModeName(TRACK_MODE Mode); static int16_t joinRelay; static bool progTrackSyncMain; // true when prog track is a siding switched to main static bool progTrackBoosted; // true when prog track is not current limited #ifdef DEBUG_ADC public: #else private: #endif static MotorDriver* track[MAX_TRACKS]; private: static void addTrack(byte t, MotorDriver* driver); static int8_t lastTrack; static byte nextCycleTrack; static void applyDCSpeed(byte t); static int16_t trackDCAddr[MAX_TRACKS]; // dc address if TRACK_MODE_DC static int16_t trackPwrMA[MAX_TRACKS]; // for command #ifdef ARDUINO_ARCH_ESP32 static byte tempProgTrack; // holds the prog track number during join #endif }; #endif ================================================ FILE: Turnouts.cpp ================================================ /* * © 2021 Neil McKechnie * © 2021 M Steve Todd * © 2021 Fred Decker * © 2020-2021 Harald Barth * © 2020-2021 Chris Harlow * © 2013-2016 Gregg E. Berman * 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 . */ #include "defines.h" // includes config.h #ifndef DISABLE_EEPROM #include "EEStore.h" #endif #include "StringFormatter.h" #include "CommandDistributor.h" #include "EXRAIL2.h" #include "Turnouts.h" #include "DCC.h" #include "LCN.h" #ifdef EESTOREDEBUG #include "DIAG.h" #endif /* * Protected static data */ /* static */ Turnout *Turnout::_firstTurnout = 0; /* * Public static data */ /* static */ int Turnout::turnoutlistHash = 0; /* * Protected static functions */ /* static */ Turnout *Turnout::get(uint16_t id) { // Find turnout object from list. for (Turnout *tt = _firstTurnout; tt != NULL; tt = tt->_nextTurnout) if (tt->_turnoutData.id == id) return tt; return NULL; } // Add new turnout to end of chain /* static */ void Turnout::add(Turnout *tt) { if (!_firstTurnout) _firstTurnout = tt; else { // Find last object on chain Turnout *ptr = _firstTurnout; for ( ; ptr->_nextTurnout!=0; ptr=ptr->_nextTurnout) {} // Line new object to last object. ptr->_nextTurnout = tt; } turnoutlistHash++; } // Remove nominated turnout from turnout linked list and delete the object. /* static */ bool Turnout::remove(uint16_t id) { Turnout *tt,*pp=NULL; for(tt=_firstTurnout; tt!=NULL && tt->_turnoutData.id!=id; pp=tt, tt=tt->_nextTurnout) {} if (tt == NULL) return false; if (tt == _firstTurnout) _firstTurnout = tt->_nextTurnout; else pp->_nextTurnout = tt->_nextTurnout; delete (ServoTurnout *)tt; turnoutlistHash++; return true; } /* * Public static functions */ /* static */ bool Turnout::isClosed(uint16_t id) { Turnout *tt = get(id); if (tt) return tt->isClosed(); else return false; } /* static */ bool Turnout::setClosedStateOnly(uint16_t id, bool closeFlag) { Turnout *tt = get(id); if (!tt) return false; // I know it says setClosedStateOnly, but we need to tell others // that the state has changed too. But we only broadcast if there // really has been a change. if (tt->_turnoutData.closed != closeFlag) { tt->_turnoutData.closed = closeFlag; CommandDistributor::broadcastTurnout(id, closeFlag); } #if defined(EXRAIL_ACTIVE) RMFT2::turnoutEvent(id, closeFlag); #endif return true; } // Static setClosed function is invoked from close(), throw() etc. to perform the // common parts of the turnout operation. Code which is specific to a turnout // type should be placed in the virtual function setClosedInternal(bool) which is // called from here. /* static */ bool Turnout::setClosed(uint16_t id, bool closeFlag) { #if defined(DIAG_IO) DIAG(F("Turnout(%d,%c)"), id, closeFlag ? 'c':'t'); #endif Turnout *tt = Turnout::get(id); if (!tt) return false; bool ok = tt->setClosedInternal(closeFlag); if (ok) { tt->setClosedStateOnly(id, closeFlag); #ifndef DISABLE_EEPROM // Write byte containing new closed/thrown state to EEPROM if required. Note that eepromAddress // is always zero for LCN turnouts. if (EEStore::eeStore->data.nTurnouts > 0 && tt->_eepromAddress > 0) EEPROM.put(tt->_eepromAddress, tt->_turnoutData.flags); #endif } return ok; } #ifndef DISABLE_EEPROM // Load all turnout objects /* static */ void Turnout::load() { for (uint16_t i=0; idata.nTurnouts; i++) { Turnout::loadTurnout(); } } // Save all turnout objects /* static */ void Turnout::store() { EEStore::eeStore->data.nTurnouts=0; for (Turnout *tt = _firstTurnout; tt != 0; tt = tt->_nextTurnout) { tt->save(); EEStore::eeStore->data.nTurnouts++; } } // Load one turnout from EEPROM /* static */ Turnout *Turnout::loadTurnout () { Turnout *tt = 0; // Read turnout type from EEPROM struct TurnoutData turnoutData; int eepromAddress = EEStore::pointer() + offsetof(struct TurnoutData, flags); // Address of byte containing the closed flag. EEPROM.get(EEStore::pointer(), turnoutData); EEStore::advance(sizeof(turnoutData)); switch (turnoutData.turnoutType) { case TURNOUT_SERVO: // Servo turnout tt = ServoTurnout::load(&turnoutData); break; case TURNOUT_DCC: // DCC Accessory turnout tt = DCCTurnout::load(&turnoutData); break; case TURNOUT_VPIN: // VPIN turnout tt = VpinTurnout::load(&turnoutData); break; default: // If we find anything else, then we don't know what it is or how long it is, // so we can't go any further through the EEPROM! return NULL; } if (tt) { // Save EEPROM address in object. Note that LCN turnouts always have eepromAddress of zero. tt->_eepromAddress = eepromAddress + offsetof(struct TurnoutData, flags); } #ifdef EESTOREDEBUG printAll(&USB_SERIAL); #endif return tt; } #endif /************************************************************************************* * ServoTurnout - Turnout controlled by servo device. * *************************************************************************************/ // Private Constructor ServoTurnout::ServoTurnout(uint16_t id, VPIN vpin, uint16_t thrownPosition, uint16_t closedPosition, uint8_t profile, bool closed) : Turnout(id, TURNOUT_SERVO, closed) { _servoTurnoutData.vpin = vpin; _servoTurnoutData.thrownPosition = thrownPosition; _servoTurnoutData.closedPosition = closedPosition; _servoTurnoutData.profile = profile; } // Create function /* static */ Turnout *ServoTurnout::create(uint16_t id, VPIN vpin, uint16_t thrownPosition, uint16_t closedPosition, uint8_t profile, bool closed) { #ifndef IO_NO_HAL Turnout *tt = get(id); if (tt) { // Object already exists, check if it is usable if (tt->isType(TURNOUT_SERVO)) { // Yes, so set parameters ServoTurnout *st = (ServoTurnout *)tt; st->_servoTurnoutData.vpin = vpin; st->_servoTurnoutData.thrownPosition = thrownPosition; st->_servoTurnoutData.closedPosition = closedPosition; st->_servoTurnoutData.profile = profile; // Don't touch the _closed parameter, retain the original value. // We don't really need to do the following, since a call to IODevice::_writeAnalogue // will provide all the data that is required! However, if someone has configured // a Turnout, we should ensure that the SET() RESET() and other commands that use write() // behave consistently with the turnout commands. IODevice::configureServo(vpin, thrownPosition, closedPosition, profile, 0, closed); // Set position directly to specified position - we don't know where it is moving from. IODevice::writeAnalogue(vpin, closed ? closedPosition : thrownPosition, PCA9685::Instant); return tt; } else { // Incompatible object, delete and recreate remove(id); } } tt = (Turnout *)new ServoTurnout(id, vpin, thrownPosition, closedPosition, profile, closed); DIAG(F("Turnout 0x%x size %d size %d"), tt, sizeof(Turnout),sizeof(struct TurnoutData)); IODevice::writeAnalogue(vpin, closed ? closedPosition : thrownPosition, PCA9685::Instant); return tt; #else (void)id; (void)vpin; (void)thrownPosition; (void)closedPosition; (void)profile; (void)closed; // avoid compiler warnings. return NULL; #endif } // Load a Servo turnout definition from EEPROM. The common Turnout data has already been read at this point. Turnout *ServoTurnout::load(struct TurnoutData *turnoutData) { #ifndef DISABLE_EEPROM ServoTurnoutData servoTurnoutData; // Read class-specific data from EEPROM EEPROM.get(EEStore::pointer(), servoTurnoutData); EEStore::advance(sizeof(servoTurnoutData)); // Create new object Turnout *tt = ServoTurnout::create(turnoutData->id, servoTurnoutData.vpin, servoTurnoutData.thrownPosition, servoTurnoutData.closedPosition, servoTurnoutData.profile, turnoutData->closed); return tt; #else (void)turnoutData; return NULL; #endif } // For DCC++ classic compatibility, state reported to JMRI is 1 for thrown and 0 for closed void ServoTurnout::print(Print *stream) { StringFormatter::send(stream, F("\n"), _turnoutData.id, _servoTurnoutData.vpin, _servoTurnoutData.thrownPosition, _servoTurnoutData.closedPosition, _servoTurnoutData.profile, !_turnoutData.closed); } // ServoTurnout-specific code for throwing or closing a servo turnout. bool ServoTurnout::setClosedInternal(bool close) { #ifndef IO_NO_HAL IODevice::writeAnalogue(_servoTurnoutData.vpin, close ? _servoTurnoutData.closedPosition : _servoTurnoutData.thrownPosition, _servoTurnoutData.profile); #else (void)close; // avoid compiler warnings #endif return true; } void ServoTurnout::save() { #ifndef DISABLE_EEPROM // Write turnout definition and current position to EEPROM // First write common servo data, then // write the servo-specific data EEPROM.put(EEStore::pointer(), _turnoutData); EEStore::advance(sizeof(_turnoutData)); EEPROM.put(EEStore::pointer(), _servoTurnoutData); EEStore::advance(sizeof(_servoTurnoutData)); #endif } /************************************************************************************* * DCCTurnout - Turnout controlled by DCC Accessory Controller. * *************************************************************************************/ // DCCTurnoutData contains data specific to this subclass that is // written to EEPROM when the turnout is saved. struct DCCTurnoutData { // DCC address (Address in bits 15-2, subaddress in bits 1-0 uint16_t address; // CS currently supports linear address 1-2048 // That's DCC accessory address 1-512 and subaddress 0-3. } _dccTurnoutData; // 2 bytes // Constructor DCCTurnout::DCCTurnout(uint16_t id, uint16_t address, uint8_t subAdd) : Turnout(id, TURNOUT_DCC, false) { _dccTurnoutData.address = address; _dccTurnoutData.subAddress = subAdd; } // Create function /* static */ Turnout *DCCTurnout::create(uint16_t id, uint16_t add, uint8_t subAdd) { Turnout *tt = get(id); if (tt) { // Object already exists, check if it is usable if (tt->isType(TURNOUT_DCC)) { // Yes, so set parameters DCCTurnout *dt = (DCCTurnout *)tt; dt->_dccTurnoutData.address = add; dt->_dccTurnoutData.subAddress = subAdd; // Don't touch the _closed parameter, retain the original value. return tt; } else { // Incompatible object, delete and recreate remove(id); } } tt = (Turnout *)new DCCTurnout(id, add, subAdd); return tt; } // Load a DCC turnout definition from EEPROM. The common Turnout data has already been read at this point. /* static */ Turnout *DCCTurnout::load(struct TurnoutData *turnoutData) { #ifndef DISABLE_EEPROM DCCTurnoutData dccTurnoutData; // Read class-specific data from EEPROM EEPROM.get(EEStore::pointer(), dccTurnoutData); EEStore::advance(sizeof(dccTurnoutData)); // Create new object DCCTurnout *tt = new DCCTurnout(turnoutData->id, dccTurnoutData.address, dccTurnoutData.subAddress); return tt; #else (void)turnoutData; return NULL; #endif } void DCCTurnout::print(Print *stream) { StringFormatter::send(stream, F("\n"), _turnoutData.id, _dccTurnoutData.address, _dccTurnoutData.subAddress, !_turnoutData.closed); // Also report using classic DCC++ syntax for DCC accessory turnouts, since JMRI expects this. StringFormatter::send(stream, F("\n"), _turnoutData.id, _dccTurnoutData.address, _dccTurnoutData.subAddress, !_turnoutData.closed); } bool DCCTurnout::setClosedInternal(bool close) { // DCC++ Classic behaviour is that Throw writes a 1 in the packet, // and Close writes a 0. // RCN-213 specifies that Throw is 0 and Close is 1. #ifndef DCC_TURNOUTS_RCN_213 close = !close; #endif DCC::setAccessory(_dccTurnoutData.address, _dccTurnoutData.subAddress, close); return true; } void DCCTurnout::save() { #ifndef DISABLE_EEPROM // Write turnout definition and current position to EEPROM // First write common servo data, then // write the servo-specific data EEPROM.put(EEStore::pointer(), _turnoutData); EEStore::advance(sizeof(_turnoutData)); EEPROM.put(EEStore::pointer(), _dccTurnoutData); EEStore::advance(sizeof(_dccTurnoutData)); #endif } /************************************************************************************* * VpinTurnout - Turnout controlled through a HAL vpin. * *************************************************************************************/ // Constructor VpinTurnout::VpinTurnout(uint16_t id, VPIN vpin, bool closed) : Turnout(id, TURNOUT_VPIN, closed) { _vpinTurnoutData.vpin = vpin; } // Create function /* static */ Turnout *VpinTurnout::create(uint16_t id, VPIN vpin, bool closed) { Turnout *tt = get(id); if (tt) { // Object already exists, check if it is usable if (tt->isType(TURNOUT_VPIN)) { // Yes, so set parameters VpinTurnout *vt = (VpinTurnout *)tt; vt->_vpinTurnoutData.vpin = vpin; // Don't touch the _closed parameter, retain the original value. return tt; } else { // Incompatible object, delete and recreate remove(id); } } tt = (Turnout *)new VpinTurnout(id, vpin, closed); return tt; } // Load a VPIN turnout definition from EEPROM. The common Turnout data has already been read at this point. /* static */ Turnout *VpinTurnout::load(struct TurnoutData *turnoutData) { #ifndef DISABLE_EEPROM VpinTurnoutData vpinTurnoutData; // Read class-specific data from EEPROM EEPROM.get(EEStore::pointer(), vpinTurnoutData); EEStore::advance(sizeof(vpinTurnoutData)); // Create new object VpinTurnout *tt = new VpinTurnout(turnoutData->id, vpinTurnoutData.vpin, turnoutData->closed); return tt; #else (void)turnoutData; return NULL; #endif } // Report 1 for thrown, 0 for closed. void VpinTurnout::print(Print *stream) { StringFormatter::send(stream, F("\n"), _turnoutData.id, _vpinTurnoutData.vpin, !_turnoutData.closed); } bool VpinTurnout::setClosedInternal(bool close) { IODevice::write(_vpinTurnoutData.vpin, close); return true; } void VpinTurnout::save() { #ifndef DISABLE_EEPROM // Write turnout definition and current position to EEPROM // First write common servo data, then // write the servo-specific data EEPROM.put(EEStore::pointer(), _turnoutData); EEStore::advance(sizeof(_turnoutData)); EEPROM.put(EEStore::pointer(), _vpinTurnoutData); EEStore::advance(sizeof(_vpinTurnoutData)); #endif } /************************************************************************************* * LCNTurnout - Turnout controlled by Loconet * *************************************************************************************/ // LCNTurnout has no specific data, and in any case is not written to EEPROM! // struct LCNTurnoutData { // } _lcnTurnoutData; // 0 bytes // Constructor LCNTurnout::LCNTurnout(uint16_t id, bool closed) : Turnout(id, TURNOUT_LCN, closed) { } // Create function /* static */ Turnout *LCNTurnout::create(uint16_t id, bool closed) { Turnout *tt = get(id); if (tt) { // Object already exists, check if it is usable if (tt->isType(TURNOUT_LCN)) { // Yes, so return this object return tt; } else { // Incompatible object, delete and recreate remove(id); } } tt = (Turnout *)new LCNTurnout(id, closed); return tt; } bool LCNTurnout::setClosedInternal(bool close) { // Assume that the LCN command still uses 1 for throw and 0 for close... LCN::send('T', _turnoutData.id, !close); // The _turnoutData.closed flag should be updated by a message from the LCN master. // but in this implementation it is updated in setClosedStateOnly() instead. // If the LCN master updates this, setClosedStateOnly() and all setClosedInternal() // have to be updated accordingly so that the closed flag is only set once. return true; } // LCN turnouts not saved to EEPROM. //void save() override { } //static Turnout *load(struct TurnoutData *turnoutData) { // Report 1 for thrown, 0 for closed. void LCNTurnout::print(Print *stream) { StringFormatter::send(stream, F("\n"), _turnoutData.id, !_turnoutData.closed); } ================================================ FILE: Turnouts.h ================================================ /* * © 2021 Neil McKechnie * © 2021 M Steve Todd * © 2021 Fred Decker * © 2020-2021 Harald Barth * © 2020-2022 Chris Harlow * © 2013-2016 Gregg E. Berman * 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 . */ #ifndef TURNOUTS_H #define TURNOUTS_H //#define EESTOREDEBUG #include "Arduino.h" #include "IODevice.h" #include "StringFormatter.h" // Turnout type definitions enum { TURNOUT_DCC = 1, TURNOUT_SERVO = 2, TURNOUT_VPIN = 3, TURNOUT_LCN = 4, }; /************************************************************************************* * Turnout - Base class for turnouts. * *************************************************************************************/ class Turnout { protected: /* * Object data */ // The TurnoutData struct contains data common to all turnout types, that // is written to EEPROM when the turnout is saved. // The first byte of this struct contains the 'closed' flag which is // updated whenever the turnout changes from thrown to closed and // vice versa. If the turnout has been saved, then this byte is rewritten // when changed in RAM. The 'closed' flag must be located in the first byte. struct TurnoutData { union { struct { bool closed : 1; bool hidden : 1; bool _rfu : 1; uint8_t turnoutType : 5; }; uint8_t flags; }; uint16_t id; } _turnoutData; // 3 bytes #ifndef DISABLE_EEPROM // Address in eeprom of first byte of the _turnoutData struct (containing the closed flag). // Set to zero if the object has not been saved in EEPROM, e.g. for newly created Turnouts, and // for all LCN turnouts. uint16_t _eepromAddress = 0; #endif // Pointer to next turnout on linked list. Turnout *_nextTurnout = 0; /* * Constructor */ Turnout(uint16_t id, uint8_t turnoutType, bool closed) { _turnoutData.id = id; _turnoutData.turnoutType = turnoutType; _turnoutData.closed = closed; _turnoutData.hidden=false; add(this); } /* * Static data */ static Turnout *_firstTurnout; static int _turnoutlistHash; /* * Virtual functions */ virtual bool setClosedInternal(bool close) = 0; // Mandatory in subclass virtual void save() {} /* * Static functions */ static void add(Turnout *tt); public: static Turnout *get(uint16_t id); /* * Static data */ static int turnoutlistHash; static const bool useClassicTurnoutCommands; /* * Public base class functions */ inline bool isClosed() { return _turnoutData.closed; }; inline bool isThrown() { return !_turnoutData.closed; } inline bool isHidden() { return _turnoutData.hidden; } inline void setHidden(bool h) { _turnoutData.hidden=h; } inline bool isType(uint8_t type) { return _turnoutData.turnoutType == type; } inline uint16_t getId() { return _turnoutData.id; } inline Turnout *next() { return _nextTurnout; } void printState(Print *stream); /* * Virtual functions */ virtual void print(Print *stream) { (void)stream; // avoid compiler warnings. } virtual ~Turnout() {} // Destructor /* * Public static functions */ inline static bool exists(uint16_t id) { return get(id) != 0; } static bool remove(uint16_t id); static bool isClosed(uint16_t id); inline static bool isThrown(uint16_t id) { return !isClosed(id); } static bool setClosed(uint16_t id, bool closeFlag); inline static bool setClosed(uint16_t id) { return setClosed(id, true); } inline static bool setThrown(uint16_t id) { return setClosed(id, false); } static bool setClosedStateOnly(uint16_t id, bool close); inline static Turnout *first() { return _firstTurnout; } #ifndef DISABLE_EEPROM // Load all turnout definitions. static void load(); // Load one turnout definition static Turnout *loadTurnout(); // Save all turnout definitions static void store(); #endif static bool printAll(Print *stream) { bool gotOne=false; for (Turnout *tt = _firstTurnout; tt != 0; tt = tt->_nextTurnout) if (!tt->isHidden()) { gotOne=true; StringFormatter::send(stream, F("\n"),tt->getId(), tt->isThrown()); } return gotOne; } }; /************************************************************************************* * ServoTurnout - Turnout controlled by servo device. * *************************************************************************************/ class ServoTurnout : public Turnout { private: // ServoTurnoutData contains data specific to this subclass that is // written to EEPROM when the turnout is saved. struct ServoTurnoutData { VPIN vpin; uint16_t closedPosition : 12; uint16_t thrownPosition : 12; uint8_t profile; } _servoTurnoutData; // 6 bytes // Constructor ServoTurnout(uint16_t id, VPIN vpin, uint16_t thrownPosition, uint16_t closedPosition, uint8_t profile, bool closed); public: // Create function static Turnout *create(uint16_t id, VPIN vpin, uint16_t thrownPosition, uint16_t closedPosition, uint8_t profile, bool closed=true); // Load a Servo turnout definition from EEPROM. The common Turnout data has already been read at this point. static Turnout *load(struct TurnoutData *turnoutData); void print(Print *stream) override; protected: // ServoTurnout-specific code for throwing or closing a servo turnout. bool setClosedInternal(bool close) override; void save() override; }; /************************************************************************************* * DCCTurnout - Turnout controlled by DCC Accessory Controller. * *************************************************************************************/ class DCCTurnout : public Turnout { private: // DCCTurnoutData contains data specific to this subclass that is // written to EEPROM when the turnout is saved. struct DCCTurnoutData { // DCC address (Address in bits 15-2, subaddress in bits 1-0) struct { uint16_t address : 14; uint8_t subAddress : 2; }; } _dccTurnoutData; // 2 bytes // Constructor DCCTurnout(uint16_t id, uint16_t address, uint8_t subAdd); public: // Create function static Turnout *create(uint16_t id, uint16_t add, uint8_t subAdd); // Load a VPIN turnout definition from EEPROM. The common Turnout data has already been read at this point. static Turnout *load(struct TurnoutData *turnoutData); void print(Print *stream) override; protected: bool setClosedInternal(bool close) override; void save() override; }; /************************************************************************************* * VpinTurnout - Turnout controlled through a HAL vpin. * *************************************************************************************/ class VpinTurnout : public Turnout { private: // VpinTurnoutData contains data specific to this subclass that is // written to EEPROM when the turnout is saved. struct VpinTurnoutData { VPIN vpin; } _vpinTurnoutData; // 2 bytes // Constructor VpinTurnout(uint16_t id, VPIN vpin, bool closed); public: // Create function static Turnout *create(uint16_t id, VPIN vpin, bool closed=true); // Load a VPIN turnout definition from EEPROM. The common Turnout data has already been read at this point. static Turnout *load(struct TurnoutData *turnoutData); void print(Print *stream) override; protected: bool setClosedInternal(bool close) override; void save() override; }; /************************************************************************************* * LCNTurnout - Turnout controlled by Loconet * *************************************************************************************/ class LCNTurnout : public Turnout { private: // LCNTurnout has no specific data, and in any case is not written to EEPROM! // struct LCNTurnoutData { // } _lcnTurnoutData; // 0 bytes // Constructor LCNTurnout(uint16_t id, bool closed); public: // Create function static Turnout *create(uint16_t id, bool closed=true); bool setClosedInternal(bool close) override; // LCN turnouts not saved to EEPROM. //void save() override { } //static Turnout *load(struct TurnoutData *turnoutData) { void print(Print *stream) override; }; #endif ================================================ FILE: Turntables.cpp ================================================ /* * © 2023 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 . */ #include "defines.h" #include #include "Turntables.h" #include "StringFormatter.h" #include "CommandDistributor.h" #include "EXRAIL2.h" #include "DCC.h" // No turntable support without HAL #ifndef IO_NO_HAL /* * Protected static data */ Turntable *Turntable::_firstTurntable = 0; /* * Public static data */ int Turntable::turntablelistHash = 0; /* * Protected static functions */ // Add new turntable to end of list void Turntable::add(Turntable *tto) { if (!_firstTurntable) { _firstTurntable = tto; } else { Turntable *ptr = _firstTurntable; for ( ; ptr->_nextTurntable!=0; ptr=ptr->_nextTurntable) {} ptr->_nextTurntable = tto; } turntablelistHash++; } // Add a position void Turntable::addPosition(uint8_t idx, uint16_t value, uint16_t angle) { _turntablePositions.insert(idx, value, angle); } // Get value for position uint16_t Turntable::getPositionValue(uint8_t position) { TurntablePosition* currentPosition = _turntablePositions.getHead(); while (currentPosition) { if (currentPosition->index == position) { return currentPosition->data; } currentPosition = currentPosition->next; } return false; } // Get value for position uint16_t Turntable::getPositionAngle(uint8_t position) { TurntablePosition* currentPosition = _turntablePositions.getHead(); while (currentPosition) { if (currentPosition->index == position) { return currentPosition->angle; } currentPosition = currentPosition->next; } return false; } // Get the count of positions associated with the turntable uint8_t Turntable::getPositionCount() { TurntablePosition* currentPosition = _turntablePositions.getHead(); uint8_t count = 0; while (currentPosition) { count++; currentPosition = currentPosition->next; } return count; } /* * Public static functions */ // Find turntable from list Turntable *Turntable::get(uint16_t id) { for (Turntable *tto = _firstTurntable; tto != nullptr; tto = tto->_nextTurntable) if (tto->_turntableData.id == id) return tto; return NULL; } // Find turntable via Vpin Turntable *Turntable::getByVpin(VPIN vpin) { for (Turntable *tto = _firstTurntable; tto != nullptr; tto = tto->_nextTurntable) { if (tto->isEXTT()) { EXTTTurntable *exttTto = static_cast(tto); if (exttTto->getVpin() == vpin) { return tto; } } } return nullptr; } // Get the current position for turntable with the specified ID uint8_t Turntable::getPosition(uint16_t id) { Turntable *tto = get(id); if (!tto) return false; return tto->getPosition(); } // Got the moving state of the specified turntable bool Turntable::ttMoving(uint16_t id) { Turntable *tto = get(id); if (!tto) return false; return tto->isMoving(); } // Initiate a turntable move bool Turntable::setPosition(uint16_t id, uint8_t position, uint8_t activity) { #if defined(DIAG_IO) DIAG(F("Rotate turntable %d to position %d, activity %d)"), id, position, activity); #endif Turntable *tto = Turntable::get(id); if (!tto) return false; if (tto->isMoving()) return false; bool ok = tto->setPositionInternal(position, activity); if (ok) { // We only deal with broadcasts for DCC turntables here, EXTT in the device driver if (!tto->isEXTT()) { CommandDistributor::broadcastTurntable(id, position, false); } // Trigger EXRAIL rotateEvent for both types here if changed #if defined(EXRAIL_ACTIVE) bool rotated = false; if (position != tto->_previousPosition) rotated = true; RMFT2::rotateEvent(id, rotated); #endif } return ok; } /************************************************************************************* * EXTTTurntable - EX-Turntable device. * *************************************************************************************/ // Private constructor EXTTTurntable::EXTTTurntable(uint16_t id, VPIN vpin) : Turntable(id, TURNTABLE_EXTT) { _exttTurntableData.vpin = vpin; } using DevState = IODevice::DeviceStateEnum; // Create function Turntable *EXTTTurntable::create(uint16_t id, VPIN vpin) { #ifndef IO_NO_HAL Turntable *tto = get(id); if (tto) { if (tto->isType(TURNTABLE_EXTT)) { EXTTTurntable *extt = (EXTTTurntable *)tto; extt->_exttTurntableData.vpin = vpin; return tto; } } if (!IODevice::exists(vpin)) return nullptr; if (IODevice::getStatus(vpin) == DevState::DEVSTATE_FAILED) return nullptr; if (Turntable::getByVpin(vpin)) return nullptr; tto = (Turntable *)new EXTTTurntable(id, vpin); DIAG(F("Turntable 0x%x size %d size %d"), tto, sizeof(Turntable), sizeof(struct TurntableData)); return tto; #else (void)id; (void)vpin; return NULL; #endif } void EXTTTurntable::print(Print *stream) { StringFormatter::send(stream, F("\n"), _turntableData.id, _exttTurntableData.vpin); } // EX-Turntable specific code for moving to the specified position bool EXTTTurntable::setPositionInternal(uint8_t position, uint8_t activity) { #ifndef IO_NO_HAL int16_t value; if (position == 0) { value = 0; // Position 0 is just to send activities } else { if (activity > 1) return false; // If sending a position update, only phase changes valid (0|1) value = getPositionValue(position); // Get position value from position list } if (position > 0 && !value) return false; // Return false if it's not a valid position // Set position via device driver _previousPosition = _turntableData.position; _turntableData.position = position; EXTurntable::writeAnalogue(_exttTurntableData.vpin, value, activity); #else (void)position; #endif return true; } /************************************************************************************* * DCCTurntable - DCC Turntable device. * *************************************************************************************/ // Private constructor DCCTurntable::DCCTurntable(uint16_t id) : Turntable(id, TURNTABLE_DCC) {} // Create function Turntable *DCCTurntable::create(uint16_t id) { #ifndef IO_NO_HAL Turntable *tto = get(id); if (!tto) { tto = (Turntable *)new DCCTurntable(id); DIAG(F("Turntable 0x%x size %d size %d"), tto, sizeof(Turntable), sizeof(struct TurntableData)); } return tto; #else (void)id; return NULL; #endif } void DCCTurntable::print(Print *stream) { StringFormatter::send(stream, F("\n"), _turntableData.id); } // EX-Turntable specific code for moving to the specified position bool DCCTurntable::setPositionInternal(uint8_t position, uint8_t activity) { (void) activity; #ifndef IO_NO_HAL int16_t value = getPositionValue(position); if (position == 0 || !value) return false; // Return false if it's not a valid position // Set position via device driver int16_t addr=value>>3; int16_t subaddr=(value>>1) & 0x03; bool active=value & 0x01; _previousPosition = _turntableData.position; _turntableData.position = position; DCC::setAccessory(addr, subaddr, active); #else (void)position; #endif return true; } #endif ================================================ FILE: Turntables.h ================================================ /* * © 2023 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 . */ #ifndef TURNTABLES_H #define TURNTABLES_H #include #include "IODevice.h" #include "StringFormatter.h" // No turntable support without HAL #ifndef IO_NO_HAL // Turntable type definitions // EXTT = EX-Turntable // DCC = DCC accessory turntables - to be added later enum { TURNTABLE_EXTT = 0, TURNTABLE_DCC = 1, }; /************************************************************************************* * Turntable positions. * *************************************************************************************/ struct TurntablePosition { uint8_t index; uint16_t data; uint16_t angle; TurntablePosition* next; TurntablePosition(uint8_t idx, uint16_t value, uint16_t angle) : index(idx), data(value), angle(angle), next(nullptr) {} }; class TurntablePositionList { public: TurntablePositionList() : head(nullptr) {} void insert(uint8_t idx, uint16_t value, uint16_t angle) { TurntablePosition* newPosition = new TurntablePosition(idx, value, angle); if(!head) { head = newPosition; } else { newPosition->next = head; head = newPosition; } } TurntablePosition* getHead() { return head; } private: TurntablePosition* head; }; /************************************************************************************* * Turntable - Base class for turntables. * *************************************************************************************/ class Turntable { protected: /* * Object data */ // Data common to all turntable types struct TurntableData { union { struct { bool hidden : 1; bool turntableType : 1; uint8_t position : 6; // Allows up to 63 positions including 0/home }; uint8_t flags; }; uint16_t id; } _turntableData; // Pointer to next turntable object Turntable *_nextTurntable = 0; // Linked list for positions TurntablePositionList _turntablePositions; // Store the previous position to allow checking for changes uint8_t _previousPosition = 0; // Store the current state of the turntable bool _isMoving = false; /* * Constructor */ Turntable(uint16_t id, uint8_t turntableType) { _turntableData.id = id; _turntableData.turntableType = turntableType; _turntableData.hidden = false; _turntableData.position = 0; add(this); } /* * Static data */ static Turntable *_firstTurntable; static int _turntablelistHash; /* * Virtual functions */ virtual bool setPositionInternal(uint8_t position, uint8_t activity) = 0; /* * Static functions */ static void add(Turntable *tto); public: static Turntable *get(uint16_t id); static Turntable *getByVpin(VPIN vpin); /* * Static data */ static int turntablelistHash; /* * Public base class functions */ inline uint8_t getPosition() { return _turntableData.position; } inline bool isHidden() { return _turntableData.hidden; } inline void setHidden(bool h) {_turntableData.hidden=h; } inline bool isType(uint8_t type) { return _turntableData.turntableType == type; } inline bool isEXTT() const { return _turntableData.turntableType == TURNTABLE_EXTT; } inline uint16_t getId() { return _turntableData.id; } inline Turntable *next() { return _nextTurntable; } void printState(Print *stream); void addPosition(uint8_t idx, uint16_t value, uint16_t angle); uint16_t getPositionValue(uint8_t position); uint16_t getPositionAngle(uint8_t position); uint8_t getPositionCount(); bool isMoving() { return _isMoving; } void setMoving(bool moving) { _isMoving=moving; } /* * Virtual functions */ virtual void print(Print *stream) { (void)stream; // suppress compiler warnings } virtual ~Turntable() {} // Destructor /* * Public static functions */ inline static bool exists(uint16_t id) { return get(id) != 0; } static bool setPosition(uint16_t id, uint8_t position, uint8_t activity=0); static uint8_t getPosition(uint16_t id); static bool ttMoving(uint16_t id); inline static Turntable *first() { return _firstTurntable; } static bool printAll(Print *stream) { bool gotOne = false; for (Turntable *tto = _firstTurntable; tto != 0; tto = tto->_nextTurntable) if (!tto->isHidden()) { gotOne = true; StringFormatter::send(stream, F("\n"), tto->getId(), tto->getPosition()); } return gotOne; } }; /************************************************************************************* * EXTTTurntable - EX-Turntable device. * *************************************************************************************/ class EXTTTurntable : public Turntable { private: // EXTTTurntableData contains device specific data struct EXTTTurntableData { VPIN vpin; } _exttTurntableData; // Constructor EXTTTurntable(uint16_t id, VPIN vpin); public: // Create function static Turntable *create(uint16_t id, VPIN vpin); void print(Print *stream) override; VPIN getVpin() const { return _exttTurntableData.vpin; } protected: // EX-Turntable specific code for setting position bool setPositionInternal(uint8_t position, uint8_t activity) override; }; /************************************************************************************* * DCCTurntable - DCC accessory Turntable device. * *************************************************************************************/ class DCCTurntable : public Turntable { private: // Constructor DCCTurntable(uint16_t id); public: // Create function static Turntable *create(uint16_t id); void print(Print *stream) override; protected: // DCC specific code for setting position bool setPositionInternal(uint8_t position, uint8_t activity=0) override; }; #endif #endif ================================================ FILE: Websockets.cpp ================================================ /* * © 2023-2026 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 . */ /************************************************** HOW IT WORKS 1) Refer to https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers 2) When a new client sends in a socket stream, the CommandDistributor pass it to this code checkConnectionString() to check for an HTTP protocol GET requesting a change to websocket protocol. [Note that the WifiInboundHandler has a shortcut to detecting this so that it does not need to use up 500+ bytes of RAM just to get at the one parameter that actually means something.] If that is found, the relevant answer is generated and queued and the CommandDistributor marks this client as a websocket client awaiting connection. Once the outbound handshake has completed, the CommandDistributor promotes the client from awaiting connection to connected websocket so that all future traffic for this client is handled with websocket protocol. 3) When an input is received from a client marked as websocket, CommandDistributor calls unmask() to strip off the websocket header and un-mask the input bytes. The command distributor will flag the clientid in the ringstream so that anyone transmitting this output will know to handle it differently. 4) when the Wifi/Ethernet handler needs to transmit the result from the output ring, it recognises the websockets flag and adds the websocket header to the output dynamically. *************************************************************/ #include #include "FSH.h" #include "RingStream.h" #include "libsha1.h" #include "Websockets.h" #include "DIAG.h" #ifdef ARDUINO_ARCH_ESP32 // ESP32 runtime or definitions has strlcat_P missing #define strlcat_P strlcat #endif static const char b64_table[] = { 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', '/' }; bool Websockets::checkConnectionString(byte clientId,byte * cmd, RingStream * outbound ) { // returns true if this input is a websocket connect if (Diag::WEBSOCKET) DIAG(F("Websock check connection")); /* Heuristic suppose this is a websocket GET typically looking like this: GET / HTTP/1.1 Host: 192.168.1.242:2560 Connection: Upgrade Pragma: no-cache Cache-Control: no-cache User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36 Edg/119.0.0.0 Upgrade: websocket Origin: null Sec-WebSocket-Version: 13 Accept-Encoding: gzip, deflate Accept-Language: en-US,en;q=0.9 Sec-WebSocket-Key: SpRkQKPPNZcO62pYf1X6Yg== Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits */ // check contents to find Sec-WebSocket-Key: and get key up to \n auto keyPos=strstr_P((char*)cmd,(char*)F("Sec-WebSocket-Key: ")); if (!keyPos) return false; keyPos+=19; // length of Sec-Websocket-Key: auto endkeypos=strstr(keyPos,"\r"); if (!endkeypos) return false; *endkeypos=0; if (Diag::WEBSOCKET) DIAG(F("Websock key=\"%s\""),keyPos); // generate the reply key uint8_t sha1HashBin[21] = { 0 }; // 21 to make it base64 div 3 char replyKey[100]; strlcpy(replyKey,keyPos, sizeof(replyKey)); strlcat_P(replyKey,(char*)F("258EAFA5-E914-47DA-95CA-C5AB0DC85B11"), sizeof(replyKey)); if (Diag::WEBSOCKET) DIAG(F("Websock replykey=%s"),replyKey); SHA1_CTX ctx; SHA1Init(&ctx); SHA1Update(&ctx, (unsigned char *)replyKey, strlen(replyKey)); SHA1Final(sha1HashBin, &ctx); // generate the response and embed the base64 encode // of the key outbound->mark(clientId); outbound->print(F("HTTP/1.1 101 Switching Protocols\r\n" "Server: DCCEX-WebSocketsServer\r\n" "Upgrade: websocket\r\n" "Connection: Upgrade\r\n" "Origin: null\r\n" "Sec-WebSocket-Version: 13\r\n" "Sec-WebSocket-Protocol: DCCEX\r\n" "Sec-WebSocket-Accept: ")); // encode and emit the reply key as base 64 auto * tmp=sha1HashBin; for (int i=0;i<7;i++) { outbound->print(b64_table[(tmp[0] & 0xfc) >> 2]); outbound->print(b64_table[((tmp[0] & 0x03) << 4) + ((tmp[1] & 0xf0) >> 4)]); outbound->print(b64_table[((tmp[1] & 0x0f) << 2) + ((tmp[2] & 0xc0) >> 6)]); if (i<6) outbound->print(b64_table[tmp[2] & 0x3f]); tmp+=3; } outbound->print(F("=\r\n\r\n")); // because we have padded 1 byte outbound->commit(); return true; } byte * Websockets::unmask(byte clientId,RingStream *ring, byte * buffer) { // buffer should have a websocket header //byte opcode=buffer[0] & 0x0f; if (Diag::WEBSOCKET) DIAG(F("Websock in: %x %x %x %x %x %x %x"), buffer[0],buffer[1],buffer[2],buffer[3], buffer[4],buffer[5],buffer[6]); byte opcode=buffer[0]; bool maskbit=buffer[1]&0x80; int16_t payloadLength=buffer[1]&0x7f; byte * mask; if (payloadLength<126) { mask=buffer+2; } else { // bytes 2 and 3 are the big-endian payload length payloadLength=(buffer[2]<<8)|(buffer[3]); mask=buffer+4; } if (Diag::WEBSOCKET) DIAG(F("Websock op=%x mb=%b pl=%d m=%x %x %x %x"), opcode, maskbit, payloadLength, mask[0],mask[1],mask[2], mask[3]); if (opcode==0x89) { // ping DIAG(F("Websock ping")); buffer[0]=0x8a; // pong.. and send it back ring->mark(clientId &0x7f); // dont readjust ring->print((char *)buffer); ring->commit(); return nullptr; } if (opcode==0x88) { // close DIAG(F("Websock close")); // Echo back an unmasked close frame (server-to-client frames are never masked) buffer[0]=0x88; buffer[1]=0x00; ring->mark(clientId & 0x7f); // dont readjust ring->write((uint8_t *)buffer, 2); ring->commit(); return nullptr; // no payload to process } if (opcode!=0x81) { DIAG(F("Websock unknown opcode 0x%x"),opcode); return nullptr; } byte * payload=mask+4; for (int i=0;i=126)? 4:2; } int Websockets::fillOutboundHeader(uint16_t dataLength, byte * buffer) { // text opcode, flag(126= use 2 length bytes, no mask bit) , length buffer[0]=0x81; if (dataLength<126) { buffer[1]=(byte)dataLength; return 2; } buffer[1]=126; buffer[2]=(byte)(dataLength >> 8); buffer[3]=(byte)(dataLength & 0xFF); return 4; } void Websockets::writeOutboundHeader(Print * stream,uint16_t dataLength) { byte prefix[4]; int headerlen=fillOutboundHeader(dataLength,prefix); stream->write(prefix,headerlen); } ================================================ FILE: Websockets.h ================================================ /* * © 2023 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 . */ #ifndef Websockets_h #define Websockets_h #include #include "RingStream.h" class Websockets { public: static bool checkConnectionString(byte clientId,byte * cmd, RingStream * outbound ); static byte * unmask(byte clientId,RingStream *ring, byte * buffer); static int16_t getOutboundHeaderSize(uint16_t dataLength); static int fillOutboundHeader(uint16_t dataLength, byte * buffer); static void writeOutboundHeader(Print * stream,uint16_t dataLength); static const byte WEBSOCK_CLIENT_MARKER=0x80; }; #endif ================================================ FILE: WiThrottle.cpp ================================================ /* * © 2021 Neil McKechnie * © 2021 Mike S * © 2020-2022 Harald Barth * © 2020-2021 M Steve Todd * © 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 . */ /* * Truncated JMRI WiThrottle server implementation for DCC-EX command station * Credit is due to Valerie Valley RR https://sites.google.com/site/valerievalleyrr/ * for showing how it could be done, but this code is very different to the original * implementation as it is designed to run on the Arduino and not the ESP and is * also calling directly into the DCCEX Api rather than simulating JMRI text commands. * Refer JMRI WiFi Throttle Communications Protocol https://www.jmri.org/help/en/package/jmri/jmrit/withrottle/Protocol.shtml * * * PROTOTYPE NOTES: * There will be one WiThrottle instance created for each WiThrottle client detected by the WifiInterface. * Some shortcuts have been taken and there are some things that are yet to be included: * e.g. Full response to adding a loco. * What to do about unknown turnouts. * Broadcasting to other WiThrottles when things change. * - Bear in mind that changes may have taken place due to * other WiThrottles, OR JMRI commands received OR TPL automation. * - I suggest that at the end of parse(), then anything that has changed and is of interest could * be notified then. (e.g loco speeds, directions or functions, turnout states. * * WiThrottle.h sets the max locos per client at 10, this is ok to increase but requires just an extra 3 bytes per loco per client. */ #include #include "defines.h" #include "WiThrottle.h" #include "DCC.h" #include "DCCWaveform.h" #include "StringFormatter.h" #include "Turnouts.h" #include "DIAG.h" #include "GITHUB_SHA.h" #include "version.h" #include "EXRAIL2.h" #include "CommandDistributor.h" #include "TrackManager.h" #include "DCCTimer.h" #define LOOPLOCOS(THROTTLECHAR, CAB) for (int loco=0;loconextThrottle) if (wt->clientid==wifiClient) return wt; return new WiThrottle( wifiClient); } void WiThrottle::forget( byte clientId) { for (WiThrottle* wt=firstThrottle; wt!=NULL ; wt=wt->nextThrottle) if (wt->clientid==clientId) { DIAG(F("Withrottle client %d dropped"),clientId); delete wt; break; } } bool WiThrottle::isThrottleInUse(int cab) { for (WiThrottle* wt=firstThrottle; wt!=NULL ; wt=wt->nextThrottle) if (wt->areYouUsingThrottle(cab)) return true; return false; } bool WiThrottle::areYouUsingThrottle(int cab) { LOOPLOCOS('*', cab) { // see if I have this cab in use return true; } return false; } // One instance of WiThrottle per connected client, so we know what the locos are WiThrottle::WiThrottle( int wificlientid) { if (Diag::WITHROTTLE) DIAG(F("%l Creating new WiThrottle for client %d"),millis(),wificlientid); nextThrottle=firstThrottle; firstThrottle= this; clientid=wificlientid; heartBeatEnable=false; // until client turns it on mostRecentCab=0; for (int loco=0;lococlientid); if (firstThrottle== this) { firstThrottle=this->nextThrottle; return; } for (WiThrottle* wt=firstThrottle; wt!=NULL ; wt=wt->nextThrottle) { if (wt->nextThrottle==this) { wt->nextThrottle=this->nextThrottle; return; } } } void WiThrottle::parse(RingStream * stream, byte * cmdx) { byte * cmd=cmdx; heartBeat=millis(); if (Diag::WITHROTTLE) DIAG(F("%l WiThrottle(%d)<-[%e]"),millis(),clientid,cmd); // On first few commands, send turnout, roster and routes if (introSent) { if (!turnoutsSent) sendTurnouts(stream); else if(!rosterSent) sendRoster(stream); else if (!routesSent) sendRoutes(stream); else if (!heartrateSent) { heartrateSent=true; // allow heartbeat to slow down once all metadata sent StringFormatter::send(stream,F("*%d\nHMConnected\n"),HEARTBEAT_SECONDS); } } while (cmd[0]) { switch (cmd[0]) { case '*': // heartbeat control if (cmd[1]=='+') heartBeatEnable=true; else if (cmd[1]=='-') heartBeatEnable=false; break; case 'P': if (cmd[1]=='P' && cmd[2]=='A' ) { //PPA power mode TrackManager::setMainPower(cmd[3]=='1'?POWERMODE::ON:POWERMODE::OFF); /* TODO if (MotorDriver::commonFaultPin) // commonFaultPin prevents individual track handling DCCWaveform::progTrack.setPowerMode(cmd[3]=='1'?POWERMODE::ON:POWERMODE::OFF); */ } #if defined(EXRAIL_ACTIVE) else if (cmd[1]=='R' && cmd[2]=='A' && cmd[3]=='2' ) { // Route activate // exrail routes are RA2Rn , Animations are RA2An int route=getInt(cmd+5); uint16_t cab=cmd[4]=='A' ? mostRecentCab : 0; RMFT2::createNewTask(route, cab); } #endif else if (cmd[1]=='T' && cmd[2]=='A') { // PTA accessory toggle int id=getInt(cmd+4); if (!Turnout::exists(id)) { // If turnout does not exist, create it int addr = ((id - 1) / 4) + 1; int subaddr = (id - 1) % 4; DCCTurnout::create(id,addr,subaddr); StringFormatter::send(stream, F("HmTurnout %d created\n"),id); } switch (cmd[3]) { // T and C according to RCN-213 where 0 is Stop, Red, Thrown, Diverging. case 'T': Turnout::setClosed(id,false); break; case 'C': Turnout::setClosed(id,true); break; case '2': Turnout::setClosed(id,!Turnout::isClosed(id)); break; default : Turnout::setClosed(id,true); break; } StringFormatter::send(stream, F("PTA%c%d\n"),Turnout::isClosed(id)?'2':'4',id ); } break; case 'N': // Heartbeat (2), only send if connection completed by 'HU' message sendIntro(stream); StringFormatter::send(stream, F("*%d\n"), heartrateSent ? HEARTBEAT_SECONDS : HEARTBEAT_PRELOAD); // return timeout value break; case 'M': // multithrottle multithrottle(stream, cmd); break; case 'H': // send initial connection info after receiving "HU" message if (cmd[1] == 'U') { sendIntro(stream); } break; case 'Q': // LOOPLOCOS('*', -1) { // tell client to drop any locos still assigned to this WiThrottle if (myLocos[loco].throttle!='\0') { StringFormatter::send(stream, F("M%c-%c%d<;>\n"), myLocos[loco].throttle, LorS(myLocos[loco].cab), myLocos[loco].cab); } } if (Diag::WITHROTTLE) DIAG(F("WiThrottle(%d) Quit"),clientid); delete this; break; } // skip over cmd until 0 or past \r or \n while(*cmd !='\0' && *cmd != '\r' && *cmd !='\n') cmd++; if (*cmd!='\0') cmd++; // skip \r or \n } } int WiThrottle::getInt(byte * cmd) { int i=0; bool negate=cmd[0]=='-'; if (negate) cmd++; while (cmd[0]>='0' && cmd[0]<='9') { i=i*10 + (cmd[0]-'0'); cmd++; } if (negate) i=0-i; return i ; } int WiThrottle::getLocoId(byte * cmd) { if (cmd[0]=='*') return -1; // match all locos if (cmd[0]!='L' && cmd[0]!='S') return 0; // should not match any locos return getInt(cmd+1); } void WiThrottle::multithrottle(RingStream * stream, byte * cmd){ char throttleChar=cmd[1]; int locoid=getLocoId(cmd+3); // -1 for * if (locoid > 10239 || locoid < -1) { StringFormatter::send(stream, F("No valid DCC loco %d\n"), locoid); return; } byte * aval=cmd; while(*aval !=';' && *aval !='\0') aval++; if (*aval) aval+=2; // skip ;> // DIAG(F("Multithrottle aval=%c cab=%d"), aval[0],locoid); switch(cmd[2]) { case '+': // add loco request if (cmd[3]=='*') { // M+* means get loco from prog track, then join tracks ready to drive away // Stash the things the callback will need later stashStream= stream; stashClient=stream->peekTargetMark(); stashThrottleChar=throttleChar; stashInstance=this; // ask DCC to call us back when the loco id has been read DCC::getDriveawayLocoId(getLocoCallback); // will remove any previous join return; // return nothing in stream as response is sent later in the callback } //return error if address zero requested if (locoid==0) { StringFormatter::send(stream, F("HMAddress '0' not supported!\n"), cmd[3] ,locoid); return; } //return error if L or S from request doesn't match DCC++ assumptions if (cmd[3] != LorS(locoid)) { StringFormatter::send(stream, F("HMLength '%c' not valid for %d!\n"), cmd[3] ,locoid); return; } //return error if loco slots or ram full if (!LocoSlot::getSlot(locoid,true)) { StringFormatter::send(stream, F("HMUnable to create loco %d slot\n"), locoid); return; } //use first empty "slot" on this client's list, will be added to DCC registration list for (int loco=0;loco\n"), throttleChar, cmd[3] ,locoid); //tell client to add loco sendFunctions(stream,loco); //speed and direction will be published at next broadcast cycle StringFormatter::send(stream, F("M%cA%c%d<;>s1\n"), throttleChar, cmd[3], locoid); //default speed step 128 return; } } StringFormatter::send(stream, F("HMMax locos (%d) exceeded, %d not added!\n"), MAX_MY_LOCO ,locoid); break; case '-': // remove loco(s) from this client (leave in DCC registration) LOOPLOCOS(throttleChar, locoid) { myLocos[loco].throttle='\0'; StringFormatter::send(stream, F("M%c-%c%d<;>\n"), throttleChar, LorS(myLocos[loco].cab), myLocos[loco].cab); } break; case 'A': locoAction(stream,aval, throttleChar, locoid); } } void WiThrottle::locoAction(RingStream * stream, byte* aval, char throttleChar, int cab){ // Note cab=-1 for all cabs in the consist called throttleChar. // DIAG(F("Loco Action aval=%c%c throttleChar=%c, cab=%d"), aval[0],aval[1],throttleChar, cab); (void) stream; switch (aval[0]) { case 'V': // Vspeed { int witSpeed=getInt(aval+1); LOOPLOCOS(throttleChar, cab) { mostRecentCab=myLocos[loco].cab; DCC::setThrottle(myLocos[loco].cab, WiTToDCCSpeed(witSpeed), DCC::getThrottleDirection(myLocos[loco].cab)); // SetThrottle will cause speed change broadcast } } break; case 'F': // Function key pressed/released { bool pressed=aval[1]=='1'; int fKey = getInt(aval+2); LOOPLOCOS(throttleChar, cab) { bool unsetOnRelease = myLocos[loco].functionToggles & (1L<nextThrottle) wt->checkHeartbeat(stream); } void WiThrottle::checkHeartbeat(RingStream * stream) { // if eStop time passed... eStop any locos still assigned to this client and then drop the connection if(heartBeatEnable && (millis()-heartBeat > ESTOP_SECONDS*1000)) { if (Diag::WITHROTTLE) DIAG(F("%l WiThrottle(%d) eStop(%ds) timeout, drop connection"), millis(), clientid, ESTOP_SECONDS); LOOPLOCOS('*', -1) { if (myLocos[loco].throttle!='\0') { if (Diag::WITHROTTLE) DIAG(F("%l eStopping cab %d"),millis(),myLocos[loco].cab); DCC::setThrottle(myLocos[loco].cab, 1, DCC::getThrottleDirection(myLocos[loco].cab)); // speed 1 is eStop heartBeat=millis(); // We have just stopped everyting, we don't need to do that again at next loop. } } // if it does come back, the throttle should re-acquire delete this; return; } // send any outstanding speed/direction/function changes for this clients locos // Changes may have been caused by this client, or another non-Withrottle or Exrail bool streamHasBeenMarked=false; LOOPLOCOS('*', -1) { if (myLocos[loco].throttle!='\0' && myLocos[loco].broadcastPending) { if (!streamHasBeenMarked) { stream->mark(clientid); streamHasBeenMarked=true; } myLocos[loco].broadcastPending=false; int cab=myLocos[loco].cab; char lors=LorS(cab); char throttle=myLocos[loco].throttle; StringFormatter::send(stream,F("M%cA%c%d<;>V%d\n"), throttle, lors , cab, DCCToWiTSpeed(DCC::getThrottleSpeed(cab))); StringFormatter::send(stream,F("M%cA%c%d<;>R%d\n"), throttle, lors , cab, DCC::getThrottleDirection(cab)); // compare the DCC functionmap with the local copy and send changes uint32_t dccFunctionMap=DCC::getFunctionMap(cab); uint32_t myFunctionMap=myLocos[loco].functionMap; myLocos[loco].functionMap=dccFunctionMap; // loop the maps sending any bit changed // Loop is terminated as soon as no changes are left for (byte fn=0;dccFunctionMap!=myFunctionMap;fn++) { if ((dccFunctionMap&1) != (myFunctionMap&1)) { StringFormatter::send(stream,F("M%cA%c%d<;>F%c%d\n"), throttle, lors , cab, (dccFunctionMap&1)?'1':'0',fn); } // shift just checked bit off end of both maps dccFunctionMap>>=1; myFunctionMap>>=1; } } } if (streamHasBeenMarked) stream->commit(); } void WiThrottle::markForBroadcast(int cab) { for (WiThrottle* wt=firstThrottle; wt!=NULL ; wt=wt->nextThrottle) wt->markForBroadcast2(cab); } void WiThrottle::markForBroadcast2(int cab) { LOOPLOCOS('*', cab) { myLocos[loco].broadcastPending=true; } } char WiThrottle::LorS(int cab) { return (cab<=HIGHEST_SHORT_ADDR)?'S':'L'; } // Drive Away feature. Callback handling RingStream * WiThrottle::stashStream; WiThrottle * WiThrottle::stashInstance; byte WiThrottle::stashClient; char WiThrottle::stashThrottleChar; void WiThrottle::getLocoCallback(int16_t locoid) { //DIAG(F("LocoCallback mark client %d"), stashClient); stashStream->mark(stashClient); if (locoid<=0) { StringFormatter::send(stashStream,F("HMNo loco found on prog track\n")); //DIAG(F("LocoCallback commit (noloco)")); stashStream->commit(); // done here, commit and return return; } // short or long char addrchar; if (locoid & LONG_ADDR_MARKER) { // maker bit indicates long addr locoid = locoid ^ LONG_ADDR_MARKER; // remove marker bit to get real long addr if (locoid <= HIGHEST_SHORT_ADDR ) { // out of range for long addr StringFormatter::send(stashStream,F("HMLong addr %d <= %d unsupported\n"), locoid, HIGHEST_SHORT_ADDR); //DIAG(F("LocoCallback commit (error)")); stashStream->commit(); // done here, commit and return return; } addrchar = 'L'; } else { addrchar = 'S'; } char addcmd[20]={'M',stashThrottleChar,'+', addrchar}; itoa(locoid,addcmd+4,10); stashInstance->multithrottle(stashStream, (byte *)addcmd); TrackManager::setJoin(true); // <1 JOIN> so we can drive loco away TrackManager::setMainPower(POWERMODE::ON); TrackManager::setProgPower(POWERMODE::ON); DIAG(F("LocoCallback commit success")); stashStream->commit(); } void WiThrottle::sendIntro(Print* stream) { if (introSent) // sendIntro only once return; introSent=true; StringFormatter::send(stream,F("VN2.0\nHTDCC-EX\nRL0\n")); StringFormatter::send(stream,F("HtDCC-EX v%S, %S, %S, %S\n"), F(VERSION), F(ARDUINO_TYPE), DCC::getMotorShieldName(), F(GITHUB_SHA)); StringFormatter::send(stream,F("PTT]\\[Turnouts}|{Turnout]\\[THROW}|{2]\\[CLOSE}|{4\n")); StringFormatter::send(stream,F("PPA%x\n"),TrackManager::getMainPower()==POWERMODE::ON); // set heartbeat to 2 seconds because we need to sync the metadata (1 second is too short!) StringFormatter::send(stream,F("*%d\nHMConnecting..\n"), HEARTBEAT_PRELOAD); } void WiThrottle::sendTurnouts(Print* stream) { turnoutsSent=true; StringFormatter::send(stream,F("PTL")); for(Turnout *tt=Turnout::first();tt!=NULL;tt=tt->next()){ if (tt->isHidden()) continue; int id=tt->getId(); const FSH * tdesc=NULL; #ifdef EXRAIL_ACTIVE tdesc=RMFT2::getTurnoutDescription(id); #endif char tchar=Turnout::isClosed(id)?'2':'4'; if (tdesc==NULL) // turnout with no description StringFormatter::send(stream,F("]\\[%d}|{T%d}|{T%c"), id,id,tchar); else StringFormatter::send(stream,F("]\\[%d}|{%S}|{%c"), id,tdesc,tchar); } StringFormatter::send(stream,F("\n")); } void WiThrottle::sendRoster(Print* stream) { rosterSent=true; #ifdef EXRAIL_ACTIVE StringFormatter::send(stream,F("RL%d"), RMFT2::rosterNameCount); for (int16_t r=0;;r++) { int16_t cabid=GETHIGHFLASHW(RMFT2::rosterIdList,r*2); if (cabid == INT16_MAX) break; if (cabid > 0) StringFormatter::send(stream,F("]\\[%S}|{%d}|{%c"), RMFT2::getRosterName(cabid),cabid,cabid<128?'S':'L'); } StringFormatter::send(stream,F("\n")); #else (void)stream; // remove warning #endif } void WiThrottle::sendRoutes(Print* stream) { routesSent=true; #ifdef EXRAIL_ACTIVE StringFormatter::send(stream,F("PRT]\\[Routes}|{Route]\\[Set}|{2]\\[Handoff}|{4\nPRL")); // first pass automations for (int ix=0;;ix+=2) { int16_t id =GETHIGHFLASHW(RMFT2::automationIdList,ix); if (id==INT16_MAX) break; const FSH * desc=RMFT2::getRouteDescription(id); StringFormatter::send(stream,F("]\\[A%d}|{%S}|{4"),id,desc); } // second pass routes. for (int ix=0;;ix+=2) { int16_t id=GETHIGHFLASHW(RMFT2::routeIdList,ix); if (id==INT16_MAX) break; const FSH * desc=RMFT2::getRouteDescription(id); StringFormatter::send(stream,F("]\\[R%d}|{%S}|{2"),id,desc); } StringFormatter::send(stream,F("\n")); #else (void)stream; // remove warning #endif } void WiThrottle::sendFunctions(Print* stream, byte loco) { int16_t locoid=myLocos[loco].cab; int fkeys=32; // upper limit (send functions 0 to 31) myLocos[loco].functionToggles=1<<2; // F2 (HORN) is a non-toggle #ifdef EXRAIL_ACTIVE const FSH * functionNames= RMFT2::getRosterFunctions(locoid); if (functionNames == NULL) { // no roster entry for locoid, try to find default entry functionNames= RMFT2::getRosterFunctions(0); } if (functionNames == NULL) { // no default roster entry either, use non-exrail presets as above } else if (GETFLASH(functionNames)=='\0') { // "" = Roster but no functions given fkeys=0; } else { // we have function names... // scan names list emitting names, counting functions and // flagging non-toggling things like horn. myLocos[loco].functionToggles =0; StringFormatter::send(stream, F("M%cL%c%d<;>]\\["), myLocos[loco].throttle,LorS(locoid),locoid); fkeys=0; bool firstchar=true; for (int fx=0;;fx++) { char c=GETFLASH((char *)functionNames+fx); if (c=='\0') { fkeys++; break; } if (c=='/') { fkeys++; StringFormatter::send(stream,F("]\\[")); firstchar=true; } else if (firstchar && c=='*') { myLocos[loco].functionToggles |= 1UL<write(c); } } StringFormatter::send(stream,F("\n")); } #endif for(int fKey=0; fKey=0) StringFormatter::send(stream,F("M%cA%c%d<;>F%d%d\n"),myLocos[loco].throttle,LorS(locoid),locoid,fstate,fKey); } } ================================================ FILE: WiThrottle.h ================================================ /* * © 2021 Mike S * © 2020-2021 Chris Harlow * 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 . */ #ifndef WiThrottle_h #define WiThrottle_h #include "RingStream.h" struct MYLOCO { char throttle; //indicates which throttle letter on client, often '0','1' or '2' int cab; //address of this loco bool broadcastPending; uint32_t functionMap; uint32_t functionToggles; }; class WiThrottle { public: static void loop(RingStream * stream); void parse(RingStream * stream, byte * cmd); static WiThrottle* getThrottle( int wifiClient); static void markForBroadcast(int cab); static void forget(byte clientId); static void findUniqThrottle(int id, char *u); private: WiThrottle( int wifiClientId); ~WiThrottle(); static const int MAX_MY_LOCO=10; // maximum number of locos assigned to a single client static const int HEARTBEAT_SECONDS=10; // heartbeat at 10 secs to provide messaging transport static const int HEARTBEAT_PRELOAD=2; // request fast callback when connecting multiple messages static const int ESTOP_SECONDS=20; // eStop if no incoming messages for more than 8secs static WiThrottle* firstThrottle; static int getInt(byte * cmd); static int getLocoId(byte * cmd); static char LorS(int cab); static bool isThrottleInUse(int cab); static void setSendTurnoutList(); bool areYouUsingThrottle(int cab); WiThrottle* nextThrottle; int clientid; char uniq[17] = ""; MYLOCO myLocos[MAX_MY_LOCO]; bool heartBeatEnable; unsigned long heartBeat; bool introSent=false; bool turnoutsSent=false; bool rosterSent=false; bool routesSent=false; bool heartrateSent=false; uint16_t mostRecentCab; bool lastPowerState; // last power state sent to this client int DCCToWiTSpeed(int DCCSpeed); int WiTToDCCSpeed(int WiTSpeed); void multithrottle(RingStream * stream, byte * cmd); void locoAction(RingStream * stream, byte* aval, char throttleChar, int cab); void accessory(RingStream *, byte* cmd); void checkHeartbeat(RingStream * stream); void markForBroadcast2(int cab); void sendIntro(Print * stream); void sendTurnouts(Print * stream); void sendRoster(Print * stream); void sendRoutes(Print * stream); void sendFunctions(Print* stream, byte loco); // callback stuff to support prog track acquire static RingStream * stashStream; static WiThrottle * stashInstance; static byte stashClient; static char stashThrottleChar; static void getLocoCallback(int16_t locoid); }; #endif ================================================ FILE: WifiESP32.cpp ================================================ /* © 2023 Paul M. Antoine © 2021 Harald Barth © 2023 Nathan Kellenicki © 2025 Chris Harlow 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 . */ #if defined(ARDUINO_ARCH_ESP32) #include #include "defines.h" #include "ESPmDNS.h" #include "esp_wifi.h" #include "WifiESP32.h" #include "DIAG.h" #include "RingStream.h" #include "CommandDistributor.h" #include "WiThrottle.h" #include "DCC.h" #include "Websockets.h" /* #include "soc/rtc_wdt.h" #include "esp_task_wdt.h" */ #include "soc/timer_group_struct.h" #include "soc/timer_group_reg.h" void feedTheDog0(){ // feed dog 0 TIMERG0.wdt_wprotect=TIMG_WDT_WKEY_VALUE; // write enable TIMERG0.wdt_feed=1; // feed dog TIMERG0.wdt_wprotect=0; // write protect // feed dog 1 //TIMERG1.wdt_wprotect=TIMG_WDT_WKEY_VALUE; // write enable //TIMERG1.wdt_feed=1; // feed dog //TIMERG1.wdt_wprotect=0; // write protect } /* void enableCoreWDT(byte core){ TaskHandle_t idle = xTaskGetIdleTaskHandleForCPU(core); if(idle == NULL){ DIAG(F("Get idle rask on core %d failed"),core); } else { if(esp_task_wdt_add(idle) != ESP_OK){ DIAG(F("Failed to add Core %d IDLE task to WDT"),core); } else { DIAG(F("Added Core %d IDLE task to WDT"),core); } } } void disableCoreWDT(byte core){ TaskHandle_t idle = xTaskGetIdleTaskHandleForCPU(core); if(idle == NULL || esp_task_wdt_delete(idle) != ESP_OK){ DIAG(F("Failed to remove Core %d IDLE task from WDT"),core); } } */ class NetworkClient { public: NetworkClient(WiFiClient c) { wifi = c; inUse = true; }; bool active(byte clientId) { if (!inUse) return false; if(!wifi.connected()) { DIAG(F("Remove client %d"), clientId); CommandDistributor::forget(clientId); wifi.stop(); inUse = false; return false; } return true; } bool recycle(WiFiClient c) { if (wifi == c) { if (inUse == true) DIAG(F("WARNING: Duplicate")); else DIAG(F("Returning")); inUse = true; return true; } if (inUse == false) { wifi = c; inUse = true; return true; } return false; }; WiFiClient wifi; private: bool inUse; }; // file scope variables static std::vector clients; // a list to hold all clients static RingStream *outboundRing = new RingStream(10240); static bool APmode = false; // init of static class scope variables bool WifiESP::wifiUp = false; WiFiServer *WifiESP::server = NULL; #ifdef WIFI_TASK_ON_CORE0 void wifiLoop(void *){ for(;;){ WifiESP::loop(); } } #endif char asciitolower(char in) { if (in <= 'Z' && in >= 'A') return in - ('Z' - 'z'); return in; } void WifiESP::teardown() { // stop all locos DCC::setThrottle(0,1,1); // this broadcasts speed 1(estop) and sets all reminders to speed 1. // terminate all clients connections while (!clients.empty()) { // pop_back() should invoke destructor which does stop() // on the underlying TCP connction clients.pop_back(); } // stop server if (server != NULL) { server->stop(); server->close(); server->end(); DIAG(F("server stop, close, end")); } // terminate MDNS anouncement mdns_service_remove_all(); mdns_free(); // stop WiFi WiFi.disconnect(true); wifiUp = false; } bool WifiESP::setup(const char *SSid, const char *password, const char *hostname, int port, const byte channel, const bool forceAP) { bool havePassword = true; bool haveSSID = true; // bool wifiUp = false; uint8_t tries = 40; if (wifiUp) teardown(); if (strcmp("OFF", SSid) == 0) { WiFi.disconnect(true); WiFi.mode(WIFI_OFF); return false; // debatable if that is true (success) or false (no network) } //#ifdef SERIAL_BT_COMMANDS //return false; //#endif // tests // enableCoreWDT(1); // disableCoreWDT(0); #ifdef WIFI_LED // Turn off Wifi LED pinMode(WIFI_LED, OUTPUT); digitalWrite(WIFI_LED, 0); #endif // clean start WiFi.mode(WIFI_STA); WiFi.disconnect(true); // differnet settings that did not improve for haba // WiFi.useStaticBuffers(true); // WiFi.setScanMethod(WIFI_ALL_CHANNEL_SCAN); // WiFi.setSortMethod(WIFI_CONNECT_AP_BY_SECURITY); const char *yourNetwork = "Your network "; if (strncmp(yourNetwork, SSid, 13) == 0 || strncmp("", SSid, 13) == 0) haveSSID = false; if (strncmp(yourNetwork, password, 13) == 0 || strncmp("", password, 13) == 0) havePassword = false; if (haveSSID && havePassword && !forceAP) { WiFi.setHostname(hostname); // Strangely does not work unless we do it HERE! WiFi.mode(WIFI_STA); WiFi.setScanMethod(WIFI_ALL_CHANNEL_SCAN); // Scan all channels so we find strongest // (default in Wifi library is first match) #ifdef SERIAL_BT_COMMANDS WiFi.setSleep(true); #else WiFi.setSleep(false); #endif WiFi.setAutoReconnect(true); WiFi.begin(SSid, password); while (WiFi.status() != WL_CONNECTED && tries) { Serial.print('.'); tries--; delay(500); } if (WiFi.status() == WL_CONNECTED) { // DIAG(F("Wifi STA IP %s"),WiFi.localIP().toString().c_str()); DIAG(F("Wifi in STA mode")); LCD(7, F("IP: %s"), WiFi.localIP().toString().c_str()); wifiUp = true; } else { DIAG(F("Could not connect to Wifi SSID %s"),SSid); DIAG(F("Forcing one more Wifi restart")); esp_wifi_start(); esp_wifi_connect(); tries=40; while (WiFi.status() != WL_CONNECTED && tries) { Serial.print('.'); tries--; delay(500); } if (WiFi.status() == WL_CONNECTED) { DIAG(F("Wifi STA IP 2nd try %s"),WiFi.localIP().toString().c_str()); wifiUp = true; } else { DIAG(F("Wifi STA mode FAIL. Will revert to AP mode")); wifiUp=false; } } } if (!wifiUp || forceAP) { // prepare all strings String strMac; if (!haveSSID || !havePassword) { strMac = WiFi.macAddress(); strMac.remove(0,9); strMac.replace(":",""); strMac.replace(":",""); // convert mac addr hex chars to lower case to be compatible with AT software std::transform(strMac.begin(), strMac.end(), strMac.begin(), asciitolower); } String strSSID; if (!haveSSID) { strSSID.concat("DCCEX_"); strSSID.concat(strMac); } else { strSSID.concat(SSid); } String strPass; if (!havePassword) { strPass.concat("PASS_"); strPass.concat(strMac); } else { strPass.concat(password); } WiFi.mode(WIFI_AP); #ifdef SERIAL_BT_COMMANDS WiFi.setSleep(true); #else WiFi.setSleep(false); #endif #ifdef WIFI_HIDE_SSID const bool hiddenAP = true; #else const bool hiddenAP = false; #endif if (WiFi.softAP(strSSID.c_str(), havePassword ? password : strPass.c_str(), channel, hiddenAP, 8)) { // DIAG(F("Wifi AP SSID %s PASS %s"),strSSID.c_str(),havePassword ? password : strPass.c_str()); DIAG(F("Wifi in AP mode")); LCD(5, F("Wifi: %s"), strSSID.c_str()); if (!havePassword) LCD(6, F("PASS: %s"),strPass.c_str()); // DIAG(F("Wifi AP IP %s"),WiFi.softAPIP().toString().c_str()); LCD(7, F("IP: %s"),WiFi.softAPIP().toString().c_str()); wifiUp = true; APmode = true; } else { DIAG(F("Could not set up AP with Wifi SSID %s"),strSSID.c_str()); } } if (!wifiUp) { DIAG(F("Wifi setup all fail (STA and AP mode)")); // no idea to go on return false; } #ifdef WIFI_LED else{ // Turn on Wifi connected LED digitalWrite(WIFI_LED, 1); } #endif // Now Wifi is up, register the mDNS service if(!MDNS.begin(hostname)) { DIAG(F("Wifi setup failed to start mDNS")); } if(!MDNS.addService("withrottle", "tcp", port)) { DIAG(F("Wifi setup failed to add withrottle service to mDNS")); } server = new WiFiServer(port); // start listening on tcp port server->begin(); // server started here #ifdef WIFI_TASK_ON_CORE0 //start loop task if (pdPASS != xTaskCreatePinnedToCore( wifiLoop, /* Task function. */ "wifiLoop",/* name of task. */ 10000, /* Stack size of task */ NULL, /* parameter of the task */ 1, /* priority of the task */ NULL, /* Task handle to keep track of created task */ 0)) { /* pin task to core 0 */ DIAG(F("Could not create wifiLoop task")); return false; } // report server started after wifiLoop creation // when everything looks good DIAG(F("Server starting (core 0) port %d"),port); #else DIAG(F("Server will be started on port %d"),port); #endif return true; } const char *wlerror[] = { "WL_IDLE_STATUS", "WL_NO_SSID_AVAIL", "WL_SCAN_COMPLETED", "WL_CONNECTED", "WL_CONNECT_FAILED", "WL_CONNECTION_LOST", "WL_DISCONNECTED" }; void WifiESP::loop() { int clientId; //tmp loop var // really no good way to check for LISTEN especially in AP mode? wl_status_t wlStatus; if (APmode || (wlStatus = WiFi.status()) == WL_CONNECTED) { if (server->hasClient()) { WiFiClient client; while (client = server->available()) { for (clientId=0; clientId=clients.size()) { NetworkClient nc(client); clients.push_back(nc); DIAG(F("New client %d, %s:%d"), clientId, client.remoteIP().toString().c_str(),client.remotePort()); } } } // loop over all connected clients // this removes as a side effect inactive clients when checking ::active() for (clientId=0; clientId 0) { // read data from client byte cmd[len+1]; for(int i=0; iread(); bool useWebsocket=clientId & Websockets::WEBSOCK_CLIENT_MARKER; clientId &= ~ Websockets::WEBSOCK_CLIENT_MARKER; if (clientId >= 0) { // We have data to send in outboundRing // and we have a valid clientId. // First read it out to buffer // and then look if it can be sent because // we can not leave it in the ring for ever int count=outboundRing->count(); auto wsHeaderLen=useWebsocket? Websockets::getOutboundHeaderSize(count) : 0; { byte buffer[wsHeaderLen + count + 1]; // one extra for '\0' if (useWebsocket) Websockets::fillOutboundHeader(count, buffer); for (int i = 0; i < count; i++) { int c = outboundRing->read(); if (!c) { DIAG(F("Ringread fail at %d"), i); break; } // websocket implementations at browser end can barf at \n if (useWebsocket && (c == '\n')) c = '\r'; buffer[i + wsHeaderLen] = (char)c; } // buffer filled, end with '\0' so we can use it as C string buffer[wsHeaderLen+count]='\0'; if((unsigned int)clientId <= clients.size()) { if (clients[clientId].active(clientId)) { if (Diag::WIFI) DIAG(F("SEND%S %d:%s"), useWebsocket?F("ws"):F(""),clientId, buffer+wsHeaderLen); clients[clientId].wifi.write(buffer,count+wsHeaderLen); } else { // existed but not active DIAG(F("Unsent(%d): %s"), clientId, buffer+wsHeaderLen); } } else { DIAG(F("Non existent client %d has message: %s"), clientId, buffer+wsHeaderLen); } } } } else if (!APmode) { // in STA mode but not connected any more // kick it again if (wlStatus <= 6) { DIAG(F("Wifi aborted with error %s. Kicking Wifi!"), wlerror[wlStatus]); esp_wifi_start(); esp_wifi_connect(); uint8_t tries=40; while (WiFi.status() != WL_CONNECTED && tries) { Serial.print('.'); tries--; delay(500); } } else { // all well, probably //DIAG(F("Running BT")); } } // when loop() is running on core0 we must // feed the core0 wdt ourselves as yield() // is not necessarily yielding to a low // prio task. On core1 this is not a problem // as there the wdt is disabled by the // arduio IDE startup routines. if (xPortGetCoreID() == 0) { feedTheDog0(); yield(); } } #endif //ESP32 ================================================ FILE: WifiESP32.h ================================================ /* * © 2021 Harald Barth * © 2023 Nathan Kellenicki * * 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 . */ #if defined(ARDUINO_ARCH_ESP32) #ifndef WifiESP32_h #define WifiESP32_h #include #include "FSH.h" class WifiESP { public: static bool setup(const char *wifiESSID, const char *wifiPassword, const char *hostname, const int port, const byte channel, const bool forceAP); static void loop(); private: static void teardown(); static bool wifiUp; static WiFiServer *server; }; #endif //WifiESP8266_h #endif //ESP8266 ================================================ FILE: WifiInboundHandler.cpp ================================================ /* * © 2021 Fred Decker * © 2021 Fred Decker * © 2020-2025 Chris Harlow * © 2020, Chris Harlow. All rights reserved. * © 2020, Harald Barth. * * 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 . */ #ifndef ARDUINO_AVR_UNO_WIFI_REV2 #include #include "WifiInboundHandler.h" #include "RingStream.h" #include "CommandDistributor.h" #include "DIAG.h" #include "Websockets.h" WifiInboundHandler * WifiInboundHandler::singleton; void WifiInboundHandler::setup(Stream * ESStream) { singleton=new WifiInboundHandler(ESStream); } void WifiInboundHandler::loop() { singleton->loop1(); } WifiInboundHandler::WifiInboundHandler(Stream * ESStream) { wifiStream=ESStream; clientPendingCIPSEND=-1; inboundRing=new RingStream(INBOUND_RING); outboundRing=new RingStream(OUTBOUND_RING); pendingCipsend=false; } // Handle any inbound transmission // +IPD,x,lll:data is stored in streamer[x] // Other input returns void WifiInboundHandler::loop1() { // First handle all inbound traffic events because they will block the sending if (loop2()!=INBOUND_IDLE) return; WiThrottle::loop(outboundRing); // if nothing is already CIPSEND pending, we can CIPSEND one reply if (clientPendingCIPSEND<0) { clientPendingCIPSEND=outboundRing->read(); if (clientPendingCIPSEND>=0) { currentReplySize=outboundRing->count(); pendingCipsend=true; } } if (pendingCipsend && millis()-lastCIPSEND > CIPSENDgap) { // add allowances for websockets bool websocket=clientPendingCIPSEND & Websockets::WEBSOCK_CLIENT_MARKER; byte realClient=clientPendingCIPSEND & ~Websockets::WEBSOCK_CLIENT_MARKER; int16_t realSize=currentReplySize; if (websocket) realSize+=Websockets::getOutboundHeaderSize(currentReplySize); if (Diag::WIFI) DIAG( F("WiFi: [[CIPSEND=%d,%d]]"), realClient, realSize); StringFormatter::send(wifiStream, F("AT+CIPSEND=%d,%d\r\n"), realClient,realSize); pendingCipsend=false; return; } // if something waiting to execute, we can call it int clientId=inboundRing->read(); if (clientId>=0) { int count=inboundRing->count(); if (Diag::WIFI) DIAG(F("Wifi EXEC: %d %d:"),clientId,count); byte cmd[count+1]; // Copy raw bytes to avoid websocket masked data being // confused with a ram-saving flash insert marker. for (int i=0;ireadRawByte(); cmd[count]=0; if (Diag::WIFI) DIAG(F("%e"),cmd); CommandDistributor::parse(clientId,cmd,outboundRing); return; } } // This is a Finite State Automation (FSA) handling the inbound bytes from an ES AT command processor WifiInboundHandler::INBOUND_STATE WifiInboundHandler::loop2() { const char WebSocketKeyName[]="Sec-WebSocket-Key: "; static byte prescanPoint=0; while (wifiStream->available()) { int ch = wifiStream->read(); // echo the char to the diagnostic stream in escaped format if (Diag::WIFI) { // DIAG(F(" %d/"), loopState); StringFormatter::printEscape(ch); // DIAG in disguise } switch (loopState) { case ANYTHING: // looking for +IPD, > , busy , n,CONNECTED, n,CLOSED, ERROR, SEND OK if (ch == '+') { loopState = IPD; break; } if (ch=='>') { bool websocket=clientPendingCIPSEND & Websockets::WEBSOCK_CLIENT_MARKER; if (Diag::WIFI) DIAG(F("[XMIT %d ws=%b]"),currentReplySize,websocket); if (websocket) Websockets::writeOutboundHeader(wifiStream,currentReplySize); for (int i=0;iread(); if (websocket && (cout=='\n')) cout='\r'; wifiStream->write(cout); if (Diag::WIFI) StringFormatter::printEscape(cout); // DIAG in disguise } clientPendingCIPSEND=-1; pendingCipsend=false; loopState=SKIPTOEND; break; } if (ch=='R') { // Received ... bytes loopState=SKIPTOEND; break; } if (ch=='S') { // SEND OK probably loopState=SKIPTOEND; lastCIPSEND=0; // no need to wait next time break; } if (ch=='b') { // This is a busy indicator... probabaly must restart a CIPSEND pendingCipsend=(clientPendingCIPSEND>=0); if (pendingCipsend) lastCIPSEND=millis(); // forces a gap to next CIPSEND loopState=SKIPTOEND; break; } if (ch>='0' && ch<='9') { runningClientId=ch-'0'; loopState=GOT_CLIENT_ID; break; } if (ch=='E' || ch=='l') { // ERROR or "link is not valid" if (clientPendingCIPSEND>=0) { // A CIPSEND was errored... just toss it away purgeCurrentCIPSEND(); } loopState=SKIPTOEND; break; } break; case IPD: // Looking for I in +IPD loopState = (ch == 'I') ? IPD1 : SKIPTOEND; break; case IPD1: // Looking for P in +IPD loopState = (ch == 'P') ? IPD2 : SKIPTOEND; break; case IPD2: // Looking for D in +IPD loopState = (ch == 'D') ? IPD3 : SKIPTOEND; break; case IPD3: // Looking for , After +IPD loopState = (ch == ',') ? IPD4_CLIENT : SKIPTOEND; break; case IPD4_CLIENT: // reading connection id if (ch >= '0' || ch <='9'){ runningClientId=ch-'0'; loopState=IPD5; } else loopState=SKIPTOEND; break; case IPD5: // Looking for , After +IPD,client loopState = (ch == ',') ? IPD6_LENGTH : SKIPTOEND; dataLength=0; // ready to start collecting the length break; case IPD6_LENGTH: // reading for length if (ch == ':') { if (dataLength==0) { loopState=ANYTHING; break; } if (Diag::WIFI) DIAG(F("Wifi inbound data(%d:%d):"),runningClientId,dataLength); // we normally dont read >100 bytes // so assume its an HTTP GET or similar if (dataLength<100 && inboundRing->freeSpace()<=(dataLength+1)) { // This input would overflow the inbound ring, ignore it loopState=IPD_IGNORE_DATA; if (Diag::WIFI) DIAG(F("Wifi OVERFLOW IGNORING:")); break; } inboundRing->mark(runningClientId); prescanPoint=0; loopState=(dataLength>100)? IPD_PRESCAN: IPD_DATA; break; } dataLength = dataLength * 10 + (ch - '0'); break; case IPD_DATA: // reading data inboundRing->write(ch); dataLength--; if (dataLength == 0) { inboundRing->commit(); loopState = ANYTHING; } break; case IPD_PRESCAN: // prescan reading data dataLength--; if (dataLength == 0) { // Nothing found, this input is lost DIAG(F("Wifi prescan for websock not found")); inboundRing->commit(); loopState = ANYTHING; } if (ch!=WebSocketKeyName[prescanPoint]) { prescanPoint=0; break; } // matched the next char of the key prescanPoint++; if (WebSocketKeyName[prescanPoint]==0) { if (Diag::WEBSOCKET) DIAG(F("Wifi prescan found")); // prescan has detected full key inboundRing->print(WebSocketKeyName); loopState=IPD_POSTSCAN; // continmue as normal } break; case IPD_POSTSCAN: // reading data inboundRing->write(ch); dataLength--; if (ch=='\n') { inboundRing->commit(); loopState = IPD_IGNORE_DATA; } break; case IPD_IGNORE_DATA: // ignoring data that would not fit in inbound ring dataLength--; if (dataLength == 0) loopState = ANYTHING; break; case GOT_CLIENT_ID: // got x before CLOSE or CONNECTED loopState=(ch==',') ? GOT_CLIENT_ID2: SKIPTOEND; break; case GOT_CLIENT_ID2: // got "x," if (ch=='C') { // got "x C" before CLOSE or CONNECTED, or CONNECT FAILED if (runningClientId==clientPendingCIPSEND) purgeCurrentCIPSEND(); else CommandDistributor::forget(runningClientId); } loopState=SKIPTOEND; break; case SKIPTOEND: // skipping for /n if (ch=='\n') loopState=ANYTHING; break; } // switch } // available return (loopState==ANYTHING) ? INBOUND_IDLE: INBOUND_BUSY; } void WifiInboundHandler::purgeCurrentCIPSEND() { // A CIPSEND was sent but errored... or the client closed just toss it away CommandDistributor::forget(clientPendingCIPSEND); DIAG(F("Wifi: DROPPING CIPSEND=%d,%d"),clientPendingCIPSEND,currentReplySize); for (int i=0;iread(); pendingCipsend=false; clientPendingCIPSEND=-1; } #endif ================================================ FILE: WifiInboundHandler.h ================================================ /* * © 2021 Harald Barth * © 2021 Fred Decker * (c) 2021 Fred Decker. All rights reserved. * (c) 2020-2025 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 . */ #ifndef WifiInboundHandler_h #define WifiInboundHandler_h #include "RingStream.h" #include "WiThrottle.h" #include "DIAG.h" class WifiInboundHandler { public: static void setup(Stream * ESStream); static void loop(); private: static WifiInboundHandler * singleton; enum INBOUND_STATE : byte { INBOUND_BUSY, // keep calling in loop() INBOUND_IDLE // Nothing happening, outbound may xcall CIPSEND }; enum LOOP_STATE : byte { ANYTHING, // ready for +IPD, n CLOSED, n CONNECTED, busy etc... SKIPTOEND, // skip to newline // +IPD,client,length:data IPD, // got + IPD1, // got +I IPD2, // got +IP IPD3, // got +IPD IPD4_CLIENT, // got +IPD, reading cient id IPD5, // got +IPD,c IPD6_LENGTH, // got +IPD,c, reading length IPD_DATA, // got +IPD,c,ll,: collecting data IPD_IGNORE_DATA, // got +IPD,c,ll,: ignoring the data that won't fit inblound Ring IPD_PRESCAN, // prescanning data for websocket keys IPD_POSTSCAN, // copyimg data for websocket keys GOT_CLIENT_ID, // clientid prefix to CONNECTED / CLOSED GOT_CLIENT_ID2 // clientid prefix to CONNECTED / CLOSED }; WifiInboundHandler(Stream * ESStream); void loop1(); INBOUND_STATE loop2(); void purgeCurrentCIPSEND(); Stream * wifiStream; static const int INBOUND_RING = 128; static const int OUTBOUND_RING = sizeof(void*)==2?2048:8192; static const int CIPSENDgap=100; // millis() between retries of cipsend. RingStream * inboundRing; RingStream * outboundRing; LOOP_STATE loopState=ANYTHING; int runningClientId; // latest client inbound processing data or CLOSE int dataLength; // dataLength of +IPD int clientPendingCIPSEND=-1; int currentReplySize; bool pendingCipsend; uint32_t lastCIPSEND=0; // millis() of previous cipsend }; #endif ================================================ FILE: WifiInterface.cpp ================================================ /* * © 2022-2024 Paul M. Antoine * © 2021 Fred Decker * © 2020-2022 Harald Barth * © 2020-2022 Chris Harlow * © 2023 Nathan Kellenicki * 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 . */ #ifndef ARDUINO_AVR_UNO_WIFI_REV2 // This code is NOT compiled on a unoWifiRev2 processor which uses a different architecture #include "WifiInterface.h" /* config.h included there */ //#include #include "DIAG.h" #include "StringFormatter.h" #include "WifiInboundHandler.h" const unsigned long LOOP_TIMEOUT = 2000; bool WifiInterface::connected = false; Stream * WifiInterface::wifiStream; #ifndef WIFI_CONNECT_TIMEOUT // Tested how long it takes to FAIL an unknown SSID on firmware 1.7.4. // The ES should fail a connect in 15 seconds, we don't want to fail BEFORE that // or ot will cause issues with the following commands. #define WIFI_CONNECT_TIMEOUT 16000 #endif //////////////////////////////////////////////////////////////////////////////// // // Figure out number of serial ports depending on hardware // #if defined(ARDUINO_AVR_UNO) || defined(ARDUINO_AVR_NANO) #define NUM_SERIAL 0 #endif #if (defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)) #define NUM_SERIAL 3 #define SERIAL1 Serial1 #define SERIAL3 Serial3 #endif #if defined(ARDUINO_ARCH_STM32) // Handle serial ports availability on STM32 for variants! // #undef NUM_SERIAL #if defined(ARDUINO_NUCLEO_F401RE) || defined(ARDUINO_NUCLEO_F411RE) #define NUM_SERIAL 3 #define SERIAL1 Serial1 #define SERIAL3 Serial6 #elif defined(ARDUINO_NUCLEO_F446RE) #define NUM_SERIAL 3 #define SERIAL1 Serial3 #define SERIAL3 Serial5 #elif defined(ARDUINO_NUCLEO_F413ZH) || defined(ARDUINO_NUCLEO_F429ZI) \ || defined(ARDUINO_NUCLEO_F446ZE) || defined(ARDUINO_NUCLEO_F412ZG) \ || defined(ARDUINO_NUCLEO_F439ZI) || defined(ARDUINO_NUCLEO_F4X9ZI) #define NUM_SERIAL 3 #define SERIAL1 Serial6 #define SERIAL3 Serial2 #else #warning This variant of Nucleo not yet explicitly supported #endif #endif #ifndef NUM_SERIAL #define NUM_SERIAL 1 #define SERIAL1 Serial1 #endif bool WifiInterface::setup(long serial_link_speed, const FSH *wifiESSID, const FSH *wifiPassword, const FSH *hostname, const int port, const byte channel, const bool forceAP) { wifiSerialState wifiUp = WIFI_NOAT; #if NUM_SERIAL == 0 // no warning about unused parameters. (void) serial_link_speed; (void) wifiESSID; (void) wifiPassword; (void) hostname; (void) port; (void) channel; (void) forceAP; #endif // See if the WiFi is attached to the first serial port #if NUM_SERIAL > 0 && !defined(SERIAL1_COMMANDS) SERIAL1.begin(serial_link_speed); wifiUp = setup(SERIAL1, wifiESSID, wifiPassword, hostname, port, channel, forceAP); #endif // Other serials are tried, depending on hardware. // Currently only the Arduino Mega 2560 has usable Serial2 (Nucleo-64 boards use Serial 2 for console!) #if defined(ARDUINO_AVR_MEGA2560) #if NUM_SERIAL > 1 && !defined(SERIAL2_COMMANDS) if (wifiUp == WIFI_NOAT) { Serial2.begin(serial_link_speed); wifiUp = setup(Serial2, wifiESSID, wifiPassword, hostname, port, channel, forceAP); } #endif #endif // We guess here that in all architctures that have a Serial3 // we can use it for our purpose. #if NUM_SERIAL > 2 && !defined(SERIAL3_COMMANDS) if (wifiUp == WIFI_NOAT) { SERIAL3.begin(serial_link_speed); wifiUp = setup(SERIAL3, wifiESSID, wifiPassword, hostname, port, channel, forceAP); } #endif if (wifiUp == WIFI_NOAT) // here and still not AT commands found return false; DCCEXParser::setAtCommandCallback(ATCommand); // CAUTION... ONLY CALL THIS ONCE WifiInboundHandler::setup(wifiStream); if (wifiUp == WIFI_CONNECTED) connected = true; else connected = false; return connected; } wifiSerialState WifiInterface::setup(Stream & setupStream, const FSH* SSid, const FSH* password, const FSH* hostname, int port, byte channel, bool forceAP) { wifiSerialState wifiState; static uint8_t ntry = 0; ntry++; wifiStream = &setupStream; DIAG(F("++ Wifi Setup Try %d ++"), ntry); wifiState = setup2( SSid, password, hostname, port, channel, forceAP); if (wifiState == WIFI_NOAT) { LCD(4, F("WiFi no AT chip")); return wifiState; } if (wifiState == WIFI_CONNECTED) { StringFormatter::send(wifiStream, F("ATE0\r\n")); // turn off the echo checkForOK(200, true); DIAG(F("WiFi CONNECTED")); // LCD already shows IP } else { LCD(4,F("WiFi DISCON.")); } return wifiState; } #ifdef DONT_TOUCH_WIFI_CONF #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wunused-variable" #pragma GCC diagnostic ignored "-Wunused-parameter" #endif wifiSerialState WifiInterface::setup2(const FSH* SSid, const FSH* password, const FSH* hostname, int port, byte channel, bool forceAP) { bool ipOK = false; bool oldCmd = false; bool apMode = false; char macAddress[17]; // mac address extraction // First check... Restarting the Arduino does not restart the ES. // There may alrerady be a connection with data in the pipeline. // If there is, just shortcut the setup and continue to read the data as normal. if (checkForOK(200,F("+IPD"), true)) { DIAG(F("Preconfigured Wifi already running with data waiting")); return WIFI_CONNECTED; } StringFormatter::send(wifiStream, F("AT\r\n")); // Is something here that understands AT? if(!checkForOK(200, true)) return WIFI_NOAT; // No AT compatible WiFi module here StringFormatter::send(wifiStream, F("ATE1\r\n")); // Turn on the echo, se we can see what's happening checkForOK(2000, true); // Makes this visible on the console // Display the AT version information StringFormatter::send(wifiStream, F("AT+GMR\r\n")); if (checkForOK(2000, F("AT version:"), true, false)) { char version[] = "0.0.0.0-xxx"; for (int i=0; i<11;i++) { while(!wifiStream->available()); version[i]=wifiStream->read(); StringFormatter::printEscape(version[i]); } if ((version[0] == '0') || (version[0] == '2' && version[2] == '0') || (version[0] == '2' && version[2] == '2' && version[4] == '0' && version[6] == '0' && version[7] == '-' && version[8] == 'd' && version[9] == 'e' && version[10] == 'v')) { DIAG(F("You need to up/downgrade the ESP firmware")); SSid = F("UPDATE_ESP_FIRMWARE"); forceAP = true; } } checkForOK(2000, true, false); #ifdef DONT_TOUCH_WIFI_CONF DIAG(F("DONT_TOUCH_WIFI_CONF was set: Using existing config")); #else // Older ES versions have AT+CWJAP, newer ones have AT+CWJAP_CUR and AT+CWHOSTNAME StringFormatter::send(wifiStream, F("AT+CWJAP_CUR?\r\n")); if (!(checkForOK(2000, true))) { oldCmd=true; while (wifiStream->available()) StringFormatter::printEscape( wifiStream->read()); /// THIS IS A DIAG IN DISGUISE } StringFormatter::send(wifiStream, F("AT+CWMODE%s=1\r\n"), oldCmd ? "" : "_CUR"); // configure as "station" = WiFi client checkForOK(1000, true); // Not always OK, sometimes "no change" #ifdef DHCPTEST // sometimes the esp8266 will get stuck with DHCP off, so reset DHCP to on // mode=1 which means DHCP for STA mode StringFormatter::send(wifiStream, F("AT+CWDHCP%s=1,1\r\n"), oldCmd ? "" : "_CUR"); checkForOK(5000, true); #else StringFormatter::send(wifiStream, F("AT+CWDHCP%s?\r\n"), oldCmd ? "" : "_CUR"); if (checkForOK(5000, F("+CWDHCP"), true,false)) { if (!checkForOK(5000, F("3"), true,false)) DIAG(F("Warning: DHCP may be off")); } else { DIAG(F("Warning: Can not determine DHCP state")); } checkForOK(1000, true); // consume the OK #endif const char *yourNetwork = "Your network "; if (STRNCMP_P(yourNetwork, (const char*)SSid, 13) == 0 || STRNCMP_P("", (const char*)SSid, 13) == 0) { if (STRNCMP_P(yourNetwork, (const char*)password, 13) == 0) { // If the source code looks unconfigured, check if the // ESP8266 is preconfigured in station mode. // We check the first 13 chars of the SSid and the password // give a preconfigured ES8266 a chance to connect to a router // typical connect time approx 7 seconds delay(8000); StringFormatter::send(wifiStream, F("AT+CIFSR\r\n")); if (checkForOK(5000, F("+CIFSR:STAIP"), true,false)) if (!checkForOK(1000, F("0.0.0.0"), true,false)) ipOK = true; } } else if (!forceAP) { // SSID was configured, so we assume station (client) mode. if (oldCmd) { // AT command early version supports CWJAP/CWSAP StringFormatter::send(wifiStream, F("AT+CWJAP=\"%S\",\"%S\"\r\n"), SSid, password); ipOK = checkForOK(WIFI_CONNECT_TIMEOUT, true); } else { // later version supports CWJAP_CUR StringFormatter::send(wifiStream, F("AT+CWHOSTNAME=\"%S\"\r\n"), hostname); // Set Host name for Wifi Client checkForOK(5001, true); // dont care if not supported StringFormatter::send(wifiStream, F("AT+CWJAP_CUR=\"%S\",\"%S\"\r\n"), SSid, password); ipOK = checkForOK(WIFI_CONNECT_TIMEOUT, true); } if (ipOK) { // But we really only have the ESSID and password correct // Let's check for IP (via DHCP) ipOK = false; StringFormatter::send(wifiStream, F("AT+CIFSR\r\n")); if (checkForOK(5004, F("+CIFSR:STAIP"), true,false)) if (!checkForOK(1000, F("0.0.0.0"), true,false)) ipOK = true; } } if (!ipOK) { // If we have not managed to get this going in station mode, go for AP mode // StringFormatter::send(wifiStream, F("AT+RST\r\n")); // checkForOK(1000, true); // Not always OK, sometimes "no change" int i=0; do { // configure as AccessPoint. Try really hard as this is the // last way out to get any Wifi connectivity. StringFormatter::send(wifiStream, F("AT+CWMODE%s=2\r\n"), oldCmd ? "" : "_CUR"); } while (!checkForOK(1000+i*500, true) && i++<10); apMode = true; while (wifiStream->available()) StringFormatter::printEscape( wifiStream->read()); /// THIS IS A DIAG IN DISGUISE #ifdef DHCPTEST // sometimes the esp8266 will get stuck with DHCP off, so reset DHCP to on // mode=0 which means DHCP for softAP StringFormatter::send(wifiStream, F("AT+CWDHCP%s=0,1\r\n"), oldCmd ? "" : "_CUR"); checkForOK(5000, true); #endif // Figure out MAC addr StringFormatter::send(wifiStream, F("AT+CIFSR\r\n")); // not TOMATO // looking fpr mac addr eg +CIFSR:APMAC,"be:dd:c2:5c:6b:b7" if (checkForOK(5000, F("+CIFSR:APMAC,\""), true,false)) { // Copy 17 byte mac address for (int i=0; i<17;i++) { while(!wifiStream->available()); macAddress[i]=wifiStream->read(); if (macAddress[i] < '0' || macAddress[i] > 'f' || (macAddress[i] > ':' && macAddress[i] < 'a')) { // this does not look like a MAC addr format, try to save the day // with some printable character macAddress[i] = 'x'; } StringFormatter::printEscape(macAddress[i]); } } else { memset(macAddress,'f',sizeof(macAddress)); } char macTail[]={macAddress[9],macAddress[10],macAddress[12],macAddress[13],macAddress[15],macAddress[16],'\0'}; checkForOK(1000, true, false); // suck up remainder of AT+CIFSR i=0; #ifdef WIFI_HIDE_SSID const byte hiddenAP = true; #else const bool hiddenAP = false; #endif do { if (!forceAP) { if (STRNCMP_P(yourNetwork, (const char*)password, 13) == 0) { // unconfigured StringFormatter::send(wifiStream, F("AT+CWSAP%s=\"DCCEX_%s\",\"PASS_%s\",%d,4,4,%b\r\n"), oldCmd ? "" : "_CUR", macTail, macTail, channel,hiddenAP); } else { // password configured by user StringFormatter::send(wifiStream, F("AT+CWSAP%s=\"DCCEX_%s\",\"%S\",%d,4,4,%b\r\n"), oldCmd ? "" : "_CUR", macTail, password, channel,hiddenAP); } } else { StringFormatter::send(wifiStream, F("AT+CWSAP%s=\"%S\",\"%S\",%d,4,4,%b\r\n"), oldCmd ? "" : "_CUR", SSid, password, channel,hiddenAP); } } while (!checkForOK(WIFI_CONNECT_TIMEOUT, true) && i++<2); // do twice if necessary but ignore failure as AP mode may still be ok if (i >= 2) DIAG(F("Warning: Setting AP SSID and password failed")); // but issue warning if (!oldCmd) { StringFormatter::send(wifiStream, F("AT+CIPRECVMODE=0\r\n"), port); // make sure transfer mode is correct checkForOK(2000, true); } } #endif //DONT_TOUCH_WIFI_CONF StringFormatter::send(wifiStream, F("AT+CIPSERVER=0\r\n")); // turn off tcp server (to clean connections before CIPMUX=1) checkForOK(1000, true); // ignore result in case it already was off StringFormatter::send(wifiStream, F("AT+CIPMUX=1\r\n")); // configure for multiple connections if (!checkForOK(1000, true)) return WIFI_DISCONNECTED; if(!oldCmd && !apMode) { // no idea to test this on old firmware and it works only in STA mode anyway StringFormatter::send(wifiStream, F("AT+MDNS=1,\"%S\",\"withrottle\",%d\r\n"), hostname, port); // mDNS responder checkForOK(1000, true); // dont care if not supported } StringFormatter::send(wifiStream, F("AT+CIPSERVER=1,%d\r\n"), port); // turn on server on port if (!checkForOK(1000, true)) return WIFI_DISCONNECTED; StringFormatter::send(wifiStream, F("AT+CIFSR\r\n")); // Display ip addresses to the DIAG if (!checkForOK(1000, F("IP,\"") , true, false)) return WIFI_DISCONNECTED; // Copy the IP address { const byte MAX_IP_LENGTH=15; char ipString[MAX_IP_LENGTH+1]; ipString[MAX_IP_LENGTH]='\0'; // protection against missing " character on end. for(byte ipLen=0;ipLenavailable()); int ipChar=wifiStream->read(); StringFormatter::printEscape(ipChar); if (ipChar=='"') { ipString[ipLen]='\0'; break; } ipString[ipLen]=ipChar; } LCD(4,F("%s"),ipString); // There is not enough room on some LCDs to put a title to this } // suck up anything after the IP. if (!checkForOK(1000, true, false)) return WIFI_DISCONNECTED; LCD(5,F("PORT=%d"),port); return WIFI_CONNECTED; } #ifdef DONT_TOUCH_WIFI_CONF #pragma GCC diagnostic pop #endif // This function is used to allow users to enter <+ commands> through the DCCEXParser // <+command> sends AT+command to the ES and returns to the caller. // Once the user has made whatever changes to the AT commands, a <+X> command can be used // to force on the connectd flag so that the loop will start picking up wifi traffic. // If the settings are corrupted <+RST> will clear this and then you must restart the arduino. // Using the <+> command with no command string causes the code to enter an echo loop so that all // input is directed to the ES and all ES output written to the USB Serial. // The sequence "!!!" returns the Arduino to the normal loop mode void WifiInterface::ATCommand(HardwareSerial * stream,const byte * command) { command++; if (*command=='\0') { // User gave <+> command stream->print(F("\nES AT command passthrough mode, use ! to exit\n")); while(stream->available()) stream->read(); // Drain serial input first bool startOfLine=true; while(true) { while (wifiStream->available()) stream->write(wifiStream->read()); if (stream->available()) { int cx=stream->read(); // A newline followed by ! is an exit if (cx=='\n' || cx=='\r') startOfLine=true; else if (startOfLine && cx=='!') break; else startOfLine=false; wifiStream->write(cx); } } stream->print(F("Passthrough Ended")); return; } if (*command=='X') { connected = true; DIAG(F("++++++ Wifi Connction forced on ++++++++")); } else { StringFormatter:: send(wifiStream, F("AT+%s\r\n"), command); checkForOK(10000, true); } } bool WifiInterface::checkForOK( const unsigned int timeout, bool echo, bool escapeEcho) { return checkForOK(timeout,F("\r\nOK\r\n"),echo,escapeEcho); } bool WifiInterface::checkForOK( const unsigned int timeout, const FSH * waitfor, bool echo, bool escapeEcho) { unsigned long startTime = millis(); char *locator = (char *)waitfor; DIAG(F("Wifi Check: [%E]"), waitfor); while ( millis() - startTime < timeout) { int nextchar; while (wifiStream->available() && (nextchar = wifiStream->read()) > -1) { char ch = (char)nextchar; if (echo) { if (escapeEcho) StringFormatter::printEscape( ch); /// THIS IS A DIAG IN DISGUISE else USB_SERIAL.print(ch); } if (ch != GETFLASH(locator)) locator = (char *)waitfor; if (ch == GETFLASH(locator)) { locator++; if (!GETFLASH(locator)) { DIAG(F("Found in %dms of %d"), (int)(millis() - startTime), timeout); return true; } } } } DIAG(F("TIMEOUT after %dms"), timeout); return false; } void WifiInterface::loop() { if (connected) { WifiInboundHandler::loop(); } } #endif ================================================ FILE: WifiInterface.h ================================================ /* * © 2020-2021 Chris Harlow * © 2020, Harald Barth. * © 2023 Nathan Kellenicki * 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 . */ #ifndef WifiInterface_h #define WifiInterface_h #include "FSH.h" #include "DCCEXParser.h" #include //#include enum wifiSerialState { WIFI_NOAT, WIFI_DISCONNECTED, WIFI_CONNECTED }; class WifiInterface { public: static bool setup(long serial_link_speed, const FSH *wifiESSID, const FSH *wifiPassword, const FSH *hostname, const int port, const byte channel, const bool forceAP); static void loop(); static void ATCommand(HardwareSerial * stream,const byte *command); private: static wifiSerialState setup(Stream &setupStream, const FSH *SSSid, const FSH *password, const FSH *hostname, int port, byte channel, bool forceAP); static Stream *wifiStream; static DCCEXParser parser; static wifiSerialState setup2(const FSH *SSSid, const FSH *password, const FSH *hostname, int port, byte channel, bool forceAP); static bool checkForOK(const unsigned int timeout, bool echo, bool escapeEcho = true); static bool checkForOK(const unsigned int timeout, const FSH *waitfor, bool echo, bool escapeEcho = true); static bool connected; }; #endif ================================================ FILE: Ztest.cpp ================================================ #include #include "DIAG.h" #include "Ztest.h" #include "DCCEXParser.h" #include "StringFormatter.h" RingStream * Ztest::ring = new RingStream(128); void Ztest::parse(const FSH * command, const FSH * expect, bool (*test)() ) { DIAG(F("ZTEST %S"), command); // create copy of command in RAM auto commandLength= STRLEN_P((char *)command) + 1; char commandBuffer[commandLength+1]; STRNCPY_P(commandBuffer, (PGM_P)command,commandLength+1); if (expect) { // create response buffer to collect comparison ring->flush(); ring->mark(0); // mark the start of the response DCCEXParser::parseOne(ring, (byte *)commandBuffer, ring); ring->commit(); } else { // run command (but not if its just a title) without output test if (commandBuffer[0]=='<') DCCEXParser::parseOne(& USB_SERIAL, (byte *)commandBuffer,nullptr); } // test the assert of side effects if (test) { auto result=test(); DIAG(F("ZTEST assert %S"), result ? F("OK") : F("FAILED")); } if (expect) { // Copy output to serial and check with expected ring->read(); // read redundant client id auto responseLength=ring->count(); if (responseLength < 1) { DIAG(F("!!....(no resp) ZTEST")); return; // no response } // show output while comparing char output[responseLength+1]; for (int16_t i=0;iread(); output[responseLength]=0; DIAG(F("ZTEST response:%s"), output); DIAG(F("ZTEST expect :%S"), (char *)expect); if (STRCMP_P(output, (char *)expect) != 0) DIAG(F("ZTEST expect failed\n")); } } ================================================ FILE: Ztest.h ================================================ #ifndef ztest_h #define ztest_h #include "RingStream.h" class Ztest { public: static void parse(const FSH * command, const FSH * expect, bool (*test)() ); private: static RingStream * ring; }; #endif ================================================ FILE: config.example.h ================================================ /* * © 2022 Paul M. Antoine * © 2021 Neil McKechnie * © 2020-2025 Harald Barth * © 2020-2021 Fred Decker * © 2020-2025 Chris Harlow * © 2023 Nathan Kellenicki * * 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 . */ /********************************************************************** The configuration file for DCC-EX Command Station **********************************************************************/ ///////////////////////////////////////////////////////////////////////////////////// // If you want to add your own motor driver definition(s), add them here // For example MY_SHIELD with display name "MINE": // (remove comment start and end marker if you want to edit and use that) /* #define MY_SHIELD F("MINE"), \ new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 5.08, 3000, A4), \ new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 5.08, 1500, A5) */ ///////////////////////////////////////////////////////////////////////////////////// // NOTE: Before connecting these boards and selecting one in this software // check the quick install guides!!! Some of these boards require a voltage // generating resistor on the current sense pin of the device. Failure to select // the correct resistor could damage the sense pin on your Arduino or destroy // the device. // // DEFINE MOTOR_SHIELD_TYPE BELOW. THESE ARE EXAMPLES. Full list in MotorDrivers.h // // STANDARD_MOTOR_SHIELD : Arduino Motor shield Rev3 based on the L298 with 18V 2A per channel // POLOLU_MOTOR_SHIELD : Pololu MC33926 Motor Driver (not recommended for prog track) // EX8874_SHIELD : DCC-EX TI DRV8874 based motor shield // EXCSB1 : DCC-EX CSB-1 hardware // EXCSB1_WITH_EX8874 : DCC-EX CSB-1 hardware with DCC-EX TI DRV8874 shield // NO_SHIELD : CS without any motor shield (as an accessory only CS) // | // +-----------------------v // #define MOTOR_SHIELD_TYPE STANDARD_MOTOR_SHIELD // ///////////////////////////////////////////////////////////////////////////////////// // // If you want to restrict the maximum current LOWER than what your // motor shield can provide, you can do that here. For example if you // have a motor shield that can provide 5A and your power supply can // only provide 2.5A then you should restict the maximum current to // 2.25A (90% of 2.5A) so that DCC-EX does shut off the track before // your PS does shut DCC-EX. MAX_CURRENT is in mA so for this example // it would be 2250, adjust the number according to your PS. If your // PS has a higher rating than your motor shield you do not need this. // You can use this as well if you are cautious and your trains do not // need full current. // #define MAX_CURRENT 2250 // ///////////////////////////////////////////////////////////////////////////////////// // // The IP port to talk to a WIFI or Ethernet shield. // #define IP_PORT 2560 ///////////////////////////////////////////////////////////////////////////////////// // // NOTE: Not supported on Arduino Uno or Nano // Set to false if you not even want it on the Arduino Mega // #define ENABLE_WIFI true ///////////////////////////////////////////////////////////////////////////////////// // // DEFINE WiFi Parameters (only in effect if WIFI is on) // // If DONT_TOUCH_WIFI_CONF is set, all WIFI config will be done with // the <+> commands and this sketch will not change anything over // AT commands and the other WIFI_* defines below do not have any effect. //#define DONT_TOUCH_WIFI_CONF // // WIFI_SSID is the network name IF you want to use your existing home network. // Do NOT change this if you want to use the WiFi in Access Point (AP) mode. // // If you do NOT set the WIFI_SSID and do NOT set the WIFI_PASSWORD, // then the WiFi chip will first try to connect to the previously // configured network and if that fails fall back to Access Point mode. // The SSID of the AP will be automatically set to DCCEX_*. // If you DO set the WIFI_SSID then the WiFi chip will try to connect // to that (home) network in station (client) mode. If a WIFI_PASSWORD // is set (recommended), that password will be used for AP mode. // The AP mode password must be at least 8 characters long. // // Your SSID may not contain ``"'' (double quote, ASCII 0x22). #define WIFI_SSID "Your network name" // // WIFI_PASSWORD is the network password for your home network or if // you want to change the password from default AP mode password // to the AP password you want. // Your password may not contain ``"'' (double quote, ASCII 0x22). #define WIFI_PASSWORD "Your network passwd" // // WIFI_HOSTNAME: You can change this if you have more than one // CS to make them show up with different names on the network. // Otherwise do not touch. #define WIFI_HOSTNAME "dccex" // // WIFI_CHANNEL: The default channel is set to "1". If you need to use an // alternate channel (we recommend using only 1,6, or 11) you may change it here. #define WIFI_CHANNEL 1 // // WIFI_FORCE_AP: If you'd like to specify your own WIFI_SSID in AP mode, set this // true. Otherwise it is assumed that you'd like to connect to an existing network // with that SSID. #define WIFI_FORCE_AP false ///////////////////////////////////////////////////////////////////////////////////// // // ENABLE_ETHERNET: Set to true if you have an Arduino Ethernet card (wired) based // on the W5100/W5500 ethernet chip or an STM32 CS with builin ethernet like the F429ZI. // This is not for Wifi. You will then need the Arduino Ethernet library as well. // //#define ENABLE_ETHERNET true ///////////////////////////////////////////////////////////////////////////////////// // // MAX_NUM_TCP_CLIENTS: If you on STM32 Ethernet (and only there) want more than // 9 (*) TCP clients, change this number to for example 20 here **AND** in // STM32lwiopts.h and follow the instructions in STM32lwiopts.h // // (*) It would be 10 if there would not be a bug in LwIP by STM32duino. // //#define MAX_NUM_TCP_CLIENTS 20 ///////////////////////////////////////////////////////////////////////////////////// // // DEFINE STATIC IP ADDRESS *OR* COMMENT OUT TO USE DHCP // //#define IP_ADDRESS { 192, 168, 1, 200 } ///////////////////////////////////////////////////////////////////////////////////// // // DEFINE LCD SCREEN USAGE BY THE BASE STATION // // Note: This feature requires an I2C enabled LCD screen using a Hitachi HD44780 // controller and a commonly available PCF8574 based I2C 'backpack'. // To enable, uncomment one of the #define lines below // define LCD_DRIVER for I2C address 0x27, 16 cols, 2 rows // #define LCD_DRIVER 0x27,16,2 //OR define OLED_DRIVER width,height[,address] in pixels (address auto detected if not supplied) // 128x32 or 128x64 I2C SSD1306-based devices are supported. // Use 132,64 for a SH1106-based I2C device with a 128x64 display. // #define OLED_DRIVER 0x3c,128,32 // Define scroll mode as 0, 1 or 2 // * #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). #define SCROLLMODE 1 // In order to avoid wasting memory the current scroll buffer is limited // to 8 lines. Some users wishing to display additional information // such as TrackManager power states have requested additional rows aware // of the warning that this will take extra RAM. if you wish to include additional rows // uncomment the following #define and set the number of lines you need. //#define MAX_CHARACTER_ROWS 12 ///////////////////////////////////////////////////////////////////////////////////// // DISABLE EEPROM // // If you do not need the EEPROM at all, you can disable all the code that saves // data in the EEPROM. You might want to do that if you are in a Arduino UNO // and want to use the EXRAIL automation. Otherwise you do not have enough RAM // to do that. Of course, then none of the EEPROM related commands work. // // EEPROM does not work on ESP32. So on ESP32, EEPROM will always be disabled, // at least until it works. // // #define DISABLE_EEPROM ///////////////////////////////////////////////////////////////////////////////////// // DISABLE PROG // // If you do not need programming capability, you can disable all programming related // commands. You might want to do that if you are using an Arduino UNO and still want // to use EXRAIL automation, as the Uno is lacking in RAM and Flash to run both. // // Note this disables all programming functionality, including EXRAIL. // // #define DISABLE_PROG ///////////////////////////////////////////////////////////////////////////////////// // DISABLE / ENABLE VDPY // // The Virtual display "VDPY" feature is by default enabled everywhere // but on Uno and Nano. If you think you can fit it (for example // having disabled some of the features above) you can enable it with // ENABLE_VDPY. You can even disable it on all other CPUs with // DISABLE_VDPY // // #define DISABLE_VDPY // #define ENABLE_VDPY ///////////////////////////////////////////////////////////////////////////////////// // DISABLE / ENABLE DIAG // // To diagose different errors, you can turn on differnet messages. This costs // program memory which we do not have enough on the Uno and Nano, so it is // by default DISABLED on those. If you think you can fit it (for example // having disabled some of the features above) you can enable it with // ENABLE_DIAG. You can even disable it on all other CPUs with // DISABLE_DIAG // // #define DISABLE_DIAG // #define ENABLE_DIAG ///////////////////////////////////////////////////////////////////////////////////// // REDEFINE WHERE SHORT/LONG ADDR break is. According to NMRA the last short address // is 127 and the first long address is 128. There are manufacturers which have // another view. Lenz CS for example have considered addresses long from 100. If // you want to change to that mode, do //#define HIGHEST_SHORT_ADDR 99 // If you want to run all your locos addressed long format, you could even do a //#define HIGHEST_SHORT_ADDR 0 // We do not support to use the same address, for example 100(long) and 100(short) // at the same time, there must be a border. ///////////////////////////////////////////////////////////////////////////////////// // REDEFINE locomotive state table size. // This is the maximum number of locos that can be controlled at the same time. // This defaults to 50 (8 on a UNO/NANO). // If you have enough free memory you can increase this to a maximum of 255. // If you are short of memory (typically a Mega with WiFi and lots of accessories) // you can decrease it (minimum 2) //#define MAX_LOCOS 100 ///////////////////////////////////////////////////////////////////////////////////// // Some newer 32bit microcontrollers boot very quickly, so powering on I2C and other // peripheral devices at the same time may result in the CommandStation booting too // quickly to detect them. // To work around this, uncomment the STARTUP_DELAY line below and set a value in // milliseconds that works for your environment, default is 3000 (3 seconds). // #define STARTUP_DELAY 3000 ///////////////////////////////////////////////////////////////////////////////////// // // DEFINE TURNOUTS/ACCESSORIES FOLLOW NORM RCN-213 // // According to norm RCN-213 a DCC packet with a 1 is closed/straight // and one with a 0 is thrown/diverging. In DCC++ Classic, and in previous // versions of DCC++EX, a turnout throw command was implemented in the packet as // '1' and a close command as '0'. The #define below makes the states // match with the norm. But we don't want to cause havoc on existent layouts, // so we define this only for new installations. If you don't want this, // don't add it to your config.h. //#define DCC_TURNOUTS_RCN_213 // By default, the driver which defines a DCC accessory decoder // does send out the same state change on the DCC packet as it // receives. This means a VPIN state=1 sends D=1 (close turnout // or signal green) in the DCC packet. This can be reversed if // necessary. //#define HAL_ACCESSORY_COMMAND_REVERSE // If you have issues with that the direction of the accessory commands is // reversed (for example when converting from another CS to DCC-EX) then // you can use this to reverse the sense of all accessory commmands sent // over DCC++. This #define likewise inverts the behaviour of the command // for triggering DCC Accessory Decoders, so that generates a // DCC packet with D=1 (close turnout) and generates D=0 // (throw turnout). //#define DCC_ACCESSORY_COMMAND_REVERSE // HANDLING MULTIPLE SERIAL THROTTLES // The command station always operates with the default Serial port. // Diagnostics are only emitted on the default serial port and not broadcast. // Other serial throttles may be added to the Serial1, Serial2, Serial3, Serial4, // Serial5, and Serial6 ports which may or may not exist on your CPU. (Mega has 3, // SAMD/SAMC and STM32 have up to 6.) // To monitor a throttle on one or more serial ports, uncomment the defines below. // NOTE: do not define here the WiFi shield serial port or your wifi will not work. // //#define SERIAL1_COMMANDS //#define SERIAL2_COMMANDS //#define SERIAL3_COMMANDS //#define SERIAL4_COMMANDS //#define SERIAL5_COMMANDS //#define SERIAL6_COMMANDS // // BLUETOOTH SERIAL ON ESP32 // On ESP32 you have the possibility to use the builtin BT serial to connect to // the CS. // // The CS shows up as a pairable BT Clasic device. Name is "DCCEX-hexnumber". // BT is as an additional serial port, debug messages are still sent over USB, // not BT serial. // // If you enable this there are some implications: // 1. WiFi will sleep more (as WiFi and BT share the radio. So WiFi performance // may suffer // 2. The app will be bigger that 1.2MB, so the default partition scheme will not // work any more. You need to choose a partition scheme with 2MB (or bigger). // For example "NO OTA (2MB APP, 2MB SPIFFS)" in the Arduino IDE. // 3. There is no securuity (PIN) implemented. Everyone in radio range can pair // with your CS. // //#define SERIAL_BT_COMMANDS // BOOSTER PIN INPUT ON ESP32 CS // On ESP32 you have the possibility to define a pin as booster input // // Arduino pin D2 is GPIO 26 is Booster Input on ESPDuino32 //#define BOOSTER_INPUT 26 // // GPIO 32 is Booster Input on EX-CSB1 //#define BOOSTER_INPUT 32 // ESP32 LED Wifi Indicator // GPIO 2 on ESPduino32 //#define WIFI_LED 2 // // GPIO 33 on EX-CSB1 //#define WIFI_LED 33 // SABERTOOTH // // This is a very special option and only useful if you happen to have a // sabertooth motor controller from dimension engineering configured to // take commands from and ESP32 via serial at 9600 baud from GPIO17 (TX) // and GPIO16 (RX, currently unused). // The number defined is the DCC address for which speed controls are sent // to the sabertooth controller _as_well_. Default: Undefined. // //#define SABERTOOTH 1 ///////////////////////////////////////////////////////////////////////////////////// // // SENSORCAM // ESP32-CAM based video sensors require #define to use appropriate base vpin number. //#define SENSORCAM_VPIN 700 // To bypass vPin number, define CAM for ex-rail use e.g. AT(CAM 012) for S12 etc. //#define CAM SENSORCAM_VPIN+ // //#define SENSORCAM2_VPIN 600 //define other CAM's if installed. //#define CAM2 SENSORCAM2_VPIN+ //for EX-RAIL commands e.g. IFLT(CAM2 020,1) // // For smoother power-up, when using the CAM, you may need a STARTUP_DELAY. // That is described further above. // ///////////////////////////////////////////////////////////////////////////////////// ================================================ FILE: defines.h ================================================ /* * © 2022 Paul M Antoine * © 2021 Neil McKechnie * © 2021 Mike S * © 2021 Fred Decker * © 2020-2022 Harald Barth * © 2020-2025 Chris Harlow * * 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 . * */ #ifndef DEFINES_H #define DEFINES_H // defines.h relies on macros defined in config.h // but it may have already been included (for cosmetic convenience) by the .ino #if __has_include ( "config.h") #include "config.h" #endif #ifndef MOTOR_SHIELD_TYPE #define MOTOR_SHIELD_TYPE NO_SHIELD #endif //////////////////////////////////////////////////////////////////////////////// // Create a cpu type we can share and // figure out if we have enough memory for advanced features // so define HAS_ENOUGH_MEMORY until proved otherwise. #define HAS_ENOUGH_MEMORY #undef USB_SERIAL // Teensy has this defined by default... #define USB_SERIAL Serial #define USB_SERIAL_WEB // Include extended addresses unless specifically excluded #define I2C_EXTENDED_ADDRESS #if defined(ARDUINO_AVR_UNO) #define ARDUINO_TYPE "UNO" #undef HAS_ENOUGH_MEMORY #define NO_EXTENDED_CHARACTERS #undef I2C_EXTENDED_ADDRESS #define DEFAULT_MAX_LOCOS 8 #elif defined(ARDUINO_AVR_NANO) #define ARDUINO_TYPE "NANO" #undef HAS_ENOUGH_MEMORY #define NO_EXTENDED_CHARACTERS #undef I2C_EXTENDED_ADDRESS #define DEFAULT_MAX_LOCOS 8 #elif defined(ARDUINO_AVR_MEGA) #define ARDUINO_TYPE "MEGA" #define DEFAULT_MAX_LOCOS 50 #elif defined(ARDUINO_AVR_MEGA2560) #define ARDUINO_TYPE "MEGA" #define DEFAULT_MAX_LOCOS 50 #elif defined(ARDUINO_ARCH_MEGAAVR) #define ARDUINO_TYPE "MEGAAVR" #undef HAS_ENOUGH_MEMORY #define NO_EXTENDED_CHARACTERS #undef I2C_EXTENDED_ADDRESS #define DEFAULT_MAX_LOCOS 8 #elif defined(ARDUINO_TEENSY31) #define ARDUINO_TYPE "TEENSY3132" #undef USB_SERIAL #define USB_SERIAL SerialUSB #ifndef DISABLE_EEPROM #define DISABLE_EEPROM #endif // Teensy support for native I2C is awaiting development #ifndef I2C_USE_WIRE #define I2C_USE_WIRE #endif #elif defined(ARDUINO_TEENSY35) #define ARDUINO_TYPE "TEENSY35" #undef USB_SERIAL #define USB_SERIAL SerialUSB // Teensy support for I2C is awaiting development #ifndef DISABLE_EEPROM #define DISABLE_EEPROM #endif // Teensy support for native I2C is awaiting development #ifndef I2C_USE_WIRE #define I2C_USE_WIRE #endif #elif defined(ARDUINO_TEENSY36) #define ARDUINO_TYPE "TEENSY36" #undef USB_SERIAL #define USB_SERIAL SerialUSB #ifndef DISABLE_EEPROM #define DISABLE_EEPROM #endif // Teensy support for native I2C is awaiting development #ifndef I2C_USE_WIRE #define I2C_USE_WIRE #endif #elif defined(ARDUINO_TEENSY40) #define ARDUINO_TYPE "TEENSY40" #undef USB_SERIAL #define USB_SERIAL SerialUSB #ifndef DISABLE_EEPROM #define DISABLE_EEPROM #endif // Teensy support for native I2C is awaiting development #ifndef I2C_USE_WIRE #define I2C_USE_WIRE #endif #elif defined(ARDUINO_TEENSY41) #define ARDUINO_TYPE "TEENSY41" #undef USB_SERIAL #define USB_SERIAL SerialUSB #ifndef DISABLE_EEPROM #define DISABLE_EEPROM #endif // Teensy support for native I2C is awaiting development #ifndef I2C_USE_WIRE #define I2C_USE_WIRE #endif #elif defined(ARDUINO_ARCH_ESP8266) #define ARDUINO_TYPE "ESP8266" #warning "ESP8266 platform untested, you are on your own" #elif defined(ARDUINO_ARCH_ESP32) #define ARDUINO_TYPE "ESP32" #ifndef DISABLE_EEPROM #define DISABLE_EEPROM #endif #if ENABLE_WIFI #define ENABLE_SERIAL_LOG #endif #elif defined(ARDUINO_ARCH_SAMD) #define ARDUINO_TYPE "SAMD21" #undef USB_SERIAL #define USB_SERIAL SerialUSB // SAMD no EEPROM by default #ifndef DISABLE_EEPROM #define DISABLE_EEPROM #endif #elif defined(ARDUINO_ARCH_STM32) #define ARDUINO_TYPE "STM32" // STM32 no EEPROM by default #ifndef DISABLE_EEPROM #define DISABLE_EEPROM #endif #if ENABLE_ETHERNET // WAITING FOR STM32 ETHERNET SUPPORT FIX // #define ENABLE_SERIAL_LOG #endif // STM32 support for native I2C is awaiting development // #ifndef I2C_USE_WIRE // #define I2C_USE_WIRE // #endif /* TODO when ready #elif defined(ARDUINO_ARCH_RP2040) #define ARDUINO_TYPE "RP2040" */ #else #define CPU_TYPE_ERROR #endif // replace board type if provided by compiler #ifdef BOARD_NAME #undef ARDUINO_TYPE #define ARDUINO_TYPE BOARD_NAME #endif //////////////////////////////////////////////////////////////////////////////// // // WIFI_ON: All prereqs for running with WIFI are met // Note: WIFI_CHANNEL may not exist in early config.h files so is added here if needed. #if ENABLE_WIFI #if defined(HAS_ENOUGH_MEMORY) #define WIFI_ON true #ifndef WIFI_CHANNEL #define WIFI_CHANNEL 1 #endif #else #define WIFI_WARNING #define WIFI_ON false #endif #else #define WIFI_ON false #endif #ifndef WIFI_FORCE_AP #define WIFI_FORCE_AP false #else #if WIFI_FORCE_AP==true || WIFI_FORCE_AP==false #else #error WIFI_FORCE_AP needs to be true or false #endif #endif #if ENABLE_ETHERNET #if defined(HAS_ENOUGH_MEMORY) #define ETHERNET_ON true #else #define ETHERNET_WARNING #define ETHERNET_ON false #endif #else #define ETHERNET_ON false #endif #if WIFI_ON && ETHERNET_ON #error Command Station does not support WIFI and ETHERNET at the same time. #endif //////////////////////////////////////////////////////////////////////////////// // // This defines the speed at which the Arduino will communicate with the ESP8266 module. // Currently only devices which can communicate at 115200 are supported. // #define WIFI_SERIAL_LINK_SPEED 115200 // configure serial log browser feature if possible #ifdef ENABLE_SERIAL_LOG // Replace USB_SERIAL with SerialLog so we can browse it! #undef USB_SERIAL #include "SerialUsbLog.h" #define USB_SERIAL SerialLog #endif //////////////////////////////////////////////////////////////////////////////// // // Define symbol IO_NO_HAL to reduce FLASH footprint when HAL features not required // The HAL is disabled by default on Nano and Uno platforms, because of limited flash space. // #if defined(ARDUINO_AVR_NANO) || defined(ARDUINO_AVR_UNO) #define IO_NO_HAL // HAL too big whatever you disable otherwise #ifndef ENABLE_VDPY #define DISABLE_VDPY #endif #ifndef ENABLE_DIAG #define DISABLE_DIAG #endif #endif #if __has_include ( "myAutomation.h") #if defined(HAS_ENOUGH_MEMORY) || defined(DISABLE_EEPROM) || defined(DISABLE_PROG) #define EXRAIL_ACTIVE #else #define EXRAIL_WARNING #endif #endif #if defined(ARDUINO_ARCH_STM32) // The LwIP library for the STM32 wired ethernet has by default 10 TCP // clients defined but because of a bug in the library #11 is not // rejected but kicks out any old connection. By restricting our limit // to 9 the #10 will be rejected by our code so that the number can // never get to 11 which would kick an existing connection. // If you want to change this value, do that in // config.h AND in STM32lwipopts.h. #ifndef MAX_NUM_TCP_CLIENTS #define MAX_NUM_TCP_CLIENTS 9 #endif #else #if defined(ARDUINO_ARCH_ESP32) // Espressif LWIP stack #define MAX_NUM_TCP_CLIENTS 10 #else // Wifi shields etc #define MAX_NUM_TCP_CLIENTS 8 #endif #endif // Default MAX_LOCOS if not found in config.h #ifndef DEFAULT_MAX_LOCOS #define DEFAULT_MAX_LOCOS 120 #endif #ifndef MAX_LOCOS #define MAX_LOCOS DEFAULT_MAX_LOCOS #endif // Default IP_PORT if not found in config.h #ifndef IP_PORT #define IP_PORT 2560 #endif // Default WIFI_SSID if not found in config.h #ifndef WIFI_SSID #define WIFI_SSID "" #endif // Default WIFI_PASSWORD if not found in config.h #ifndef WIFI_PASSWORD #define WIFI_PASSWORD "Your network passwd" #endif // Default WIFI_HOSTNAME if not found in config.h #ifndef WIFI_HOSTNAME #define WIFI_HOSTNAME "DCC-EX" #endif // Default ETHERNET_HOSTNAME to WIFI_HOSTNAME if not found in config.h (for old EXinstaller compatibility) #ifndef ETHERNET_HOSTNAME #define ETHERNET_HOSTNAME WIFI_HOSTNAME #endif #endif //DEFINES_H ================================================ FILE: docs/DoxyfileEXRAIL ================================================ # Doxyfile 1.9.8 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. # # All text after a double hash (##) is considered a comment and is placed in # front of the TAG it is preceding. # # All text after a single hash (#) is considered a comment and will be ignored. # The format is: # TAG = value [value, ...] # For lists, items can also be appended using: # TAG += value [value, ...] # Values that contain spaces should be placed between quotes (\" \"). # # Note: # # Use doxygen to compare the used configuration file with the template # configuration file: # doxygen -x [configFile] # Use doxygen to compare the used configuration file with the template # configuration file without replacing the environment variables or CMake type # replacement variables: # doxygen -x_noenv [configFile] #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- # This tag specifies the encoding used for all characters in the configuration # file that follow. The default is UTF-8 which is also the encoding used for all # text before the first occurrence of this tag. Doxygen uses libiconv (or the # iconv built into libc) for the transcoding. See # https://www.gnu.org/software/libiconv/ for the list of possible encodings. # The default value is: UTF-8. DOXYFILE_ENCODING = UTF-8 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded by # double-quotes, unless you are using Doxywizard) that should identify the # project for which the documentation is generated. This name is used in the # title of most generated pages and in a few other places. # The default value is: My Project. PROJECT_NAME = "EXRAIL Language" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. PROJECT_NUMBER = # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. PROJECT_BRIEF = "EXRAIL Language" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. PROJECT_LOGO = # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. OUTPUT_DIRECTORY = "_build" # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format # and will distribute the generated files over these directories. Enabling this # option can be useful when feeding doxygen a huge amount of source files, where # putting all generated files in the same directory would otherwise causes # performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to # control the number of sub-directories. # The default value is: NO. CREATE_SUBDIRS = NO # Controls the number of sub-directories that will be created when # CREATE_SUBDIRS tag is set to YES. Level 0 represents 16 directories, and every # level increment doubles the number of directories, resulting in 4096 # directories at level 8 which is the default and also the maximum value. The # sub-directories are organized in 2 levels, the first level always has a fixed # number of 16 directories. # Minimum value: 0, maximum value: 8, default value: 8. # This tag requires that the tag CREATE_SUBDIRS is set to YES. CREATE_SUBDIRS_LEVEL = 8 # If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII # characters to appear in the names of generated files. If set to NO, non-ASCII # characters will be escaped, for example _xE3_x81_x84 will be used for Unicode # U+3044. # The default value is: NO. ALLOW_UNICODE_NAMES = NO # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. # Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Bulgarian, # Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English # (United States), Esperanto, Farsi (Persian), Finnish, French, German, Greek, # Hindi, Hungarian, Indonesian, Italian, Japanese, Japanese-en (Japanese with # English messages), Korean, Korean-en (Korean with English messages), Latvian, # Lithuanian, Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, # Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, # Swedish, Turkish, Ukrainian and Vietnamese. # The default value is: English. OUTPUT_LANGUAGE = English # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. # The default value is: YES. BRIEF_MEMBER_DESC = YES # If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief # description of a member or function before the detailed description # # Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. # The default value is: YES. REPEAT_BRIEF = YES # This tag implements a quasi-intelligent brief description abbreviator that is # used to form the text in various listings. Each string in this list, if found # as the leading text of the brief description, will be stripped from the text # and the result, after processing the whole list, is used as the annotated # text. Otherwise, the brief description is used as-is. If left blank, the # following values are used ($name is automatically replaced with the name of # the entity):The $name class, The $name widget, The $name file, is, provides, # specifies, contains, represents, a, an and the. ABBREVIATE_BRIEF = "The $name class" \ "The $name widget" \ "The $name file" \ is \ provides \ specifies \ contains \ represents \ a \ an \ the # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then # doxygen will generate a detailed section even if there is only a brief # description. # The default value is: NO. ALWAYS_DETAILED_SEC = NO # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all # inherited members of a class in the documentation of that class as if those # members were ordinary class members. Constructors, destructors and assignment # operators of the base classes will not be shown. # The default value is: NO. INLINE_INHERITED_MEMB = NO # If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path # before files name in the file list and in the header files. If set to NO the # shortest path that makes the file name unique will be used # The default value is: YES. FULL_PATH_NAMES = YES # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. # Stripping is only done if one of the specified strings matches the left-hand # part of the path. The tag can be used to show relative paths in the file list. # If left blank the directory from which doxygen is run is used as the path to # strip. # # Note that you can specify absolute paths here, but also relative paths, which # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. STRIP_FROM_PATH = # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which # header file to include in order to use a class. If left blank only the name of # the header file containing the class definition is used. Otherwise one should # specify the list of include paths that are normally passed to the compiler # using the -I flag. STRIP_FROM_INC_PATH = # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't # support long names like on DOS, Mac, or CD-ROM. # The default value is: NO. SHORT_NAMES = NO # If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the # first line (until the first dot) of a Javadoc-style comment as the brief # description. If set to NO, the Javadoc-style will behave just like regular Qt- # style comments (thus requiring an explicit @brief command for a brief # description.) # The default value is: NO. JAVADOC_AUTOBRIEF = NO # If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line # such as # /*************** # as being the beginning of a Javadoc-style comment "banner". If set to NO, the # Javadoc-style will behave just like regular comments and it will not be # interpreted by doxygen. # The default value is: NO. JAVADOC_BANNER = NO # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If # set to NO, the Qt-style will behave just like regular Qt-style comments (thus # requiring an explicit \brief command for a brief description.) # The default value is: NO. QT_AUTOBRIEF = NO # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a # multi-line C++ special comment block (i.e. a block of //! or /// comments) as # a brief description. This used to be the default behavior. The new default is # to treat a multi-line C++ comment block as a detailed description. Set this # tag to YES if you prefer the old behavior instead. # # Note that setting this tag to YES also means that rational rose comments are # not recognized any more. # The default value is: NO. MULTILINE_CPP_IS_BRIEF = NO # By default Python docstrings are displayed as preformatted text and doxygen's # special commands cannot be used. By setting PYTHON_DOCSTRING to NO the # doxygen's special commands can be used and the contents of the docstring # documentation blocks is shown as doxygen documentation. # The default value is: YES. PYTHON_DOCSTRING = YES # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. # The default value is: YES. INHERIT_DOCS = YES # If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new # page for each member. If set to NO, the documentation of a member will be part # of the file/class/namespace that contains it. # The default value is: NO. SEPARATE_MEMBER_PAGES = NO # The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen # uses this value to replace tabs by spaces in code fragments. # Minimum value: 1, maximum value: 16, default value: 4. TAB_SIZE = 4 # This tag can be used to specify a number of aliases that act as commands in # the documentation. An alias has the form: # name=value # For example adding # "sideeffect=@par Side Effects:^^" # will allow you to put the command \sideeffect (or @sideeffect) in the # documentation, which will result in a user-defined paragraph with heading # "Side Effects:". Note that you cannot put \n's in the value part of an alias # to insert newlines (in the resulting output). You can put ^^ in the value part # of an alias to insert a newline as if a physical newline was in the original # file. When you need a literal { or } or , in the value part of an alias you # have to escape them by means of a backslash (\), this can lead to conflicts # with the commands \{ and \} for these it is advised to use the version @{ and # @} or use a double escape (\\{ and \\}) ALIASES = # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all # members will be omitted, etc. # The default value is: NO. OPTIMIZE_OUTPUT_FOR_C = NO # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or # Python sources only. Doxygen will then generate output that is more tailored # for that language. For instance, namespaces will be presented as packages, # qualified scopes will look different, etc. # The default value is: NO. OPTIMIZE_OUTPUT_JAVA = NO # Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran # sources. Doxygen will then generate output that is tailored for Fortran. # The default value is: NO. OPTIMIZE_FOR_FORTRAN = NO # Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL # sources. Doxygen will then generate output that is tailored for VHDL. # The default value is: NO. OPTIMIZE_OUTPUT_VHDL = NO # Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice # sources only. Doxygen will then generate output that is more tailored for that # language. For instance, namespaces will be presented as modules, types will be # separated into more groups, etc. # The default value is: NO. OPTIMIZE_OUTPUT_SLICE = NO # Doxygen selects the parser to use depending on the extension of the files it # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and # language is one of the parsers supported by doxygen: IDL, Java, JavaScript, # Csharp (C#), C, C++, Lex, D, PHP, md (Markdown), Objective-C, Python, Slice, # VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: # FortranFree, unknown formatted Fortran: Fortran. In the later case the parser # tries to guess whether the code is fixed or free formatted code, this is the # default for Fortran type files). For instance to make doxygen treat .inc files # as Fortran files (default is PHP), and .f files as C (default is Fortran), # use: inc=Fortran f=C. # # Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise # the files are not read by doxygen. When specifying no_extension you should add # * to the FILE_PATTERNS. # # Note see also the list of default file extension mappings. EXTENSION_MAPPING = # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable # documentation. See https://daringfireball.net/projects/markdown/ for details. # The output of markdown processing is further processed by doxygen, so you can # mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in # case of backward compatibilities issues. # The default value is: YES. MARKDOWN_SUPPORT = YES # When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up # to that level are automatically included in the table of contents, even if # they do not have an id attribute. # Note: This feature currently applies only to Markdown headings. # Minimum value: 0, maximum value: 99, default value: 5. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. TOC_INCLUDE_HEADINGS = 5 # The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to # generate identifiers for the Markdown headings. Note: Every identifier is # unique. # Possible values are: DOXYGEN use a fixed 'autotoc_md' string followed by a # sequence number starting at 0 and GITHUB use the lower case version of title # with any whitespace replaced by '-' and punctuation characters removed. # The default value is: DOXYGEN. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. MARKDOWN_ID_STYLE = DOXYGEN # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or # globally by setting AUTOLINK_SUPPORT to NO. # The default value is: YES. AUTOLINK_SUPPORT = YES # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want # to include (a tag file for) the STL sources as input, then you should set this # tag to YES in order to let doxygen match functions declarations and # definitions whose arguments contain STL classes (e.g. func(std::string); # versus func(std::string) {}). This also make the inheritance and collaboration # diagrams that involve STL classes more complete and accurate. # The default value is: NO. BUILTIN_STL_SUPPORT = NO # If you use Microsoft's C++/CLI language, you should set this option to YES to # enable parsing support. # The default value is: NO. CPP_CLI_SUPPORT = NO # Set the SIP_SUPPORT tag to YES if your project consists of sip (see: # https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen # will parse them like normal C++ but will assume all classes use public instead # of private inheritance when no explicit protection keyword is present. # The default value is: NO. SIP_SUPPORT = NO # For Microsoft's IDL there are propget and propput attributes to indicate # getter and setter methods for a property. Setting this option to YES will make # doxygen to replace the get and set methods by a property in the documentation. # This will only work if the methods are indeed getting or setting a simple # type. If this is not the case, or you want to show the methods anyway, you # should set this option to NO. # The default value is: YES. IDL_PROPERTY_SUPPORT = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES then doxygen will reuse the documentation of the first # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. # The default value is: NO. DISTRIBUTE_GROUP_DOC = NO # If one adds a struct or class to a group and this option is enabled, then also # any nested class or struct is added to the same group. By default this option # is disabled and one has to add nested compounds explicitly via \ingroup. # The default value is: NO. GROUP_NESTED_COMPOUNDS = NO # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that # type (e.g. under the Public Functions section). Set it to NO to prevent # subgrouping. Alternatively, this can be done per class using the # \nosubgrouping command. # The default value is: YES. SUBGROUPING = YES # When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions # are shown inside the group in which they are included (e.g. using \ingroup) # instead of on a separate page (for HTML and Man pages) or section (for LaTeX # and RTF). # # Note that this feature does not work in combination with # SEPARATE_MEMBER_PAGES. # The default value is: NO. INLINE_GROUPED_CLASSES = NO # When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions # with only public data fields or simple typedef fields will be shown inline in # the documentation of the scope in which they are defined (i.e. file, # namespace, or group documentation), provided this scope is documented. If set # to NO, structs, classes, and unions are shown on a separate page (for HTML and # Man pages) or section (for LaTeX and RTF). # The default value is: NO. INLINE_SIMPLE_STRUCTS = NO # When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or # enum is documented as struct, union, or enum with the name of the typedef. So # typedef struct TypeS {} TypeT, will appear in the documentation as a struct # with name TypeT. When disabled the typedef will appear as a member of a file, # namespace, or class. And the struct will be named TypeS. This can typically be # useful for C code in case the coding convention dictates that all compound # types are typedef'ed and only the typedef is referenced, never the tag name. # The default value is: NO. TYPEDEF_HIDES_STRUCT = NO # The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This # cache is used to resolve symbols given their name and scope. Since this can be # an expensive process and often the same symbol appears multiple times in the # code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small # doxygen will become slower. If the cache is too large, memory is wasted. The # cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range # is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 # symbols. At the end of a run doxygen will report the cache usage and suggest # the optimal cache size from a speed point of view. # Minimum value: 0, maximum value: 9, default value: 0. LOOKUP_CACHE_SIZE = 0 # The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use # during processing. When set to 0 doxygen will based this on the number of # cores available in the system. You can set it explicitly to a value larger # than 0 to get more control over the balance between CPU load and processing # speed. At this moment only the input processing can be done using multiple # threads. Since this is still an experimental feature the default is set to 1, # which effectively disables parallel processing. Please report any issues you # encounter. Generating dot graphs in parallel is controlled by the # DOT_NUM_THREADS setting. # Minimum value: 0, maximum value: 32, default value: 1. NUM_PROC_THREADS = 1 # If the TIMESTAMP tag is set different from NO then each generated page will # contain the date or date and time when the page was generated. Setting this to # NO can help when comparing the output of multiple runs. # Possible values are: YES, NO, DATETIME and DATE. # The default value is: NO. TIMESTAMP = NO #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- # If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in # documentation are documented, even if no documentation was available. Private # class members and static file members will be hidden unless the # EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. # Note: This will also disable the warnings about undocumented members that are # normally produced when WARNINGS is set to YES. # The default value is: NO. EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. # The default value is: NO. EXTRACT_PRIVATE = YES # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual # methods of a class will be included in the documentation. # The default value is: NO. EXTRACT_PRIV_VIRTUAL = NO # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. EXTRACT_PACKAGE = NO # If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. # The default value is: NO. EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, # only classes defined in header files are included. Does not have any effect # for Java sources. # The default value is: YES. EXTRACT_LOCAL_CLASSES = YES # This flag is only useful for Objective-C code. If set to YES, local methods, # which are defined in the implementation section but not in the interface are # included in the documentation. If set to NO, only methods in the interface are # included. # The default value is: NO. EXTRACT_LOCAL_METHODS = YES # If this flag is set to YES, the members of anonymous namespaces will be # extracted and appear in the documentation as a namespace called # 'anonymous_namespace{file}', where file will be replaced with the base name of # the file that contains the anonymous namespace. By default anonymous namespace # are hidden. # The default value is: NO. EXTRACT_ANON_NSPACES = NO # If this flag is set to YES, the name of an unnamed parameter in a declaration # will be determined by the corresponding definition. By default unnamed # parameters remain unnamed in the output. # The default value is: YES. RESOLVE_UNNAMED_PARAMS = YES # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation # section is generated. This option has no effect if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_MEMBERS = NO # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set # to NO, these classes will be included in the various overviews. This option # will also hide undocumented C++ concepts if enabled. This option has no effect # if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend # declarations. If set to NO, these declarations will be included in the # documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any # documentation blocks found inside the body of a function. If set to NO, these # blocks will be appended to the function's detailed documentation block. # The default value is: NO. HIDE_IN_BODY_DOCS = NO # The INTERNAL_DOCS tag determines if documentation that is typed after a # \internal command is included. If the tag is set to NO then the documentation # will be excluded. Set it to YES to include the internal documentation. # The default value is: NO. INTERNAL_DOCS = NO # With the correct setting of option CASE_SENSE_NAMES doxygen will better be # able to match the capabilities of the underlying filesystem. In case the # filesystem is case sensitive (i.e. it supports files in the same directory # whose names only differ in casing), the option must be set to YES to properly # deal with such files in case they appear in the input. For filesystems that # are not case sensitive the option should be set to NO to properly deal with # output files written for symbols that only differ in casing, such as for two # classes, one named CLASS and the other named Class, and to also support # references to files without having to specify the exact matching casing. On # Windows (including Cygwin) and MacOS, users should typically set this option # to NO, whereas on Linux or other Unix flavors it should typically be set to # YES. # Possible values are: SYSTEM, NO and YES. # The default value is: SYSTEM. CASE_SENSE_NAMES = SYSTEM # If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with # their full class and namespace scopes in the documentation. If set to YES, the # scope will be hidden. # The default value is: NO. HIDE_SCOPE_NAMES = NO # If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will # append additional text to a page's title, such as Class Reference. If set to # YES the compound reference will be hidden. # The default value is: NO. HIDE_COMPOUND_REFERENCE= NO # If the SHOW_HEADERFILE tag is set to YES then the documentation for a class # will show which file needs to be included to use the class. # The default value is: YES. SHOW_HEADERFILE = YES # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. SHOW_INCLUDE_FILES = YES # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each # grouped member an include statement to the documentation, telling the reader # which file to include in order to use the member. # The default value is: NO. SHOW_GROUPED_MEMB_INC = NO # If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. FORCE_LOCAL_INCLUDES = NO # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the # documentation for inline members. # The default value is: YES. INLINE_INFO = YES # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the # (detailed) documentation of file and class members alphabetically by member # name. If set to NO, the members will appear in declaration order. # The default value is: YES. SORT_MEMBER_DOCS = YES # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member # name. If set to NO, the members will appear in declaration order. Note that # this will also influence the order of the classes in the class list. # The default value is: NO. SORT_BRIEF_DOCS = NO # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the # (brief and detailed) documentation of class members so that constructors and # destructors are listed first. If set to NO the constructors will appear in the # respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. # Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief # member documentation. # Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting # detailed member documentation. # The default value is: NO. SORT_MEMBERS_CTORS_1ST = NO # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy # of group names into alphabetical order. If set to NO the group names will # appear in their defined order. # The default value is: NO. SORT_GROUP_NAMES = NO # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by # fully-qualified names, including namespaces. If set to NO, the class list will # be sorted only by class name, not including the namespace part. # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. # Note: This option applies only to the class list, not to the alphabetical # list. # The default value is: NO. SORT_BY_SCOPE_NAME = NO # If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper # type resolution of all parameters of a function it will reject a match between # the prototype and the implementation of a member function even if there is # only one candidate or it is obvious which candidate to choose by doing a # simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still # accept a match between prototype and implementation in such cases. # The default value is: NO. STRICT_PROTO_MATCHING = NO # The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo # list. This list is created by putting \todo commands in the documentation. # The default value is: YES. GENERATE_TODOLIST = YES # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test # list. This list is created by putting \test commands in the documentation. # The default value is: YES. GENERATE_TESTLIST = YES # The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug # list. This list is created by putting \bug commands in the documentation. # The default value is: YES. GENERATE_BUGLIST = YES # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) # the deprecated list. This list is created by putting \deprecated commands in # the documentation. # The default value is: YES. GENERATE_DEPRECATEDLIST= YES # The ENABLED_SECTIONS tag can be used to enable conditional documentation # sections, marked by \if ... \endif and \cond # ... \endcond blocks. ENABLED_SECTIONS = # The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the # initial value of a variable or macro / define can have for it to appear in the # documentation. If the initializer consists of more lines than specified here # it will be hidden. Use a value of 0 to hide initializers completely. The # appearance of the value of individual variables and macros / defines can be # controlled using \showinitializer or \hideinitializer command in the # documentation regardless of this setting. # Minimum value: 0, maximum value: 10000, default value: 30. MAX_INITIALIZER_LINES = 30 # Set the SHOW_USED_FILES tag to NO to disable the list of files generated at # the bottom of the documentation of classes and structs. If set to YES, the # list will mention the files that were used to generate the documentation. # The default value is: YES. SHOW_USED_FILES = YES # Set the SHOW_FILES tag to NO to disable the generation of the Files page. This # will remove the Files entry from the Quick Index and from the Folder Tree View # (if specified). # The default value is: YES. SHOW_FILES = YES # Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces # page. This will remove the Namespaces entry from the Quick Index and from the # Folder Tree View (if specified). # The default value is: YES. SHOW_NAMESPACES = YES # The FILE_VERSION_FILTER tag can be used to specify a program or script that # doxygen should invoke to get the current version for each file (typically from # the version control system). Doxygen will invoke the program by executing (via # popen()) the command command input-file, where command is the value of the # FILE_VERSION_FILTER tag, and input-file is the name of an input file provided # by doxygen. Whatever the program writes to standard output is used as the file # version. For an example see the documentation. FILE_VERSION_FILTER = # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed # by doxygen. The layout file controls the global structure of the generated # output files in an output format independent way. To create the layout file # that represents doxygen's defaults, run doxygen with the -l option. You can # optionally specify a file name after the option, if omitted DoxygenLayout.xml # will be used as the name of the layout file. See also section "Changing the # layout of pages" for information. # # Note that if you run doxygen from a directory containing a file called # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib # extension is automatically appended if omitted. This requires the bibtex tool # to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. CITE_BIB_FILES = #--------------------------------------------------------------------------- # Configuration options related to warning and progress messages #--------------------------------------------------------------------------- # The QUIET tag can be used to turn on/off the messages that are generated to # standard output by doxygen. If QUIET is set to YES this implies that the # messages are off. # The default value is: NO. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES # this implies that the warnings are on. # # Tip: Turn warnings on while writing the documentation. # The default value is: YES. WARNINGS = YES # If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. WARN_IF_UNDOCUMENTED = YES # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as documenting some parameters in # a documented function twice, or documenting parameters that don't exist or # using markup commands wrongly. # The default value is: YES. WARN_IF_DOC_ERROR = YES # If WARN_IF_INCOMPLETE_DOC is set to YES, doxygen will warn about incomplete # function parameter documentation. If set to NO, doxygen will accept that some # parameters have no documentation without warning. # The default value is: YES. WARN_IF_INCOMPLETE_DOC = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return # value. If set to NO, doxygen will only warn about wrong parameter # documentation, but not about the absence of documentation. If EXTRACT_ALL is # set to YES then this flag will automatically be disabled. See also # WARN_IF_INCOMPLETE_DOC # The default value is: NO. WARN_NO_PARAMDOC = NO # If WARN_IF_UNDOC_ENUM_VAL option is set to YES, doxygen will warn about # undocumented enumeration values. If set to NO, doxygen will accept # undocumented enumeration values. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: NO. WARN_IF_UNDOC_ENUM_VAL = NO # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS # then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but # at the end of the doxygen process doxygen will return with a non-zero status. # If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS_PRINT then doxygen behaves # like FAIL_ON_WARNINGS but in case no WARN_LOGFILE is defined doxygen will not # write the warning messages in between other messages but write them at the end # of a run, in case a WARN_LOGFILE is defined the warning messages will be # besides being in the defined file also be shown at the end of a run, unless # the WARN_LOGFILE is defined as - i.e. standard output (stdout) in that case # the behavior will remain as with the setting FAIL_ON_WARNINGS. # Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT. # The default value is: NO. WARN_AS_ERROR = NO # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which # will be replaced by the file and line number from which the warning originated # and the warning text. Optionally the format may contain $version, which will # be replaced by the version of the file (if it could be obtained via # FILE_VERSION_FILTER) # See also: WARN_LINE_FORMAT # The default value is: $file:$line: $text. WARN_FORMAT = "$file:$line: $text" # In the $text part of the WARN_FORMAT command it is possible that a reference # to a more specific place is given. To make it easier to jump to this place # (outside of doxygen) the user can define a custom "cut" / "paste" string. # Example: # WARN_LINE_FORMAT = "'vi $file +$line'" # See also: WARN_FORMAT # The default value is: at line $line of file $file. WARN_LINE_FORMAT = "at line $line of file $file" # The WARN_LOGFILE tag can be used to specify a file to which warning and error # messages should be written. If left blank the output is written to standard # error (stderr). In case the file specified cannot be opened for writing the # warning and error messages are written to standard error. When as file - is # specified the warning and error messages are written to standard output # (stdout). WARN_LOGFILE = #--------------------------------------------------------------------------- # Configuration options related to the input files #--------------------------------------------------------------------------- # The INPUT tag is used to specify the files and/or directories that contain # documented source files. You may enter file names like myfile.cpp or # directories like /usr/src/myproject. Separate the files or directories with # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. INPUT = ../ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv # documentation (see: # https://www.gnu.org/software/libiconv/) for the list of possible encodings. # See also: INPUT_FILE_ENCODING # The default value is: UTF-8. INPUT_ENCODING = UTF-8 # This tag can be used to specify the character encoding of the source files # that doxygen parses The INPUT_FILE_ENCODING tag can be used to specify # character encoding on a per file pattern basis. Doxygen will compare the file # name with each pattern and apply the encoding instead of the default # INPUT_ENCODING) if there is a match. The character encodings are a list of the # form: pattern=encoding (like *.php=ISO-8859-1). See cfg_input_encoding # "INPUT_ENCODING" for further information on supported encodings. INPUT_FILE_ENCODING = # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and # *.h) to filter out the source-files in the directories. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # read by doxygen. # # Note the list of default checked file patterns might differ from the list of # default file extension mappings. # # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cxxm, # *.cpp, *.cppm, *.c++, *.c++m, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, # *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.ixx, *.l, *.cs, *.d, *.php, # *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be # provided as doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, # *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = EXRAIL2MacroReset.h # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. # The default value is: NO. RECURSIVE = NO # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. # # Note that relative paths are relative to the directory from which doxygen is # run. EXCLUDE = _build # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded # from the input. # The default value is: NO. EXCLUDE_SYMLINKS = NO # If the value of the INPUT tag contains directories, you can use the # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. # # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* EXCLUDE_PATTERNS = # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, # ANamespace::AClass, ANamespace::*Test EXCLUDE_SYMBOLS = # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include # command). EXAMPLE_PATH = # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and # *.h) to filter out the source-files in the directories. If left blank all # files are included. EXAMPLE_PATTERNS = * # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands # irrespective of the value of the RECURSIVE tag. # The default value is: NO. EXAMPLE_RECURSIVE = NO # The IMAGE_PATH tag can be used to specify one or more files or directories # that contain images that are to be included in the documentation (see the # \image command). IMAGE_PATH = # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program # by executing (via popen()) the command: # # # # where is the value of the INPUT_FILTER tag, and is the # name of an input file. Doxygen will then use the output that the filter # program writes to standard output. If FILTER_PATTERNS is specified, this tag # will be ignored. # # Note that the filter must not add or remove lines; it is applied before the # code is scanned, but not when the output code is generated. If lines are added # or removed, the anchors will not be placed correctly. # # Note that doxygen will use the data processed and written to standard output # for further processing, therefore nothing else, like debug statements or used # commands (so in case of a Windows batch file always use @echo OFF), should be # written to standard output. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. INPUT_FILTER = # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern # basis. Doxygen will compare the file name with each pattern and apply the # filter if there is a match. The filters are a list of the form: pattern=filter # (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how # filters are used. If the FILTER_PATTERNS tag is empty or if none of the # patterns match the file name, INPUT_FILTER is applied. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using # INPUT_FILTER) will also be used to filter the input files that are used for # producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). # The default value is: NO. FILTER_SOURCE_FILES = NO # The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file # pattern. A pattern will override the setting for FILTER_PATTERN (if any) and # it is also possible to disable source filtering for a specific pattern using # *.ext= (so without naming a filter). # This tag requires that the tag FILTER_SOURCE_FILES is set to YES. FILTER_SOURCE_PATTERNS = # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that # is part of the input, its contents will be placed on the main page # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. USE_MDFILE_AS_MAINPAGE = # The Fortran standard specifies that for fixed formatted Fortran code all # characters from position 72 are to be considered as comment. A common # extension is to allow longer lines before the automatic comment starts. The # setting FORTRAN_COMMENT_AFTER will also make it possible that longer lines can # be processed before the automatic comment starts. # Minimum value: 7, maximum value: 10000, default value: 72. FORTRAN_COMMENT_AFTER = 72 #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- # If the SOURCE_BROWSER tag is set to YES then a list of source files will be # generated. Documented entities will be cross-referenced with these sources. # # Note: To get rid of all source code in the generated output, make sure that # also VERBATIM_HEADERS is set to NO. # The default value is: NO. SOURCE_BROWSER = NO # Setting the INLINE_SOURCES tag to YES will include the body of functions, # classes and enums directly into the documentation. # The default value is: NO. INLINE_SOURCES = NO # Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any # special comment blocks from generated source code fragments. Normal C, C++ and # Fortran comments will always remain visible. # The default value is: YES. STRIP_CODE_COMMENTS = YES # If the REFERENCED_BY_RELATION tag is set to YES then for each documented # entity all documented functions referencing it will be listed. # The default value is: NO. REFERENCED_BY_RELATION = NO # If the REFERENCES_RELATION tag is set to YES then for each documented function # all documented entities called/used by that function will be listed. # The default value is: NO. REFERENCES_RELATION = NO # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set # to YES then the hyperlinks from functions in REFERENCES_RELATION and # REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will # link to the documentation. # The default value is: YES. REFERENCES_LINK_SOURCE = YES # If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the # source code will show a tooltip with additional information such as prototype, # brief description and links to the definition and documentation. Since this # will make the HTML file larger and loading of large files a bit slower, you # can opt to disable this feature. # The default value is: YES. # This tag requires that the tag SOURCE_BROWSER is set to YES. SOURCE_TOOLTIPS = YES # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in # source browser. The htags tool is part of GNU's global source tagging system # (see https://www.gnu.org/software/global/global.html). You will need version # 4.8.6 or higher. # # To use it do the following: # - Install the latest version of global # - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file # - Make sure the INPUT points to the root of the source tree # - Run doxygen as normal # # Doxygen will invoke htags (and that will in turn invoke gtags), so these # tools must be available from the command line (i.e. in the search path). # # The result: instead of the source browser generated by doxygen, the links to # source code will now point to the output of htags. # The default value is: NO. # This tag requires that the tag SOURCE_BROWSER is set to YES. USE_HTAGS = NO # If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a # verbatim copy of the header file for each class for which an include is # specified. Set to NO to disable this. # See also: Section \class. # The default value is: YES. VERBATIM_HEADERS = YES # If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the # clang parser (see: # http://clang.llvm.org/) for more accurate parsing at the cost of reduced # performance. This can be particularly helpful with template rich C++ code for # which doxygen's built-in parser lacks the necessary type information. # Note: The availability of this option depends on whether or not doxygen was # generated with the -Duse_libclang=ON option for CMake. # The default value is: NO. CLANG_ASSISTED_PARSING = NO # If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS # tag is set to YES then doxygen will add the directory of each input to the # include path. # The default value is: YES. # This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. CLANG_ADD_INC_PATHS = YES # If clang assisted parsing is enabled you can provide the compiler with command # line options that you would normally use when invoking the compiler. Note that # the include paths will already be set by doxygen for the files and directories # specified with INPUT and INCLUDE_PATH. # This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. CLANG_OPTIONS = # If clang assisted parsing is enabled you can provide the clang parser with the # path to the directory containing a file called compile_commands.json. This # file is the compilation database (see: # http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the # options used when the source files were built. This is equivalent to # specifying the -p option to a clang tool, such as clang-check. These options # will then be passed to the parser. Any options specified with CLANG_OPTIONS # will be added as well. # Note: The availability of this option depends on whether or not doxygen was # generated with the -Duse_libclang=ON option for CMake. CLANG_DATABASE_PATH = #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- # If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all # compounds will be generated. Enable this if the project contains a lot of # classes, structs, unions or interfaces. # The default value is: YES. ALPHABETICAL_INDEX = YES # The IGNORE_PREFIX tag can be used to specify a prefix (or a list of prefixes) # that should be ignored while generating the index headers. The IGNORE_PREFIX # tag works for classes, function and member names. The entity will be placed in # the alphabetical list under the first letter of the entity name that remains # after removing the prefix. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. IGNORE_PREFIX = #--------------------------------------------------------------------------- # Configuration options related to the HTML output #--------------------------------------------------------------------------- # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. GENERATE_HTML = NO # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of # it. # The default directory is: html. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_OUTPUT = html # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each # generated HTML page (for example: .htm, .php, .asp). # The default value is: .html. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_FILE_EXTENSION = .html # The HTML_HEADER tag can be used to specify a user-defined HTML header file for # each generated HTML page. If the tag is left blank doxygen will generate a # standard header. # # To get valid HTML the header file that includes any scripts and style sheets # that doxygen needs, which is dependent on the configuration options used (e.g. # the setting GENERATE_TREEVIEW). It is highly recommended to start with a # default header using # doxygen -w html new_header.html new_footer.html new_stylesheet.css # YourConfigFile # and then modify the file new_header.html. See also section "Doxygen usage" # for information on how to generate the default header that doxygen normally # uses. # Note: The header is subject to change so you typically have to regenerate the # default header when upgrading to a newer version of doxygen. For a description # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_HEADER = # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # generated HTML page. If the tag is left blank doxygen will generate a standard # footer. See HTML_HEADER for more information on how to generate a default # footer and what special commands can be used inside the footer. See also # section "Doxygen usage" for information on how to generate the default footer # that doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_FOOTER = # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of # the HTML output. If left blank doxygen will generate a default style sheet. # See also section "Doxygen usage" for information on how to generate the style # sheet that doxygen normally uses. # Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as # it is more robust and this tag (HTML_STYLESHEET) will in the future become # obsolete. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_STYLESHEET = # The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined # cascading style sheets that are included after the standard style sheets # created by doxygen. Using this option one can overrule certain style aspects. # This is preferred over using HTML_STYLESHEET since it does not replace the # standard style sheet and is therefore more robust against future updates. # Doxygen will copy the style sheet files to the output directory. # Note: The order of the extra style sheet files is of importance (e.g. the last # style sheet in the list overrules the setting of the previous ones in the # list). # Note: Since the styling of scrollbars can currently not be overruled in # Webkit/Chromium, the styling will be left out of the default doxygen.css if # one or more extra stylesheets have been specified. So if scrollbar # customization is desired it has to be added explicitly. For an example see the # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_STYLESHEET = # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note # that these files will be copied to the base HTML output directory. Use the # $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these # files. In the HTML_STYLESHEET file, use the file name only. Also note that the # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_FILES = # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output # should be rendered with a dark or light theme. # Possible values are: LIGHT always generate light mode output, DARK always # generate dark mode output, AUTO_LIGHT automatically set the mode according to # the user preference, use light mode if no preference is set (the default), # AUTO_DARK automatically set the mode according to the user preference, use # dark mode if no preference is set and TOGGLE allow to user to switch between # light and dark mode via a button. # The default value is: AUTO_LIGHT. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE = AUTO_LIGHT # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a color-wheel, see # https://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. # Minimum value: 0, maximum value: 359, default value: 220. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_HUE = 220 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors # in the HTML output. For a value of 0 the output will use gray-scales only. A # value of 255 will produce the most vivid colors. # Minimum value: 0, maximum value: 255, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_SAT = 100 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the # luminance component of the colors in the HTML output. Values below 100 # gradually make the output lighter, whereas values above 100 make the output # darker. The value divided by 100 is the actual gamma applied, so 80 represents # a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not # change the gamma. # Minimum value: 40, maximum value: 240, default value: 80. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_GAMMA = 80 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that # are dynamically created via JavaScript. If disabled, the navigation index will # consists of multiple levels of tabs that are statically embedded in every HTML # page. Disable this option to support browsers that do not have JavaScript, # like the Qt help browser. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_DYNAMIC_MENUS = YES # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the # page has loaded. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_DYNAMIC_SECTIONS = NO # If the HTML_CODE_FOLDING tag is set to YES then classes and functions can be # dynamically folded and expanded in the generated HTML source code. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_CODE_FOLDING = YES # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand # and collapse entries dynamically later on. Doxygen will expand the tree to # such a level that at most the specified number of entries are visible (unless # a fully collapsed tree already exceeds this amount). So setting the number of # entries 1 will produce a full collapsed tree by default. 0 is a special value # representing an infinite number of entries and will result in a full expanded # tree by default. # Minimum value: 0, maximum value: 9999, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development # environment (see: # https://developer.apple.com/xcode/), introduced with OSX 10.5 (Leopard). To # create a documentation set, doxygen will generate a Makefile in the HTML # output directory. Running make will produce the docset in that directory and # running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at # startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy # genXcode/_index.html for more information. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_DOCSET = NO # This tag determines the name of the docset feed. A documentation feed provides # an umbrella under which multiple documentation sets from a single provider # (such as a company or product suite) can be grouped. # The default value is: Doxygen generated docs. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_FEEDNAME = "Doxygen generated docs" # This tag determines the URL of the docset feed. A documentation feed provides # an umbrella under which multiple documentation sets from a single provider # (such as a company or product suite) can be grouped. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_FEEDURL = # This tag specifies a string that should uniquely identify the documentation # set bundle. This should be a reverse domain-name style string, e.g. # com.mycompany.MyDocSet. Doxygen will append .docset to the name. # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_BUNDLE_ID = org.doxygen.Project # The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify # the documentation publisher. This should be a reverse domain-name style # string, e.g. com.mycompany.MyDocSet.documentation. # The default value is: org.doxygen.Publisher. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_PUBLISHER_ID = org.doxygen.Publisher # The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. # The default value is: Publisher. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop # on Windows. In the beginning of 2021 Microsoft took the original page, with # a.o. the download links, offline the HTML help workshop was already many years # in maintenance mode). You can download the HTML help workshop from the web # archives at Installation executable (see: # http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo # ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe). # # The HTML Help Workshop contains a compiler that can convert all HTML output # generated by doxygen into a single compiled HTML file (.chm). Compiled HTML # files are now used as the Windows 98 help format, and will replace the old # Windows help format (.hlp) on all Windows platforms in the future. Compressed # HTML files also contain an index, a table of contents, and you can search for # words in the documentation. The HTML workshop also contains a viewer for # compressed HTML files. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_HTMLHELP = NO # The CHM_FILE tag can be used to specify the file name of the resulting .chm # file. You can add a path in front of the file if the result should not be # written to the html output directory. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_FILE = # The HHC_LOCATION tag can be used to specify the location (absolute path # including file name) of the HTML help compiler (hhc.exe). If non-empty, # doxygen will try to run the HTML help compiler on the generated index.hhp. # The file has to be specified with full path. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. HHC_LOCATION = # The GENERATE_CHI flag controls if a separate .chi index file is generated # (YES) or that it should be included in the main .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. GENERATE_CHI = NO # The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) # and project file content. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_INDEX_ENCODING = # The BINARY_TOC flag controls whether a binary table of contents is generated # (YES) or a normal table of contents (NO) in the .chm file. Furthermore it # enables the Previous and Next buttons. # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. BINARY_TOC = NO # The TOC_EXPAND flag can be set to YES to add extra items for group members to # the table of contents of the HTML help documentation and to the tree view. # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. TOC_EXPAND = NO # The SITEMAP_URL tag is used to specify the full URL of the place where the # generated documentation will be placed on the server by the user during the # deployment of the documentation. The generated sitemap is called sitemap.xml # and placed on the directory specified by HTML_OUTPUT. In case no SITEMAP_URL # is specified no sitemap is generated. For information about the sitemap # protocol see https://www.sitemaps.org # This tag requires that the tag GENERATE_HTML is set to YES. SITEMAP_URL = # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help # (.qch) of the generated HTML documentation. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_QHP = NO # If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify # the file name of the resulting .qch file. The path specified is relative to # the HTML output folder. # This tag requires that the tag GENERATE_QHP is set to YES. QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace # (see: # https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual # Folders (see: # https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom # Filters (see: # https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom # Filters (see: # https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this # project's filter section matches. Qt Help Project / Filter Attributes (see: # https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_SECT_FILTER_ATTRS = # The QHG_LOCATION tag can be used to specify the location (absolute path # including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to # run qhelpgenerator on the generated .qhp file. # This tag requires that the tag GENERATE_QHP is set to YES. QHG_LOCATION = # If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be # generated, together with the HTML files, they form an Eclipse help plugin. To # install this plugin and make it available under the help contents menu in # Eclipse, the contents of the directory containing the HTML and XML files needs # to be copied into the plugins directory of eclipse. The name of the directory # within the plugins directory should be the same as the ECLIPSE_DOC_ID value. # After copying Eclipse needs to be restarted before the help appears. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_ECLIPSEHELP = NO # A unique identifier for the Eclipse help plugin. When installing the plugin # the directory name containing the HTML and XML files should also have this # name. Each documentation set should have its own identifier. # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. ECLIPSE_DOC_ID = org.doxygen.Project # If you want full control over the layout of the generated HTML pages it might # be necessary to disable the index and replace it with your own. The # DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top # of each HTML page. A value of NO enables the index and the value YES disables # it. Since the tabs in the index contain the same information as the navigation # tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. DISABLE_INDEX = NO # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. If the tag # value is set to YES, a side panel will be generated containing a tree-like # index structure (just like the one that is generated for HTML Help). For this # to work a browser that supports JavaScript, DHTML, CSS and frames is required # (i.e. any modern browser). Windows users are probably better off using the # HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can # further fine tune the look of the index (see "Fine-tuning the output"). As an # example, the default style sheet generated by doxygen has an example that # shows how to put an image at the root of the tree instead of the PROJECT_NAME. # Since the tree basically has the same information as the tab index, you could # consider setting DISABLE_INDEX to YES when enabling this option. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_TREEVIEW = NO # When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the # FULL_SIDEBAR option determines if the side bar is limited to only the treeview # area (value NO) or if it should extend to the full height of the window (value # YES). Setting this to YES gives a layout similar to # https://docs.readthedocs.io with more room for contents, but less room for the # project logo, title, and description. If either GENERATE_TREEVIEW or # DISABLE_INDEX is set to NO, this option has no effect. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. FULL_SIDEBAR = NO # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that # doxygen will group on one line in the generated HTML documentation. # # Note that a value of 0 will completely suppress the enum values from appearing # in the overview section. # Minimum value: 0, maximum value: 20, default value: 4. # This tag requires that the tag GENERATE_HTML is set to YES. ENUM_VALUES_PER_LINE = 4 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used # to set the initial width (in pixels) of the frame in which the tree is shown. # Minimum value: 0, maximum value: 1500, default value: 250. # This tag requires that the tag GENERATE_HTML is set to YES. TREEVIEW_WIDTH = 250 # If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to # external symbols imported via tag files in a separate window. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. EXT_LINKS_IN_WINDOW = NO # If the OBFUSCATE_EMAILS tag is set to YES, doxygen will obfuscate email # addresses. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. OBFUSCATE_EMAILS = YES # If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg # tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see # https://inkscape.org) to generate formulas as SVG images instead of PNGs for # the HTML output. These images will generally look nicer at scaled resolutions. # Possible values are: png (the default) and svg (looks nicer but requires the # pdf2svg or inkscape tool). # The default value is: png. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_FORMULA_FORMAT = png # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful # doxygen run you need to manually remove any form_*.png images from the HTML # output directory to force them to be regenerated. # Minimum value: 8, maximum value: 50, default value: 10. # This tag requires that the tag GENERATE_HTML is set to YES. FORMULA_FONTSIZE = 10 # The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands # to create new LaTeX commands to be used in formulas as building blocks. See # the section "Including formulas" for details. FORMULA_MACROFILE = # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # https://www.mathjax.org) which uses client side JavaScript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path # to it using the MATHJAX_RELPATH option. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. USE_MATHJAX = NO # With MATHJAX_VERSION it is possible to specify the MathJax version to be used. # Note that the different versions of MathJax have different requirements with # regards to the different settings, so it is possible that also other MathJax # settings have to be changed when switching between the different MathJax # versions. # Possible values are: MathJax_2 and MathJax_3. # The default value is: MathJax_2. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_VERSION = MathJax_2 # When MathJax is enabled you can set the default output format to be used for # the MathJax output. For more details about the output format see MathJax # version 2 (see: # http://docs.mathjax.org/en/v2.7-latest/output.html) and MathJax version 3 # (see: # http://docs.mathjax.org/en/latest/web/components/output.html). # Possible values are: HTML-CSS (which is slower, but has the best # compatibility. This is the name for Mathjax version 2, for MathJax version 3 # this will be translated into chtml), NativeMML (i.e. MathML. Only supported # for NathJax 2. For MathJax version 3 chtml will be used instead.), chtml (This # is the name for Mathjax version 3, for MathJax version 2 this will be # translated into HTML-CSS) and SVG. # The default value is: HTML-CSS. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_FORMAT = HTML-CSS # When MathJax is enabled you need to specify the location relative to the HTML # output directory using the MATHJAX_RELPATH option. The destination directory # should contain the MathJax.js script. For instance, if the mathjax directory # is located at the same level as the HTML output directory, then # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of # MathJax from https://www.mathjax.org before deployment. The default value is: # - in case of MathJax version 2: https://cdn.jsdelivr.net/npm/mathjax@2 # - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3 # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_RELPATH = # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example # for MathJax version 2 (see # https://docs.mathjax.org/en/v2.7-latest/tex.html#tex-and-latex-extensions): # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols # For example for MathJax version 3 (see # http://docs.mathjax.org/en/latest/input/tex/extensions/index.html): # MATHJAX_EXTENSIONS = ams # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_EXTENSIONS = # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces # of code that will be used on startup of the MathJax code. See the MathJax site # (see: # http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an # example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_CODEFILE = # When the SEARCHENGINE tag is enabled doxygen will generate a search box for # the HTML output. The underlying search engine uses javascript and DHTML and # should work on any modern browser. Note that when using HTML help # (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) # there is already a search function so this one should typically be disabled. # For large projects the javascript based search engine can be slow, then # enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to # search using the keyboard; to jump to the search box use + S # (what the is depends on the OS and browser, but it is typically # , /Node, # Edge and Graph Attributes specification You need to make sure dot is able # to find the font, which can be done by putting it in a standard location or by # setting the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the # directory containing the font. Default graphviz fontsize is 14. # The default value is: fontname=Helvetica,fontsize=10. # This tag requires that the tag HAVE_DOT is set to YES. DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10" # DOT_EDGE_ATTR is concatenated with DOT_COMMON_ATTR. For elegant style you can # add 'arrowhead=open, arrowtail=open, arrowsize=0.5'. Complete documentation about # arrows shapes. # The default value is: labelfontname=Helvetica,labelfontsize=10. # This tag requires that the tag HAVE_DOT is set to YES. DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10" # DOT_NODE_ATTR is concatenated with DOT_COMMON_ATTR. For view without boxes # around nodes set 'shape=plain' or 'shape=plaintext' Shapes specification # The default value is: shape=box,height=0.2,width=0.4. # This tag requires that the tag HAVE_DOT is set to YES. DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4" # You can set the path where dot can find font specified with fontname in # DOT_COMMON_ATTR and others dot attributes. # This tag requires that the tag HAVE_DOT is set to YES. DOT_FONTPATH = # If the CLASS_GRAPH tag is set to YES or GRAPH or BUILTIN then doxygen will # generate a graph for each documented class showing the direct and indirect # inheritance relations. In case the CLASS_GRAPH tag is set to YES or GRAPH and # HAVE_DOT is enabled as well, then dot will be used to draw the graph. In case # the CLASS_GRAPH tag is set to YES and HAVE_DOT is disabled or if the # CLASS_GRAPH tag is set to BUILTIN, then the built-in generator will be used. # If the CLASS_GRAPH tag is set to TEXT the direct and indirect inheritance # relations will be shown as texts / links. # Possible values are: NO, YES, TEXT, GRAPH and BUILTIN. # The default value is: YES. CLASS_GRAPH = YES # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a # graph for each documented class showing the direct and indirect implementation # dependencies (inheritance, containment, and class references variables) of the # class with other documented classes. Explicit enabling a collaboration graph, # when COLLABORATION_GRAPH is set to NO, can be accomplished by means of the # command \collaborationgraph. Disabling a collaboration graph can be # accomplished by means of the command \hidecollaborationgraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. COLLABORATION_GRAPH = YES # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for # groups, showing the direct groups dependencies. Explicit enabling a group # dependency graph, when GROUP_GRAPHS is set to NO, can be accomplished by means # of the command \groupgraph. Disabling a directory graph can be accomplished by # means of the command \hidegroupgraph. See also the chapter Grouping in the # manual. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. GROUP_GRAPHS = YES # If the UML_LOOK tag is set to YES, doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling # Language. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. UML_LOOK = NO # If the UML_LOOK tag is enabled, the fields and methods are shown inside the # class node. If there are many fields or methods and many nodes the graph may # become too big to be useful. The UML_LIMIT_NUM_FIELDS threshold limits the # number of items for each type to make the size more manageable. Set this to 0 # for no limit. Note that the threshold may be exceeded by 50% before the limit # is enforced. So when you set the threshold to 10, up to 15 fields may appear, # but if the number exceeds 15, the total amount of fields shown is limited to # 10. # Minimum value: 0, maximum value: 100, default value: 10. # This tag requires that the tag UML_LOOK is set to YES. UML_LIMIT_NUM_FIELDS = 10 # If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and # methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS # tag is set to YES, doxygen will add type and arguments for attributes and # methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen # will not generate fields with class member information in the UML graphs. The # class diagrams will look similar to the default class diagrams but using UML # notation for the relationships. # Possible values are: NO, YES and NONE. # The default value is: NO. # This tag requires that the tag UML_LOOK is set to YES. DOT_UML_DETAILS = NO # The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters # to display on a single line. If the actual line length exceeds this threshold # significantly it will wrapped across multiple lines. Some heuristics are apply # to avoid ugly line breaks. # Minimum value: 0, maximum value: 1000, default value: 17. # This tag requires that the tag HAVE_DOT is set to YES. DOT_WRAP_THRESHOLD = 17 # If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and # collaboration graphs will show the relations between templates and their # instances. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. TEMPLATE_RELATIONS = NO # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to # YES then doxygen will generate a graph for each documented file showing the # direct and indirect include dependencies of the file with other documented # files. Explicit enabling an include graph, when INCLUDE_GRAPH is is set to NO, # can be accomplished by means of the command \includegraph. Disabling an # include graph can be accomplished by means of the command \hideincludegraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. INCLUDE_GRAPH = YES # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are # set to YES then doxygen will generate a graph for each documented file showing # the direct and indirect include dependencies of the file with other documented # files. Explicit enabling an included by graph, when INCLUDED_BY_GRAPH is set # to NO, can be accomplished by means of the command \includedbygraph. Disabling # an included by graph can be accomplished by means of the command # \hideincludedbygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. INCLUDED_BY_GRAPH = YES # If the CALL_GRAPH tag is set to YES then doxygen will generate a call # dependency graph for every global function or class method. # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable call graphs for selected # functions only using the \callgraph command. Disabling a call graph can be # accomplished by means of the command \hidecallgraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. CALL_GRAPH = NO # If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller # dependency graph for every global function or class method. # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable caller graphs for selected # functions only using the \callergraph command. Disabling a caller graph can be # accomplished by means of the command \hidecallergraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. CALLER_GRAPH = NO # If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical # hierarchy of all classes instead of a textual one. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. GRAPHICAL_HIERARCHY = YES # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the # dependencies a directory has on other directories in a graphical way. The # dependency relations are determined by the #include relations between the # files in the directories. Explicit enabling a directory graph, when # DIRECTORY_GRAPH is set to NO, can be accomplished by means of the command # \directorygraph. Disabling a directory graph can be accomplished by means of # the command \hidedirectorygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. DIRECTORY_GRAPH = YES # The DIR_GRAPH_MAX_DEPTH tag can be used to limit the maximum number of levels # of child directories generated in directory dependency graphs by dot. # Minimum value: 1, maximum value: 25, default value: 1. # This tag requires that the tag DIRECTORY_GRAPH is set to YES. DIR_GRAPH_MAX_DEPTH = 1 # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section # output formats in the documentation of the dot tool (Graphviz (see: # https://www.graphviz.org/)). # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). # Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, # png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and # png:gdiplus:gdiplus. # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. DOT_IMAGE_FORMAT = png # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to # enable generation of interactive SVG images that allow zooming and panning. # # Note that this requires a modern browser other than Internet Explorer. Tested # and working are Firefox, Chrome, Safari, and Opera. # Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make # the SVG files visible. Older versions of IE do not have SVG support. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. INTERACTIVE_SVG = NO # The DOT_PATH tag can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found in the path. # This tag requires that the tag HAVE_DOT is set to YES. DOT_PATH = # The DOTFILE_DIRS tag can be used to specify one or more directories that # contain dot files that are included in the documentation (see the \dotfile # command). # This tag requires that the tag HAVE_DOT is set to YES. DOTFILE_DIRS = # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. # If left empty dia is assumed to be found in the default search path. DIA_PATH = # The DIAFILE_DIRS tag can be used to specify one or more directories that # contain dia files that are included in the documentation (see the \diafile # command). DIAFILE_DIRS = # When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the # path where java can find the plantuml.jar file or to the filename of jar file # to be used. If left blank, it is assumed PlantUML is not used or called during # a preprocessing step. Doxygen will generate a warning when it encounters a # \startuml command in this case and will not generate output for the diagram. PLANTUML_JAR_PATH = # When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a # configuration file for plantuml. PLANTUML_CFG_FILE = # When using plantuml, the specified paths are searched for files specified by # the !include statement in a plantuml block. PLANTUML_INCLUDE_PATH = # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes # that will be shown in the graph. If the number of nodes in a graph becomes # larger than this value, doxygen will truncate the graph, which is visualized # by representing a node as a red box. Note that doxygen if the number of direct # children of the root node in a graph is already larger than # DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that # the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. # Minimum value: 0, maximum value: 10000, default value: 50. # This tag requires that the tag HAVE_DOT is set to YES. DOT_GRAPH_MAX_NODES = 50 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs # generated by dot. A depth value of 3 means that only nodes reachable from the # root by following a path via at most 3 edges will be shown. Nodes that lay # further from the root node will be omitted. Note that setting this option to 1 # or 2 may greatly reduce the computation time needed for large code bases. Also # note that the size of a graph can be further restricted by # DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. # Minimum value: 0, maximum value: 1000, default value: 0. # This tag requires that the tag HAVE_DOT is set to YES. MAX_DOT_GRAPH_DEPTH = 0 # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) support # this, this feature is disabled by default. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. DOT_MULTI_TARGETS = NO # If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page # explaining the meaning of the various boxes and arrows in the dot generated # graphs. # Note: This tag requires that UML_LOOK isn't set, i.e. the doxygen internal # graphical representation for inheritance and collaboration diagrams is used. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. GENERATE_LEGEND = YES # If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate # files that are used to generate the various graphs. # # Note: This setting is not only used for dot files but also for msc temporary # files. # The default value is: YES. DOT_CLEANUP = YES # You can define message sequence charts within doxygen comments using the \msc # command. If the MSCGEN_TOOL tag is left empty (the default), then doxygen will # use a built-in version of mscgen tool to produce the charts. Alternatively, # the MSCGEN_TOOL tag can also specify the name an external tool. For instance, # specifying prog as the value, doxygen will call the tool as prog -T # -o . The external tool should support # output file formats "png", "eps", "svg", and "ismap". MSCGEN_TOOL = # The MSCFILE_DIRS tag can be used to specify one or more directories that # contain msc files that are included in the documentation (see the \mscfile # command). MSCFILE_DIRS = ================================================ FILE: docs/Makefile ================================================ # Minimal makefile for Sphinx documentation # # You can set these variables from the command line, and also # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) ================================================ FILE: docs/_static/css/dccex_theme.css ================================================ @import url(https://fonts.googleapis.com/css?family=Audiowide); @import url(https://fonts.googleapis.com/css?family=Roboto); h1, .h1 { font-family: Audiowide,Helvetica,Arial,sans-serif !important; font-weight: 500 !important; color: #00353d !important; /* font-size: 200% !important; */ font-size: 180% !important; text-shadow: 1px 1px #ffffff78; } html[data-theme='dark'] h1, .h1 { color: #ffffff !important; text-shadow: 1px 1px #00353d; } h2, .h2 { font-family: Roboto,Helvetica,Arial,sans-serif !important; color: #00353d !important; /* font-size: 190% !important; */ font-size: 160% !important; text-shadow: 1px 1px #ffffff78; } html[data-theme='dark'] h2, .h2 { color: #ffffff !important; text-shadow: 1px 1px #00353d; } html[data-theme='dark'] h2 a, html[data-theme='dark'] h2 a:visited { color: #00a3b9ff !important; } h3, .h3 { font-family: Roboto,Helvetica,Arial,sans-serif !important; color: #00353d !important; /* font-size: 160% !important; */ font-size: 140% !important; font-style: italic !important; text-shadow: 1px 1px #ffffff78; } html[data-theme='dark'] h3, .h3 { color: #ffffff !important; text-shadow: 1px 1px #00353d; } html[data-theme='dark'] h3 a, html[data-theme='dark'] h3 a:visited { color: #00a3b9ff !important; } h4, .h4 { font-family: Roboto,Helvetica,Arial,sans-serif !important; color: #00353d !important; /* font-size: 130% !important; */ font-size: 120% !important; text-shadow: 1px 1px #ffffff78; } html[data-theme='dark'] h4, .h4 { color: #00a3b9ff !important; text-shadow: 1px 1px #00353d; } html[data-theme='dark'] h4 a, html[data-theme='dark'] h4 a:visited { color: #00a3b9ff !important; text-shadow: 1px 1px #00353d; } h5, .h5 { font-family: Roboto,Helvetica,Arial,sans-serif !important; color: #00a3b9ff !important; /* font-size: 110% !important; */ font-size: 100% !important; } h6, .h6 { font-family: Roboto,Helvetica,Arial,sans-serif !important; color: #00a3b9ff !important; font-size: 90% !important; font-style: italic !important; } .clearer { clear: both; } .wy-nav-side { background: #031c20 !important; /* background: #031214 !important; */ } .caption-text { color: #00a3b9ff !important; } .wy-nav-top { background:#00a3b9ff !important; font-size: 80% !important; } .wy-nav-top a { font-family: Audiowide,Helvetica,Arial,sans-serif !important; font-weight: 100 !important; } .wy-nav-content { max-width: 1024px; } .wy-breadcrumbs { font-family: Roboto,Helvetica,Arial,sans-serif !important; font-size: 80% !important; } .wy-side-nav-search>a img.logo { width: 100%; } .rst-content table.docutils th { background-color: #F3F6F6; } .rst-content table.docutils td { background-color: #F3F6F6; } .rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td { background-color: #E0E0E0; } html[data-theme='dark'] .rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td { background-color: #ffffff08 !important; } .caption-number { font-size: small !important; } .caption-text { font-size: small !important; } table.intro-table { max-width: 600px; } .intro-table img { width: 70%; height: auto; margin: 5% 15%; } html[data-theme='dark'] .btn-neutral { color: #c1c1c1 !important; } #ex-rail-command-summary .wy-table-responsive { overflow: visible; } /* product titles */ .ex-prefix { font-weight: bold; color: #00a3b9; font-size: 110%; } .ex-suffix { font-weight: bold; color: #00353d; font-size: 110%; } html[data-theme='dark'] .ex-suffix { font-weight: bold; color: #006979; font-size: 110%; } /* main dcc-ex text only */ .dccex-prefix { font-family: Audiowide,Helvetica,Arial,sans-serif; font-weight: 600; color: #00353d; font-size: 110%; } html[data-theme='dark'] .dccex-prefix { font-family: Audiowide,Helvetica,Arial,sans-serif; font-weight: 600; color: #006979; font-size: 110%; } .dccex-suffix { font-family: Audiowide,Helvetica,Arial,sans-serif; font-weight: 600; color: #00a3b9; font-size: 110%; } /***************************/ .command-table thead th { text-align: center; } .command-table tbody td { white-space: normal; margin: 10px; padding: 8px 8px 8px 8px !important; } .command-table tbody tr:first-child td p code { white-space: nowrap !important; } .command-table tbody tr td p code { font-size: 110% !important; } .command-table tbody tr td p { font-size: 90% !important; } .command-table tbody tr td ol li p { font-size: 90% !important; } .command-table tbody tr td ol { margin-bottom: 0px !important; } .command-table .category { display: block; text-align: center; } .command-table tr:nth-child(odd) { background-color: #f1f1f1 !important; } .command-table tr:nth-child(even) { background-color: #f8f8f8 !important; } html[data-theme='dark'] .command-table tr:nth-child(even) { background-color: #ffffff08 !important; } .command-table td { background-color: #ffffff00 !important; } /* html[data-theme='dark'] .rst-content table.docutils tr:nth-child(odd) { background-color: #ffffff08 !important; } */ html[data-theme='dark'] .rst-content table.docutils td, .wy-table-bordered-all td { background-color: #fff40000 !important; } /* html[data-theme='dark'] .rst-content table.docutils .row-odd { background-color: #36ff0000 !important; } */ html[data-theme='dark'] .rst-content table.docutils th { background-color: #36ff0000 !important; color: white !important; font-style: italic !important;; font-weight: 700 !important;; } /* *************************************** */ html[data-theme='dark'] .sd-card { background-color: #0000008a; box-shadow: 0 0.5rem 1rem rgb(32 88 91 / 25%) !important; } /* *************************************** */ .dcclink a { background-color: #00a3b9ff; box-shadow: 0 2px 0 #00353dff; color: white !important; padding: 0.5em 0.5em; position: relative; text-decoration: none; text-transform: none; border-radius: 5px; } .dcclink-right a { background-color: #00a3b9ff; box-shadow: 0 2px 0 #00353dff; color: white !important; padding: 0.5em 0.5em; position: relative; text-decoration: none; text-transform: none; border-radius: 10px; float:right; margin: 0px 0px 0px 10px; } .dcclink a:visited { color: whitesmoke !important; } .dcclink a:hover { background-color: darkslategrey; cursor: pointer; } .dcclink a:active { box-shadow: none; top: 5px; } html[data-theme='dark'] .rst-content .guilabel { color: black; } .hr-dashed { margin: -10px 0px -10px 0px; border-top: 1px dashed #d2dfe3; } .hr-heavy { margin: -10px 0px -10px 0px; border-top: 5px solid #d2dfe3; } html[data-theme='dark'] .hr-dashed { border-top: 1px dashed #114759; } /* *************************************** */ a.githublink, .githublink a { background-color: #f7b656; box-shadow: 0 2px 0 #00353dff; color: white; padding: 3px 5px 3px 5px; position: relative; font-size: 90% !important; text-decoration: none; text-transform: none; border-radius: 5px; } .githublink-right a { background-color: #f7b656; box-shadow: 0 2px 0 #00353dff; color: white; padding: 3px 5px 3px 5px; position: relative; font-size: 90% !important; text-decoration: none; text-transform: none; border-radius: 10px; float:right; margin: 0px 0px 0px 0px; } .githublink a:visited { color: whitesmoke } .githublink a:hover { background-color: rgb(172, 95, 7); cursor: pointer; } .githublink a:active { box-shadow: none; top: 5px; } /* *************************************** */ svg { max-width: 100%; height: auto; } .responsive-image { max-width: 100%; height: auto; } /* *************************************** */ .warning-float-right { float: right; width: 40%; } .warning-float-right-narrow { float: right; width: 20%; } .warning-float-right-wide { float: right; width: 60%; } .note-float-right { float: right; width: 40%; } .note-float-right-narrow { float: right; width: 20%; } .code-block-float-right { float: right; width: 40%; margin: 0px 0px 0px 24px; } .note { background: #f7fcff !important; clear: none !important; } html[data-theme='dark'] .note { background: #ffffff24 !important; } .note p.admonition-title { background: #cbe1ef !important; } html[data-theme='dark'] .note p.admonition-title { background: #256a97 !important; } .tip { background: #eef5f4 !important; clear: none !important; } html[data-theme='dark'] .tip { background: #ffffff24 !important; clear: none !important; } .tip p.admonition-title { background: #9cd7cb !important; } html[data-theme='dark'] .tip p.admonition-title { background: #256a97 !important; } .admonition-todo { background: #f9f0e0 !important; clear: none !important; } html[data-theme='dark'] .admonition-todo { background: #ffffff24 !important; clear: none !important; } .admonition-todo p.admonition-title { background: #f7d1b0 !important; } html[data-theme='dark'] .admonition-todo p.admonition-title { background: #6d3403 !important; } /* *************************************** */ .menuselection { font-style: italic; font-weight: 700; } /* *************************************** */ .wy-table-responsive { margin-bottom: 12px !important; } /* override table width restrictions */ .table-wrap-text p, .table-grid-homepage p, .table-list-homepage p { white-space: normal !important; font-size: 110% !important; line-height: 140% !important; } .table-wrap-text tr:nth-child(odd), .table-grid-homepage tr:nth-child(odd), .table-list-homepage tr:nth-child(odd) { background-color: white !important; border-style: none !important; border-width:0px !important; } html[data-theme='dark'] tr:nth-child(odd), .table-grid-homepage tr:nth-child(odd), .table-list-homepage tr:nth-child(odd) { background-color: #ffffff08 !important; } .table-wrap-text tr:nth-child(even), .table-grid-homepage tr:nth-child(even), .table-list-homepage tr:nth-child(even) { background-color: #ffffff00 !important; border-style: none !important; border-width:0px !important; } .table-wrap-text td { background-color: white !important; border-style: none !important; border-width:0px !important; } html[data-theme='dark'] .table-wrap-text td { background-color: ffffff08 !important; } .table-grid-homepage td, .table-list-homepage td { font-size: 80% !important; color: #666666 !important; vertical-align:top !important; background-color: #ffffff00 !important; border-style: none !important; border-width: 0px !important; } .table-wrap-text, .table-grid-homepage, .table-list-homepage { margin-bottom: 24px; max-width: 100% !important; overflow: visible !important; border-style: none !important; border-width: 0px !important; } @media screen and (max-width: 900px) { .table-grid-homepage { display: none; } .table-list-homepage { display: block; } } @media not screen and (max-width: 900px) { .table-grid-homepage { display: block; } .table-list-homepage { display: none; } } .table-wrap-text th p, table-wrap-text-align-top th p { margin-bottom: unset; } /* *************************************** */ .image-min-width-144 { min-width: 144px; height: auto !important; } .image-min-width-72 { min-width: 72px; height: auto !important; } .image-float-right img { float:right; } .image-product-logo-float-right img { float:right; } @media screen and (max-width: 1000px) { .image-product-logo-float-right img { display: none; } } /* *************************************** */ /* Google search */ .gsc-input-box { border: 0px !important; } .gsib_a input { padding: 5px !important; background-color: #141414 !important; color:white !important; } .gsc-search-button .gsc-search-button-v2 { width: 40px !important; height: 21px !important; padding: 4px 4px !important; background-color: #00a3b9ff !important; border-color: #00a3b9ff !important; border-radius: 5px; } /* .gsc-search-button .gsc-search-button-v2 { width: 0px !important; padding: 7px 7px !important; border-color: #009300 !important; background-color: #009300 !important; } */ /* *************************************** */ /* sidebar level 3 bullet points */ nav#on-this-page ul.simple li ul li p { font-family: Roboto,Helvetica,Arial,sans-serif !important; font-size: 80% !important; line-height: 120% !important; margin-bottom: 0px !important; } /* sidebar level 3 bullet points */ nav#on-this-page ul.simple li ul li { font-family: Roboto,Helvetica,Arial,sans-serif !important; line-height: 120% !important; margin-bottom: 0px !important; } /* sidebar level 2 bullet points */ nav#on-this-page ul.simple li p { font-family: Roboto,Helvetica,Arial,sans-serif !important; font-size: 80% !important; line-height: 120% !important; margin-bottom: 0px !important; } /* sidebar level 2 bullet points */ nav#on-this-page ul.simple li { font-family: Roboto,Helvetica,Arial,sans-serif !important; line-height: 120% !important; margin-bottom: 0px !important; } nav#on-this-page ul.simple { font-family: Roboto,Helvetica,Arial,sans-serif !important; margin-bottom: 0px !important; } nav#on-this-page p { font-family: Roboto,Helvetica,Arial,sans-serif !important; margin-top: 0px !important; margin-bottom: 6px !important; } nav#on-this-page { margin-bottom: 10px !important; } /* in-this-section level 3 bullet points */ nav.in-this-section ul.simple li ul li p { font-family: Roboto,Helvetica,Arial,sans-serif !important; font-size: 80% !important; line-height: 120% !important; margin-bottom: 0px !important; } /* in-this-section level 3 bullet points */ nav.in-this-section ul.simple li ul li { font-family: Roboto,Helvetica,Arial,sans-serif !important; line-height: 120% !important; margin-bottom: 0px !important; } /* in-this-section level 2 bullet points */ nav.in-this-section ul.simple li p { font-family: Roboto,Helvetica,Arial,sans-serif !important; font-size: 80% !important; line-height: 120% !important; margin-bottom: 0px !important; } /* in-this-section level 2 bullet points */ nav.in-this-section ul.simple li { font-family: Roboto,Helvetica,Arial,sans-serif !important; line-height: 120% !important; margin-bottom: 0px !important; } nav.in-this-section ul.simple { font-family: Roboto,Helvetica,Arial,sans-serif !important; margin-bottom: 0px !important; } nav.in-this-section p { font-family: Roboto,Helvetica,Arial,sans-serif !important; font-style: italic; font-size: 90%; margin-top: 0px !important; margin-bottom: 6px !important; margin-left: -30px; } nav.in-this-section { margin-bottom: 20px !important; margin-left: 30px; } /* sidebars */ .rst-content .sidebar { padding: 12px 24px 12px 24px !important; border-radius: 10px; } html[data-theme='dark'] .rst-content .sidebar { background: #000000ff !important; border:#000000ff !important; } .sidebar-title { border-radius: 10px; } html[data-theme='dark'] .sidebar-title { background: #002735 !important; } /* news */ section#dcc-ex-model-railroading aside p.sidebar-title { font-size: 110% !important; font-family: Audiowide,Helvetica,Arial,sans-serif !important; font-weight: 500 !important; color: #00a3b9ff; text-shadow: 1px 1px 0 #00353dff; margin: -24px -24px 12px !important; } /* news */ p.ablog-post-title { font-family: Roboto,Helvetica,Arial,sans-serif !important; font-size: 90% !important; line-height: 130% !important; margin-bottom: 0px !important; font-weight: bold !important; } p.ablog-post-excerpt { font-family: Roboto,Helvetica,Arial,sans-serif !important; font-size: 90% !important; line-height: 130% !important; margin-bottom: 0px !important; margin-top: 6px !important; } p.ablog-post-expand { font-family: Roboto,Helvetica,Arial,sans-serif !important; font-size: 80% !important; line-height: 130% !important; margin-bottom: 10px !important; margin-top: 0px !important; margin-left: 20px; } li.ablog-post { list-style-type: none !important; margin: 0px !important; } img.sd-card-img-top { max-width: 30% !important; display: block !important; margin-left: auto !important; margin-right: auto !important; margin-top: 10px; margin-bottom: -5px !important; } .sd-card-header { margin-bottom: -10px !important; margin-top: 10px !important; padding-top: 0px !important; padding-bottom: 0px !important; } .sd-card-header p { line-height: 18px !important; } html[data-theme='dark'] .sd-card-header { border-bottom: 1px solid rgb(255 253 253 / 13%); } .sd-card-body ul li p { margin-bottom: 5px !important; } .sd-card-text { margin: 0 0 12px !important; } /* code */ .rst-content code { font-size: 100% !important; } .rst-content code.literal, .rst-content tt.literal { color: #ba2121 !important; font-size: 100% important; } html[data-theme='dark'] .rst-content code.literal, .rst-content tt.literal { color: #ff6000 !important; } /* general purpose */ .dcc-ex-red { color:red; } .dcc-ex-red-bold { color:red; font-weight: bold !important; } .dcc-ex-red-bold-italic { color:red; font-weight: bold !important; font-style: italic !important; } .dcc-ex-code { color:#ba2121; font-weight: bold !important; } .dcc-ex-text-size-200pct { font-size: 200% !important; line-height: 110% !important; } .dcc-ex-text-size-80pct { font-size: 80% !important; } .dcc-ex-text-size-60pct { font-size: 80% !important; } .new-in-v5 { font-family: Audiowide,Helvetica,Arial,sans-serif; font-weight: bold; font-style: italic; color: #00a3b9; font-size: 110%; } html[data-theme='dark'] .new-in-v5 { font-weight: normal; color: #ffffff; text-shadow: 0px 0px 10px #00a3b9; } /* *************************************** */ @media not screen and (max-width: 900px) { div.rst-footer-buttons { position: fixed; bottom:5px; width:350px; background: #c9c9c999; padding: 10px; border-radius: 10px; border-color: white !important; border: 4px solid; transform: translateX(50%); } html[data-theme='dark'] div.rst-footer-buttons { border-color: #141414 !important; background: #c9c9c92e; } footer { padding-bottom: 40px; font-size: 80% !important; } } @media screen and (max-width: 900px) { div.rst-footer-buttons { display:block; font-size: 80% !important; } } html[data-theme='dark'] .rst-content span.descname { color: #dbdd7c !important; } ================================================ FILE: docs/_static/css/sphinx_design_overrides.css ================================================ /* Override for the sphinx-design extension classes */ .sd-card-header { font-size: 110% !important; font-family: Audiowide,Helvetica,Arial,sans-serif !important; font-weight: 500 !important; color: #00a3b9ff; text-shadow: 1px 1px 0 #00353dff; margin-bottom: .5rem !important; } ================================================ FILE: docs/conf.py ================================================ # Configuration file for the Sphinx documentation builder. # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html import os import subprocess # Doxygen subprocess.call('doxygen DoxyfileEXRAIL', shell=True) # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'EXRAIL Language' copyright = '2025 - Peter Cole' author = 'Peter Cole' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ 'sphinx_sitemap', 'sphinxcontrib.spelling', 'sphinx_rtd_dark_mode', 'breathe' ] autosectionlabel_prefix_document = True # Don't make dark mode the user default default_dark_mode = False spelling_lang = 'en_UK' tokenizer_lang = 'en_UK' spelling_word_list_filename = ['spelling_wordlist.txt'] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] highlight_language = 'c++' numfig = True numfig_format = {'figure': 'Figure %s'} # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] html_logo = "./_static/images/product-logo-ex-rail.png" html_favicon = "./_static/images/favicon.ico" html_theme_options = { 'style_nav_header_background': 'white', 'logo_only': True, # Toc options 'includehidden': True, 'titles_only': False, # 'titles_only': True, 'collapse_navigation': False, # 'navigation_depth': 3, 'navigation_depth': 1, 'analytics_id': 'G-L5X0KNBF0W', } html_context = { 'display_github': True, 'github_user': 'DCC-EX', 'github_repo': 'CommandStation-EX', 'github_version': 'sphinx/docs/', } html_css_files = [ 'css/dccex_theme.css', 'css/sphinx_design_overrides.css', ] html_baseurl = 'https://dcc-ex.com/CommandStation-EX/' # Sphinx sitemap html_extra_path = [ 'robots.txt', ] # -- Breathe configuration ------------------------------------------------- breathe_projects = { "EXRAIL Language": "_build/xml/" } breathe_default_project = "EXRAIL Language" breathe_default_members = () ================================================ FILE: docs/index.rst ================================================ EXRAIL Language documentation ============================= Introduction ------------ EXRAIL - Extended Railroad Automation Instruction Language This page is a reference to all EXRAIL commands available with EX-CommandStation. Macros ------ .. doxygenfile:: EXRAIL2MacroReset.h :project: EXRAIL Language ================================================ FILE: docs/make.bat ================================================ @ECHO OFF pushd %~dp0 REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) set SOURCEDIR=. set BUILDDIR=_build %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( echo. echo.The 'sphinx-build' command was not found. Make sure you have Sphinx echo.installed, then set the SPHINXBUILD environment variable to point echo.to the full path of the 'sphinx-build' executable. Alternatively you echo.may add the Sphinx directory to PATH. echo. echo.If you don't have Sphinx installed, grab it from echo.https://www.sphinx-doc.org/ exit /b 1 ) if "%1" == "" goto help %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% goto end :help %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% :end popd ================================================ FILE: docs/requirements.txt ================================================ alabaster==1.0.0 attrs==25.1.0 babel==2.17.0 breathe==4.35.0 cattrs==24.1.2 certifi==2025.1.31 charset-normalizer==3.4.1 colorama==0.4.6 docutils==0.21.2 esbonio==0.16.5 exceptiongroup==1.2.2 idna==3.10 imagesize==1.4.1 Jinja2==3.1.5 lsprotocol==2023.0.1 MarkupSafe==3.0.2 packaging==24.2 platformdirs==4.3.6 pyenchant==3.2.2 pygls==1.3.1 Pygments==2.19.1 pyspellchecker==0.8.2 requests==2.32.3 snowballstemmer==2.2.0 Sphinx==8.1.3 sphinx-rtd-dark-mode==1.3.0 sphinx-rtd-theme==3.0.2 sphinx-sitemap==2.6.0 sphinxcontrib-applehelp==2.0.0 sphinxcontrib-devhelp==2.0.0 sphinxcontrib-htmlhelp==2.1.0 sphinxcontrib-jquery==4.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==2.0.0 sphinxcontrib-serializinghtml==2.0.0 sphinxcontrib-spelling==8.0.1 tomli==2.2.1 typing_extensions==4.12.2 urllib3==2.3.0 ================================================ FILE: docs/robots.txt ================================================ User-agent: * Sitemap: https://dcc-ex.com/CommandStation-EX/sitemap.xml ================================================ FILE: install_via_powershell.cmd ================================================ @ECHO OFF FOR /f "tokens=*" %%a IN ('powershell Get-ExecutionPolicy -Scope CurrentUser') DO SET PS_POLICY=%%a IF NOT %PS_POLICY=="Bypass" ( powershell Set-ExecutionPolicy -Scope CurrentUser Bypass ) powershell %~dp0%installer.ps1 IF NOT %PS_POLICY=="Bypass" ( powershell Set-ExecutionPolicy -Scope CurrentUser %PS_POLICY% ) ================================================ FILE: installer.json ================================================ [ { "Name": "BaseStationClassic", "Git": "DCC-EX/BaseStation-Classic", "Libraries": [ { "Name": "Ethernet", "Repo": "arduino-libraries/Ethernet", "Location": "libraries/Ethernet", "LibraryDownloadAvailable": true } ], "SupportedBoards": [ { "Name": "Uno", "FQBN": "arduino:avr:uno", "Platforms": [ { "Architecture": "avr", "Package": "arduino" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" } ], "ExtraLibraries": [] }, { "Name": "Mega", "FQBN": "arduino:avr:mega", "Platforms": [ { "Architecture": "avr", "Package": "arduino" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" } ], "ExtraLibraries": [] } ], "DisplayName": "Base Station Classic", "InputFileLocation": "DCCpp", "AllowAdvanced": false, "ConfigFile": "DCCpp/Config.h" }, { "Name": "CommandStation-EX", "Git": "DCC-EX/CommandStation-EX", "Libraries": [ { "Name": "Ethernet", "Repo": "arduino-libraries/Ethernet", "Location": "libraries/Ethernet", "LibraryDownloadAvailable": true }, { "Name": "DIO2", "Repo": "", "Location": "libraries/DIO2", "LibraryDownloadAvailable": true } ], "SupportedBoards": [ { "Name": "Uno", "FQBN": "arduino:avr:uno", "Platforms": [ { "Architecture": "avr", "Package": "arduino" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" } ], "ExtraLibraries": [] }, { "Name": "Mega", "FQBN": "arduino:avr:mega", "Platforms": [ { "Architecture": "avr", "Package": "arduino" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" } ], "ExtraLibraries": [] }, { "Name": "Mega Wifi", "FQBN": "arduino:avr:mega", "Platforms": [ { "Architecture": "avr", "Package": "arduino" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" } ], "ExtraLibraries": [] }, { "Name": "Nano", "FQBN": "arduino:avr:nano", "Platforms": [ { "Architecture": "avr", "Package": "arduino" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" } ], "ExtraLibraries": [] }, { "Name": "Nano Every", "FQBN": "arduino:megaavr:nanoevery", "Platforms": [ { "Architecture": "megaavr", "Package": "arduino" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" } ], "ExtraLibraries": [] }, { "Name": "Teensy 3.x", "FQBN": "teensy:avr:teensy31", "Platforms": [ { "Architecture": "teensy", "Package": "arduino" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" } ], "ExtraLibraries": [] }, { "Name": "Teensy 4.x", "FQBN": "teensy:avr:teensy41", "Platforms": [ { "Architecture": "teensy", "Package": "arduino" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" } ], "ExtraLibraries": [] }, { "Name": "SAMD21", "FQBN": "SparkFun:samd", "Platforms": [ { "Architecture": "avr", "Package": "arduino" }, { "Architecture": "samd", "Package": "arduino" }, { "Architecture": "samd", "Package": "SparkFun" } ], "SupportedMotoShields": [ { "Name": "Arduino Motor Shield", "Declaration": "STANDARD_MOTOR_SHIELD" }, { "Name": "Pololu MC33926 Motor Shield", "Declaration": "POLOLU_MOTOR_SHIELD" }, { "Name": "FireBox MK1", "Declaration": "FIREBOX_MK1" }, { "Name": "FireBox MK1S", "Declaration": "FIREBOX_MK1S" } ], "ExtraLibraries": [] } ], "DisplayName": "CommandStation EX", "InputFileLocation": "", "AllowAdvanced": true, "ConfigFile": "config.h" } ] ================================================ FILE: installer.ps1 ================================================ <# # © 2023 Peter Cole # # 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 . #> <############################################ For script errors set ExecutionPolicy: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Bypass ############################################> <############################################ Optional command line parameters: $buildDirectory - specify an existing directory rather than generating a new unique one $configDirectory - specify a directory containing existing files as per $configFiles ############################################> Param( [Parameter()] [String]$buildDirectory, [Parameter()] [String]$configDirectory ) <############################################ Define global parameters here such as known URLs etc. ############################################> $installerVersion = "v0.0.8" $configFiles = @("config.h", "myAutomation.h", "myHal.cpp", "mySetup.h") $wifiBoards = @("arduino:avr:mega", "esp32:esp32:esp32") $userDirectory = $env:USERPROFILE + "\" $gitHubAPITags = "https://api.github.com/repos/DCC-EX/CommandStation-EX/git/refs/tags" $gitHubURLPrefix = "https://github.com/DCC-EX/CommandStation-EX/archive/" if ((Get-WmiObject win32_operatingsystem | Select-Object osarchitecture).osarchitecture -eq "64-bit") { $arduinoCLIURL = "https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_64bit.zip" $arduinoCLIZip = $userDirectory + "Downloads\" + "arduino-cli_latest_Windows_64bit.zip" } else { $arduinoCLIURL = "https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_32bit.zip" $arduinoCLIZip = $userDirectory + "Downloads\" + "arduino-cli_latest_Windows_32bit.zip" } $arduinoCLIDirectory = $userDirectory + "arduino-cli" $arduinoCLI = $arduinoCLIDirectory + "\arduino-cli.exe" <############################################ List of supported devices with FQBN in case clones used that aren't detected ############################################> $supportedDevices = @( @{ name = "Arduino Mega or Mega 2560" fqbn = "arduino:avr:mega" }, @{ name = "Arduino Nano" fqbn = "arduino:avr:nano" }, @{ name = "Arduino Uno" fqbn = "arduino:avr:uno" }, @{ name = "ESP32 Dev Module" fqbn = "esp32:esp32:esp32" } ) <############################################ List of supported displays ############################################> $displayList = @( @{ option = "LCD 16 columns x 2 rows" configLine = "#define LCD_DRIVER 0x27,16,2" }, @{ option = "LCD 16 columns x 4 rows" configLine = "#define LCD_DRIVER 0x27,16,4" }, @{ option = "OLED 128 x 32" configLine = "#define OLED_DRIVER 128,32" }, @{ option = "OLED 128 x 64" configLine = "#define OLED_DRIVER 128,64" } ) <############################################ Basics of config.h ############################################> $configLines = @( "/*", "This config.h file was generated by the DCC-EX PowerShell installer $installerVersion", "*/", "", "// Define standard motor shield", "#define MOTOR_SHIELD_TYPE STANDARD_MOTOR_SHIELD", "" ) <############################################ Set default action for progress indicators, warnings, and errors ############################################> $global:ProgressPreference = "SilentlyContinue" $global:WarningPreference = "SilentlyContinue" $global:ErrorActionPreference = "SilentlyContinue" <############################################ If $buildDirectory not provided, generate a new time/date stamp based directory to use ############################################> if (!$PSBoundParameters.ContainsKey('buildDirectory')) { $buildDate = Get-Date -Format 'yyyyMMdd-HHmmss' $buildDirectory = $userDirectory + "EX-CommandStation-Installer\" + $buildDate } $commandStationDirectory = $buildDirectory + "\CommandStation-EX" <############################################ Write out intro message and prompt to continue ############################################> @" Welcome to the DCC-EX PowerShell installer for EX-CommandStation ($installerVersion) Current installer options: - EX-CommandStation will be built in $commandStationDirectory - Arduino CLI will downloaded and extracted to $arduinoCLIDirectory Before continuing, please ensure: - Your computer is connected to the internet - The device you wish to install EX-CommandStation on is connected to a USB port This installer will obtain the Arduino CLI (if not already present), and then download and install your chosen version of EX-CommandStation "@ <############################################ Prompt user to confirm all is ready to proceed ############################################> $confirmation = Read-Host "Enter 'Y' or 'y' then press to confirm you are ready to proceed, any other key to exit" if ($confirmation -ne "Y" -and $confirmation -ne "y") { Exit } <############################################ See if we have the Arduino CLI already, otherwise download and extract it ############################################> if (!(Test-Path -PathType Leaf -Path $arduinoCLI)) { if (!(Test-Path -PathType Container -Path $arduinoCLIDirectory)) { try { New-Item -ItemType Directory -Path $arduinoCLIDirectory | Out-Null } catch { Write-Output "Arduino CLI does not exist and cannot create directory $arduinoCLIDirectory" Exit } } Write-Output "`r`nDownloading and extracting Arduino CLI" try { Invoke-WebRequest -Uri $arduinoCLIURL -OutFile $arduinoCLIZip } catch { Write-Output "Failed to download Arduino CLI" Exit } try { Expand-Archive -Path $arduinoCLIZip -DestinationPath $arduinoCLIDirectory -Force } catch { Write-Output "Failed to extract Arduino CLI" } } else { Write-Output "`r`nArduino CLI already downloaded, ensuring it is up to date and you have a board connected" } <############################################ Make sure Arduino CLI core index updated and list of boards populated ############################################> # Need to do an initial board list to download everything first try { & $arduinoCLI core update-index | Out-Null } catch { Write-Output "Failed to update Arduino CLI core index" Exit } # Need to do an initial board list to download everything first try { & $arduinoCLI board list | Out-Null } catch { Write-Output "Failed to update Arduino CLI board list" Exit } <############################################ Identify available board(s) ############################################> try { $boardList = & $arduinoCLI board list --format jsonmini | ConvertFrom-Json } catch { Write-Output "Failed to obtain list of boards" Exit } <############################################ Get user to select board ############################################> if ($boardList.count -eq 0) { Write-Output "Could not find any attached devices, please ensure your device is plugged in to a USB port and Windows recognises it" Exit } else { @" Devices attached to COM ports: ------------------------------ "@ $boardSelect = 1 foreach ($board in $boardList) { if ($board.matching_boards.name) { $boardName = $board.matching_boards.name } else { $boardName = "Unknown device" } $port = $board.port.address Write-Output "$boardSelect - $boardName on port $port" $boardSelect++ } Write-Output "$boardSelect - Exit" $userSelection = 0 do { [int]$userSelection = Read-Host "`r`nSelect the device to use from the list above" } until ( (($userSelection -ge 1) -and ($userSelection -le ($boardList.count + 1))) ) if ($userSelection -eq ($boardList.count + 1)) { Write-Output "Exiting installer" Exit } else { $selectedBoard = $userSelection - 1 } } <############################################ If the board is unknown, need to choose which one ############################################> if ($null -eq $boardList[$selectedBoard].matching_boards.name) { Write-Output "The device selected is unknown, these boards are supported:`r`n" $deviceSelect = 1 foreach ($device in $supportedDevices) { Write-Output "$deviceSelect - $($supportedDevices[$deviceSelect - 1].name)" $deviceSelect++ } Write-Output "$deviceSelect - Exit" $userSelection = 0 do { [int]$userSelection = Read-Host "Select the board type from the list above" } until ( (($userSelection -ge 1) -and ($userSelection -le ($supportedDevices.count + 1))) ) if ($userSelection -eq ($supportedDevices.count + 1)) { Write-Output "Exiting installer" Exit } else { $deviceName = $supportedDevices[$userSelection - 1].name $deviceFQBN = $supportedDevices[$userSelection - 1].fqbn $devicePort = $boardList[$selectedBoard].port.address } } else { $deviceName = $boardList[$selectedBoard].matching_boards.name $deviceFQBN = $boardList[$selectedBoard].matching_boards.fqbn $devicePort = $boardList[$selectedBoard].port.address } <############################################ Get the list of tags ############################################> try { $gitHubTags = Invoke-RestMethod -Uri $gitHubAPITags } catch { Write-Output "Failed to obtain list of available EX-CommandStation versions" Exit } <############################################ Get our GitHub tag list in a hash so we can sort by version numbers and extract just the ones we want ############################################> $versionMatch = ".*?v(\d+)\.(\d+).(\d+)-(.*)" $tagList = @{} foreach ($tag in $gitHubTags) { $tagHash = @{} $tagHash["Ref"] = $tag.ref $version = $tag.ref.split("/")[2] $null = $version -match $versionMatch $tagHash["Major"] = [int]$Matches[1] $tagHash["Minor"] = [int]$Matches[2] $tagHash["Patch"] = [int]$Matches[3] $tagHash["Type"] = $Matches[4] $tagList.Add($version, $tagHash) } <############################################ Get latest two Prod and Devel for user to select ############################################> $userList = @{} $prodCount = 1 $devCount = 1 $select = 1 foreach ($tag in $tagList.Keys | Sort-Object {$tagList[$_]["Major"]},{$tagList[$_]["Minor"]},{$tagList[$_]["Patch"]} -Descending) { if (($tagList[$tag]["Type"] -eq "Prod") -and $prodCount -le 2) { $userList[$select] = $tag $select++ $prodCount++ } elseif (($tagList[$tag]["Type"] -eq "Devel") -and $devCount -le 2) { $userList[$select] = $tag $select++ $devCount++ } } <############################################ Display options for user to select and get the selection ############################################> @" Available EX-CommandStation versions: ------------------------------------- "@ foreach ($selection in $userList.Keys | Sort-Object $selection) { Write-Output "$selection - $($userList[$selection])" } Write-Output "5 - Exit" $userSelection = 0 do { [int]$userSelection = Read-Host "`r`nSelect the version to install from the list above (1 - 5)" } until ( (($userSelection -ge 1) -and ($userSelection -le 5)) ) if ($userSelection -eq 5) { Write-Output "Exiting installer" Exit } else { $downloadURL = $gitHubURLPrefix + $tagList[$userList[$userSelection]]["Ref"] + ".zip" } <############################################ Create build directory if it doesn't exist, or fail ############################################> if (!(Test-Path -PathType Container -Path $buildDirectory)) { try { New-Item -ItemType Directory -Path $buildDirectory | Out-Null } catch { Write-Output "Could not create build directory $buildDirectory" Exit } } <############################################ Download the chosen version to the build directory ############################################> $downladFile = $buildDirectory + "\CommandStation-EX.zip" Write-Output "Downloading and extracting $($userList[$userSelection])" try { Invoke-WebRequest -Uri $downloadURL -OutFile $downladFile } catch { Write-Output "Error downloading EX-CommandStation zip file" Exit } <############################################ If folder exists, bail out and tell user ############################################> if (Test-Path -PathType Container -Path "$buildDirectory\CommandStation-EX") { Write-Output "EX-CommandStation directory already exists, please ensure you have copied any user files then delete manually: $buildDirectory\CommandStation-EX" Exit } <############################################ Extract and rename to CommandStation-EX to allow building ############################################> try { Expand-Archive -Path $downladFile -DestinationPath $buildDirectory -Force } catch { Write-Output "Failed to extract EX-CommandStation zip file" Exit } $folderName = $buildDirectory + "\CommandStation-EX-" + ($userList[$userSelection] -replace "^v", "") try { Rename-Item -Path $folderName -NewName $commandStationDirectory } catch { Write-Output "Could not rename folder" Exit } <############################################ If config directory provided, copy files here ############################################> if ($PSBoundParameters.ContainsKey('configDirectory')) { if (Test-Path -PathType Container -Path $configDirectory) { foreach ($file in $configFiles) { if (Test-Path -PathType Leaf -Path "$configDirectory\$file") { Copy-Item -Path "$configDirectory\$file" -Destination "$commandStationDirectory\$file" } } } else { Write-Output "User provided configuration directory $configDirectory does not exist, skipping" } } else { <############################################ If no config directory provided, prompt for display option ############################################> Write-Output "`r`nIf you have an LCD or OLED display connected, you can configure it here`r`n" Write-Output "1 - I have no display, skip this step" $displaySelect = 2 foreach ($display in $displayList) { Write-Output "$displaySelect - $($displayList[$displaySelect - 2].option)" $displaySelect++ } Write-Output "$($displayList.Count + 2) - Exit" do { [int]$displayChoice = Read-Host "`r`nSelect a display option" } until ( ($displayChoice -ge 1 -and $displayChoice -le ($displayList.Count + 2)) ) if ($displayChoice -eq ($displayList.Count + 2)) { Exit } elseif ($displayChoice -ge 2) { $configLines+= "// Display configuration" $configLines+= "$($displayList[$displayChoice - 2].configLine)" $configLines+= "#define SCROLLMODE 1 // Alternate between pages" } <############################################ If device supports WiFi, prompt to configure ############################################> if ($wifiBoards.Contains($deviceFQBN)) { Write-Output "`r`nYour chosen board supports WiFi`r`n" Write-Output "1 - I don't want WiFi, skip this step 2 - Configure my device as an access point I will connect to directly 3 - Configure my device to connect to my home WiFi network 4 - Exit" do { [int]$wifiChoice = Read-Host "`r`nSelect a WiFi option" } until ( ($wifiChoice -ge 1 -and $wifiChoice -le 4) ) if ($wifiChoice -eq 4) { Exit } elseif ($wifiChoice -ne 1) { $configLines+= "" $configLines+= "// WiFi configuration" $configLines+= "#define ENABLE_WIFI true" $configLines+= "#define IP_PORT 2560" $configLines+= "#define WIFI_HOSTNAME ""dccex""" $configLines+= "#define WIFI_CHANNEL 1" if ($wifiChoice -eq 2) { $configLines+= "#define WIFI_SSID ""Your network name""" $configLines+= "#define WIFI_PASSWORD ""Your network passwd""" } if ($wifiChoice -eq 3) { $wifiSSID = Read-Host "Please enter the SSID of your home network here" $wifiPassword = Read-Host "Please enter your home network WiFi password here" $configLines+= "#define WIFI_SSID ""$($wifiSSID)""" $configLines+= "#define WIFI_PASSWORD ""$($wifiPassword)""" } } } <############################################ Write out config.h to a file here only if config directory not provided ############################################> $configH = $commandStationDirectory + "\config.h" try { $configLines | Out-File -FilePath $configH -Encoding ascii } catch { Write-Output "Error writing config file to $configH" Exit } } <############################################ Install core libraries for the platform ############################################> $platformArray = $deviceFQBN.split(":") $platform = $platformArray[0] + ":" + $platformArray[1] try { & $arduinoCLI core install $platform } catch { Write-Output "Error install core libraries" Exit } <############################################ Upload the sketch to the selected board ############################################> #$arduinoCLI upload -b fqbn -p port $commandStationDirectory Write-Output "Compiling and uploading to $deviceName on $devicePort" try { $output = & $arduinoCLI compile -b $deviceFQBN -u -t -p $devicePort $commandStationDirectory --format jsonmini | ConvertFrom-Json } catch { Write-Output "Failed to compile" Exit } if ($output.success -eq "True") { Write-Output "`r`nCongratulations! DCC-EX EX-CommandStation $($userList[$userSelection]) has been installed on your $deviceName`r`n" } else { Write-Output "`r`nThere was an error installing $($userList[$userSelection]) on your $($deviceName), please take note of the errors provided:`r`n" if ($null -ne $output.compiler_err) { Write-Output "Compiler error: $($output.compiler_err)`r`n" } if ($null -ne $output.builder_result) { Write-Output "Builder result: $($output.builder_result)`r`n" } } Write-Output "`r`nPress any key to exit the installer" [void][System.Console]::ReadKey($true) ================================================ FILE: installer.sh ================================================ #!/bin/bash # # © 2022,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 . # # # Usage: mkdir DIRNAME ; cd DIRNAME ; ../installer.sh # or from install directory ./installer.sh # DCCEXGITURL="https://github.com/DCC-EX/CommandStation-EX" ACLIINSTALL="https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh" ACLI="./bin/arduino-cli" function need () { type -p $1 > /dev/null && return dpkg -l $1 2>&1 | egrep ^ii >/dev/null && return sudo apt-get install $1 type -p $1 > /dev/null && return echo "Could not install $1, abort" exit 255 } need git if cat /etc/issue | egrep '^Raspbian' 2>&1 >/dev/null ; then # we are on a raspi where we do not support graphical unset DISPLAY fi if [ x$DISPLAY != x ] ; then # we have DISPLAY, do the graphic thing need python3-tk need python3.8-venv mkdir -p ~/ex-installer/venv python3 -m venv ~/ex-installer/venv cd ~/ex-installer/venv || exit 255 source ./bin/activate git clone https://github.com/DCC-EX/EX-Installer cd EX-Installer || exit 255 pip3 install -r requirements.txt exec python3 -m ex_installer fi if test -d `basename "$DCCEXGITURL"` ; then : assume we are almost there cd `basename "$DCCEXGITURL"` || exit 255 fi if test -d .git ; then : assume we are right here git pull else git clone "$DCCEXGITURL" cd `basename "$DCCEXGITURL"` || exit 255 fi # prepare versions VERSIONS=/tmp/versions.$$ git tag --sort=v:refname | grep Prod | tail -1 > $VERSIONS echo master >> $VERSIONS git tag --sort=v:refname | grep Devel | tail -1 >> $VERSIONS echo devel >> $VERSIONS # ask user what version to use echo "What version to use? (give line number) If in doubt, use 1" cat -n $VERSIONS echo -n "> " LINE=`awk 'BEGIN {getline A < "/dev/tty"} ; A == NR {print}' $VERSIONS` git checkout $LINE if test -f config.h ; then : all well else # need to do this config better cp -p config.example.h config.h fi if test -x "$ACLI" ; then : all well else need curl curl "$ACLIINSTALL" > acliinstall.sh chmod +x acliinstall.sh ./acliinstall.sh fi $ACLI core update-index || exit 255 # Board discovery BOARDS=/tmp/boards.$$ $ACLI board list > /dev/null # download missing components $ACLI board list | grep serial > $BOARDS # real run if test -s $BOARDS ; then : all well else echo "$ACLI: No boards found" exit 255 fi if test x`< $BOARDS wc -l` = 'x1' ; then LINE=`cat $BOARDS` else # ask user echo "What board to use? (give line number)" cat -n $BOARDS echo -n "> " LINE=`awk 'BEGIN {getline A < "/dev/tty"} ; A == NR {print}' $BOARDS` fi rm $BOARDS PORT=`echo $LINE | cut -d" " -f1` echo Will use port: $PORT # FQBN discovery FQBN=`echo $LINE | egrep 'arduino:avr:[a-z][a-z]*' | sed 's/.*\(arduino:avr:[a-z][a-z]*\) .*/\1/1'` if test x$FQBN = x ; then # ask user cat > /tmp/fqbn.$$ < " FQBN=`awk 'BEGIN {getline A < "/dev/tty"} ; A == NR {print}' /tmp/fqbn.$$` fi rm /tmp/fqbn.$$ echo FQBN is $FQBN # Install phase $ACLI core install `echo $FQBN | sed 's,:[^:]*$,,1'` # remove last component to get package $ACLI board attach -p $PORT --fqbn $FQBN "$PWD" $ACLI compile --fqbn $FQBN "$PWD" $ACLI upload -v -t -p $PORT "$PWD" ================================================ FILE: libsha1.cpp ================================================ // For DCC-EX: This file downloaded from: // https://github.com/Links2004/arduinoWebSockets // All due credit to Steve Reid /* from valgrind tests */ /* ================ sha1.c ================ */ /* SHA-1 in C By Steve Reid 100% Public Domain Test Vectors (from FIPS PUB 180-1) "abc" A9993E36 4706816A BA3E2571 7850C26C 9CD0D89D "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq" 84983E44 1C3BD26E BAAE4AA1 F95129E5 E54670F1 A million repetitions of "a" 34AA973C D4C4DAA4 F61EEB2B DBAD2731 6534016F */ /* #define LITTLE_ENDIAN * This should be #define'd already, if true. */ /* #define SHA1HANDSOFF * Copies data before messing with it. */ // DCC-EX removed #if !defined(ESP8266) && !defined(ESP32) #define SHA1HANDSOFF #include #include #include #include "libsha1.h" #define rol(value, bits) (((value) << (bits)) | ((value) >> (32 - (bits)))) /* blk0() and blk() perform the initial expand. */ /* I got the idea of expanding during the round function from SSLeay */ #if BYTE_ORDER == LITTLE_ENDIAN #define blk0(i) (block->l[i] = (rol(block->l[i],24)&0xFF00FF00) \ |(rol(block->l[i],8)&0x00FF00FF)) #elif BYTE_ORDER == BIG_ENDIAN #define blk0(i) block->l[i] #else #error "Endianness not defined!" #endif #define blk(i) (block->l[i&15] = rol(block->l[(i+13)&15]^block->l[(i+8)&15] \ ^block->l[(i+2)&15]^block->l[i&15],1)) /* (R0+R1), R2, R3, R4 are the different operations used in SHA1 */ #define R0(v,w,x,y,z,i) z+=((w&(x^y))^y)+blk0(i)+0x5A827999+rol(v,5);w=rol(w,30); #define R1(v,w,x,y,z,i) z+=((w&(x^y))^y)+blk(i)+0x5A827999+rol(v,5);w=rol(w,30); #define R2(v,w,x,y,z,i) z+=(w^x^y)+blk(i)+0x6ED9EBA1+rol(v,5);w=rol(w,30); #define R3(v,w,x,y,z,i) z+=(((w|x)&y)|(w&x))+blk(i)+0x8F1BBCDC+rol(v,5);w=rol(w,30); #define R4(v,w,x,y,z,i) z+=(w^x^y)+blk(i)+0xCA62C1D6+rol(v,5);w=rol(w,30); /* Hash a single 512-bit block. This is the core of the algorithm. */ void SHA1Transform(uint32_t state[5], const unsigned char buffer[64]) { uint32_t a, b, c, d, e; typedef union { unsigned char c[64]; uint32_t l[16]; } CHAR64LONG16; #ifdef SHA1HANDSOFF CHAR64LONG16 block[1]; /* use array to appear as a pointer */ memcpy(block, buffer, 64); #else /* The following had better never be used because it causes the * pointer-to-const buffer to be cast into a pointer to non-const. * And the result is written through. I threw a "const" in, hoping * this will cause a diagnostic. */ CHAR64LONG16* block = (const CHAR64LONG16*)buffer; #endif /* Copy context->state[] to working vars */ a = state[0]; b = state[1]; c = state[2]; d = state[3]; e = state[4]; /* 4 rounds of 20 operations each. Loop unrolled. */ R0(a,b,c,d,e, 0); R0(e,a,b,c,d, 1); R0(d,e,a,b,c, 2); R0(c,d,e,a,b, 3); R0(b,c,d,e,a, 4); R0(a,b,c,d,e, 5); R0(e,a,b,c,d, 6); R0(d,e,a,b,c, 7); R0(c,d,e,a,b, 8); R0(b,c,d,e,a, 9); R0(a,b,c,d,e,10); R0(e,a,b,c,d,11); R0(d,e,a,b,c,12); R0(c,d,e,a,b,13); R0(b,c,d,e,a,14); R0(a,b,c,d,e,15); R1(e,a,b,c,d,16); R1(d,e,a,b,c,17); R1(c,d,e,a,b,18); R1(b,c,d,e,a,19); R2(a,b,c,d,e,20); R2(e,a,b,c,d,21); R2(d,e,a,b,c,22); R2(c,d,e,a,b,23); R2(b,c,d,e,a,24); R2(a,b,c,d,e,25); R2(e,a,b,c,d,26); R2(d,e,a,b,c,27); R2(c,d,e,a,b,28); R2(b,c,d,e,a,29); R2(a,b,c,d,e,30); R2(e,a,b,c,d,31); R2(d,e,a,b,c,32); R2(c,d,e,a,b,33); R2(b,c,d,e,a,34); R2(a,b,c,d,e,35); R2(e,a,b,c,d,36); R2(d,e,a,b,c,37); R2(c,d,e,a,b,38); R2(b,c,d,e,a,39); R3(a,b,c,d,e,40); R3(e,a,b,c,d,41); R3(d,e,a,b,c,42); R3(c,d,e,a,b,43); R3(b,c,d,e,a,44); R3(a,b,c,d,e,45); R3(e,a,b,c,d,46); R3(d,e,a,b,c,47); R3(c,d,e,a,b,48); R3(b,c,d,e,a,49); R3(a,b,c,d,e,50); R3(e,a,b,c,d,51); R3(d,e,a,b,c,52); R3(c,d,e,a,b,53); R3(b,c,d,e,a,54); R3(a,b,c,d,e,55); R3(e,a,b,c,d,56); R3(d,e,a,b,c,57); R3(c,d,e,a,b,58); R3(b,c,d,e,a,59); R4(a,b,c,d,e,60); R4(e,a,b,c,d,61); R4(d,e,a,b,c,62); R4(c,d,e,a,b,63); R4(b,c,d,e,a,64); R4(a,b,c,d,e,65); R4(e,a,b,c,d,66); R4(d,e,a,b,c,67); R4(c,d,e,a,b,68); R4(b,c,d,e,a,69); R4(a,b,c,d,e,70); R4(e,a,b,c,d,71); R4(d,e,a,b,c,72); R4(c,d,e,a,b,73); R4(b,c,d,e,a,74); R4(a,b,c,d,e,75); R4(e,a,b,c,d,76); R4(d,e,a,b,c,77); R4(c,d,e,a,b,78); R4(b,c,d,e,a,79); /* Add the working vars back into context.state[] */ state[0] += a; state[1] += b; state[2] += c; state[3] += d; state[4] += e; /* Wipe variables */ a = b = c = d = e = 0; #ifdef SHA1HANDSOFF memset(block, '\0', sizeof(block)); #endif } /* SHA1Init - Initialize new context */ void SHA1Init(SHA1_CTX* context) { /* SHA1 initialization constants */ context->state[0] = 0x67452301; context->state[1] = 0xEFCDAB89; context->state[2] = 0x98BADCFE; context->state[3] = 0x10325476; context->state[4] = 0xC3D2E1F0; context->count[0] = context->count[1] = 0; } /* Run your data through this. */ void SHA1Update(SHA1_CTX* context, const unsigned char* data, uint32_t len) { uint32_t i, j; j = context->count[0]; if ((context->count[0] += len << 3) < j) context->count[1]++; context->count[1] += (len>>29); j = (j >> 3) & 63; if ((j + len) > 63) { memcpy(&context->buffer[j], data, (i = 64-j)); SHA1Transform(context->state, context->buffer); for ( ; i + 63 < len; i += 64) { SHA1Transform(context->state, &data[i]); } j = 0; } else i = 0; memcpy(&context->buffer[j], &data[i], len - i); } /* Add padding and return the message digest. */ void SHA1Final(unsigned char digest[20], SHA1_CTX* context) { unsigned i; unsigned char finalcount[8]; unsigned char c; #if 0 /* untested "improvement" by DHR */ /* Convert context->count to a sequence of bytes * in finalcount. Second element first, but * big-endian order within element. * But we do it all backwards. */ unsigned char *fcp = &finalcount[8]; for (i = 0; i < 2; i++) { uint32_t t = context->count[i]; int j; for (j = 0; j < 4; t >>= 8, j++) *--fcp = (unsigned char) t; } #else for (i = 0; i < 8; i++) { finalcount[i] = (unsigned char)((context->count[(i >= 4 ? 0 : 1)] >> ((3-(i & 3)) * 8) ) & 255); /* Endian independent */ } #endif c = 0200; SHA1Update(context, &c, 1); while ((context->count[0] & 504) != 448) { c = 0000; SHA1Update(context, &c, 1); } SHA1Update(context, finalcount, 8); /* Should cause a SHA1Transform() */ for (i = 0; i < 20; i++) { digest[i] = (unsigned char) ((context->state[i>>2] >> ((3-(i & 3)) * 8) ) & 255); } /* Wipe variables */ memset(context, '\0', sizeof(*context)); memset(&finalcount, '\0', sizeof(finalcount)); } /* ================ end of sha1.c ================ */ // DCC-EX Removed: #endif ================================================ FILE: libsha1.h ================================================ // For DCC-EX: This file downloaded from: // https://github.com/Links2004/arduinoWebSockets // All due credit to Steve Reid /* ================ sha1.h ================ */ /* SHA-1 in C By Steve Reid 100% Public Domain */ // DCC-EX REMOVED #if !defined(ESP8266) && !defined(ESP32) #ifndef libsha1_h #define libsha1_h typedef struct { uint32_t state[5]; uint32_t count[2]; unsigned char buffer[64]; } SHA1_CTX; void SHA1Transform(uint32_t state[5], const unsigned char buffer[64]); void SHA1Init(SHA1_CTX* context); void SHA1Update(SHA1_CTX* context, const unsigned char* data, uint32_t len); void SHA1Final(unsigned char digest[20], SHA1_CTX* context); #endif ================================================ FILE: myAutomation.example.h ================================================ /* This is an automation example file. * The presence of a file called "myAutomation.h" brings EX-RAIL code into * the command station. * The automation may have multiple concurrent tasks. * A task may * - Act as a ROUTE setup macro for a user to drive over * - drive a loco through an AUTOMATION * - automate some cosmetic part of the layout without any loco. * * At startup, a single task is created to execute the startup sequence. * This task may simply follow a route, or may START * further tasks (that is.. send a loco out along a route). * * Where the loco id is not known at compile time, a new task * can be created with the command: * * * A ROUTE, AUTOMATION or SEQUENCE are internally identical in ExRail terms * but are just represented differently to a Withrottle user: * ROUTE(n,"name") - as Route_n .. to setup a route through a layout * AUTOMATION(n,"name") as Auto_n .. to send the current loco off along an automated journey * SEQUENCE(n) is not visible to Withrottle. * */ // This is the startup sequence, AUTOSTART POWERON // turn on track power SENDLOCO(3,1) // send loco 3 off along route 1 SENDLOCO(10,2) // send loco 10 off along route 2 DONE // This just ends the startup thread, leaving 2 others running. /* SEQUENCE(1) is a simple shuttle between 2 sensors * S20 and S21 are sensors on arduino pins 20 and 21 * S20 S21 * === START->================ */ SEQUENCE(1) DELAY(10000) // wait 10 seconds FON(3) // Set Loco Function 3, Horn on DELAY(1000) // wait 1 second FOFF(3) // Horn off FWD(80) // Move forward at speed 80 AT(21) // until we hit sensor id 21 STOP // then stop DELAY(5000) // Wait 5 seconds FON(2) // ring bell REV(60) // reverse at speed 60 AT(20) // until we get to S20 STOP // then stop FOFF(2) // Bell off FOLLOW(1) // and follow sequence 1 again /* SEQUENCE(2) is an automation example for a single loco Y shaped journey * S31,S32,S33 are sensors, T4 is a turnout * * S33 T4 S31 * ===-START->============================================= * // * S32 // * ======================// * * Train runs from START to S31, back to S32, again to S31, Back to start. */ SEQUENCE(2) FWD(60) // go forward at DCC speed 60 AT(31) STOP // when we get to sensor 31 DELAY(10000) // wait 10 seconds THROW(4) // throw turnout for route to S32 REV(45) // go backwards at speed 45 AT(32) STOP // until we arrive at sensor 32 DELAY(5000) // wait 5 seconds FWD(50) // go forwards at speed 50 AT(31) STOP // and stop at sensor 31 DELAY(5000) // wait 5 seconds CLOSE(4) // set turnout closed REV(50) // reverse back to S3 AT(33) STOP DELAY(20000) // wait 20 seconds FOLLOW(2) // follow sequence 2... ie repeat the process ================================================ FILE: myEX-Turntable.example.h ================================================ /************************************************************************************************** * This is an example automation file to control EX-Turntable using recommended techniques. ************************************************************************************************** * INSTRUCTIONS ************************************************************************************************** * To use this example file as the starting point for your layout, there are two options: * * 1. If you don't have an existing "myAutomation.h" file, simply rename "myEX-Turntable.example.h" to * "myAutomation.h". * 2. If you have an existing "myAutomation.h" file, rename "myEX-Turntable.example.h" to "myEX-Turntable.h", * and then include it by adding the line below at the end of your existing "myAutomation.h", on a * line of its own: * * #include "myEX-Turntable.h" * * Note that there are further instructions in the documentation at https://dcc-ex.com/. *************************************************************************************************/ /************************************************************************************************** * The MOVETT() command below will automatically move your turntable to the defined step position on * start up. * * If you do not wish this to occur, simply comment the line out. * * NOTE: If you are including this file at the end of an existing "myAutomation.h" file, you will likely * need to move this line to the beginning of your existing "myAutomation.h" file in order for it to * be effective. *************************************************************************************************/ MOVETT(600, 114, Turn) DONE // For Conductor level users who wish to just use EX-Turntable, you don't need to understand this // and can move to defining the turntable positions below. You must, however, ensure this remains // before any position definitions or you will get compile errors when uploading. // // Definition of the EX_TURNTABLE macro to correctly create the ROUTEs required for each position. // This includes RESERVE()/FREE() to protect any automation activities. // #define EX_TURNTABLE(route_id, reserve_id, vpin, steps, activity, desc) \ ROUTE(route_id, desc) \ RESERVE(reserve_id) \ MOVETT(vpin, steps, activity) \ WAITFOR(vpin) \ FREE(reserve_id) \ DONE /************************************************************************************************** * TURNTABLE POSITION DEFINITIONS *************************************************************************************************/ // EX_TURNTABLE(route_id, reserve_id, vpin, steps, activity, desc) // // route_id = A unique number for each defined route, the route is what appears in throttles // reserve_id = A unique reservation number (0 - 255) to ensure nothing interferes with automation // vpin = The Vpin defined for the Turntable-EX device driver, default is 600 // steps = The target step position // activity = The activity performed for this ROUTE (Note do not enclose in quotes "") // desc = Description that will appear in throttles (Must use quotes "") // EX_TURNTABLE(TTRoute1, Turntable, 600, 114, Turn, "Position 1") EX_TURNTABLE(TTRoute2, Turntable, 600, 227, Turn, "Position 2") EX_TURNTABLE(TTRoute3, Turntable, 600, 341, Turn, "Position 3") EX_TURNTABLE(TTRoute4, Turntable, 600, 2159, Turn, "Position 4") EX_TURNTABLE(TTRoute5, Turntable, 600, 2273, Turn, "Position 5") EX_TURNTABLE(TTRoute6, Turntable, 600, 2386, Turn, "Position 6") EX_TURNTABLE(TTRoute7, Turntable, 600, 0, Home, "Home turntable") // Pre-defined aliases to ensure unique IDs are used. // Turntable reserve ID, valid is 0 - 255 ALIAS(Turntable, 255) // Turntable ROUTE ID reservations, using for uniqueness: ALIAS(TTRoute1) ALIAS(TTRoute2) ALIAS(TTRoute3) ALIAS(TTRoute4) ALIAS(TTRoute5) ALIAS(TTRoute6) ALIAS(TTRoute7) ALIAS(TTRoute8) ALIAS(TTRoute9) ALIAS(TTRoute10) ALIAS(TTRoute11) ALIAS(TTRoute12) ALIAS(TTRoute13) ALIAS(TTRoute14) ALIAS(TTRoute15) ALIAS(TTRoute16) ALIAS(TTRoute17) ALIAS(TTRoute18) ALIAS(TTRoute19) ALIAS(TTRoute20) ALIAS(TTRoute21) ALIAS(TTRoute22) ALIAS(TTRoute23) ALIAS(TTRoute24) ALIAS(TTRoute25) ALIAS(TTRoute26) ALIAS(TTRoute27) ALIAS(TTRoute28) ALIAS(TTRoute29) ALIAS(TTRoute30) ================================================ FILE: myHal.cpp.txt ================================================ #include "defines.h" #include "IODevice.h" #ifndef IO_NO_HAL #include "IO_VL53L0X.h" #include "IO_HCSR04.h" #include "Sensors.h" #include "Turnouts.h" #include "IO_DFPlayer.h" //#include "IO_Wire.h" #include "IO_AnalogueInputs.h" #if __has_include("IO_Servo.h") #include "IO_Servo.h" #include "IO_PCA9685pwm.h" #endif #include "IO_HALDisplay.h" #include "LiquidCrystal_I2C.h" #if __has_include("IO_CMRI.h") #include "IO_CMRI.h" #endif //#include "IO_ExampleSerial.h" //#include "IO_EXFastclock.h" //#include "IO_EXTurntable.h" #if __has_include("IO_ExternalEEPROM.h") #include "IO_ExternalEEPROM.h" #endif #if __has_include("IO_Network.h") #include "IO_Network.h" #include "Net_RF24.h" #include "Net_ENC28J60.h" #include "Net_Ethernet.h" #define NETWORK_PRESENT #endif #include "IO_TouchKeypad.h" #define WIRE_TEST 0 #define TESTHARNESS 1 #define I2C_STRESS_TEST 0 #define I2C_SETCLOCK 0 #include "DCC.h" #if 0 // Long Strings #define s10 "0123456789" #define s100 s10 s10 s10 s10 s10 s10 s10 s10 s10 s10 #define s1k s100 s100 s100 s100 s100 s100 s100 s100 s100 s100 #define s10k s1k s1k s1k s1k s1k s1k s1k s1k s1k s1k #define s32k s10k s10k s10k s1k s1k volatile const char PROGMEM ss1[] = s32k; #endif #if TESTHARNESS // Function to be invoked by test harness void myTest() { // DIAG(F("VL53L0X #1 Test: dist=%d signal=%d ambient=%d value=%d"), // IODevice::readAnalogue(5000), // IODevice::readAnalogue(5001), // IODevice::readAnalogue(5002), // IODevice::read(5000)); // DIAG(F("VL53L0X #2 Test: dist=%d signal=%d ambient=%d value=%d"), // IODevice::readAnalogue(5003), // IODevice::readAnalogue(5004), // IODevice::readAnalogue(5005), // IODevice::read(5003)); // DIAG(F("HCSR04 Test: dist=%d value=%d"), // IODevice::readAnalogue(2000), // IODevice::read(2000)); // DIAG(F("ADS111x Test: %d %d %d %d %d"), // IODevice::readAnalogue(4500), // IODevice::readAnalogue(4501), // IODevice::readAnalogue(4502), // IODevice::readAnalogue(4503), // IODevice::readAnalogue(A5) // ); // DIAG(F("RF24 Test: 4000:%d 4002:%d"), // IODevice::read(4000), // IODevice::read(4002) // ); DIAG(F("EXPANDER: 2212:%d 2213:%d 2214:%d"), IODevice::readAnalogue(2212), IODevice::readAnalogue(2213), IODevice::readAnalogue(2214)); } #endif #if I2C_STRESS_TEST static bool initialised = false; static uint8_t lastStatus = 0; static const int nRBs = 3; // request blocks concurrently static const int I2cTestPeriod = 1; // milliseconds static I2CAddress testDevice = {SubBus_6, 0x27}; static I2CRB rb[nRBs]; static uint8_t readBuffer[nRBs*32]; // nRB x 32-byte input buffer static uint8_t writeBuffer[nRBs]; // nRB x 1-byte output buffer static unsigned long count = 0; static unsigned long errors = 0; static unsigned long lastOutput = millis(); void I2CTest() { if (!initialised) { // I2C Loading for stress test. // Write value then read back 32 times for (int i=0; i 60000) { // 1 minute DIAG(F("I2CTest: Count=%l Errors=%l"), count, errors); count = errors = 0; lastOutput = millis(); } } #endif void updateLocoScreen() { for (int i=0; i<8; i++) { if (DCC::speedTable[i].loco > 0) { int speed = DCC::speedTable[i].speedCode; char direction = (speed & 0x80) ? 'R' : 'F'; speed = speed & 0x7f; if (speed > 0) speed = speed - 1; SCREEN(3, i, F("Loco:%4d %3d %c"), DCC::speedTable[i].loco, speed, direction); } } } void updateTime() { uint8_t buffer[20]; I2CAddress rtc = {SubBus_1, 0x68}; // Real-time clock I2C address buffer[0] = 0; // Set time - only needs to be done once if battery is ok. static bool timeSet = false; if (!timeSet) { // I2CManager.read(rtc, buffer+1, sizeof(buffer)-1); // uint8_t year = 23; // 2023 // uint8_t day = 2; // tuesday // uint8_t date = 21; // 21st // uint8_t month = 2; // feb // uint8_t hours = 23; // xx: // uint8_t minutes = 25; // :xx // buffer[1] = 0; // seconds // buffer[2] = ((minutes / 10) << 4) | (minutes % 10); // buffer[3] = ((hours / 10) << 4) | (hours % 10); // buffer[4] = day; // buffer[5] = ((date/10) << 4) + date%10; // 24th // buffer[6] = ((month/10) << 4) + month%10; // feb // buffer[7] = ((year/10) << 4) + year%10; // xx23 // for (uint8_t i=8; i> 4; uint8_t seconds1 = buffer[1] & 0xf; uint8_t minutes10 = buffer[2] >> 4; uint8_t minutes1 = buffer[2] & 0xf; uint8_t hours10 = buffer[3] >> 4; uint8_t hours1 = buffer[3] & 0xf; SCREEN(10, 0, F("Departures %d%d:%d%d:%d%d"), hours10, hours1, minutes10, minutes1, seconds10, seconds1); } } void showCharacterSet() { if (millis() < 3000) return; const uint8_t lineLen = 20; char buffer[lineLen+1]; static uint8_t nextChar = 0x20; for (uint8_t row=0; row<8; row+=1) { for (uint8_t col=0; col::create(10, {SubBus_5, 0x3c}, 132, 64); // SH1106 // UserAddin::create(updateLocoScreen, 1000); // UserAddin::create(showCharacterSet, 5000); // UserAddin::create(updateTime, 1000); HALDisplay::create(10, {SubBus_4, 0x3c}, 128, 32); HALDisplay::create(10, {SubBus_7, 0x3c}, 128, 32); //HALDisplay::create(10, {SubBus_4, 0x27}, 20, 4); // Draw double boxes with X O O X inside. // SCREEN(3, 2, F("\xc9\xcd\xcd\xcd\xcb\xcd\xcd\xcd\xcb\xcd\xcd\xcd\xcb\xcd\xcd\xcd\xcb\xcd\xcd\xcd\xbb")); // SCREEN(3, 3, F("\xba X \xba O \xba O \xba O \xba X \xba")); // SCREEN(3, 4, F("\xcc\xcd\xcd\xcd\xce\xcd\xcd\xcd\xce\xcd\xcd\xcd\xce\xcd\xcd\xcd\xce\xcd\xcd\xcd\xb9")); // SCREEN(3, 5, F("\xba X \xba O \xba O \xba O \xba X \xba")); // SCREEN(3, 6, F("\xc8\xcd\xcd\xcd\xca\xcd\xcd\xcd\xca\xcd\xcd\xcd\xca\xcd\xcd\xcd\xca\xcd\xcd\xcd\xbc")); // Draw single boxes with X O O X inside. // SCREEN(3, 0, F("Summary Data:")); // SCREEN(3, 1, F("\xda\xc4\xc4\xc4\xc2\xc4\xc4\xc4\xc2\xc4\xc4\xc4\xc2\xc4\xc4\xc4\xc2\xc4\xc4\xc4\xbf")); // SCREEN(3, 2, F("\xb3 X \xb3 O \xb3 O \xb3 O \xb3 X \xb3")); // SCREEN(3, 3, F("\xc3\xc4\xc4\xc4\xc5\xc4\xc4\xc4\xc5\xc4\xc4\xc4\xc5\xc4\xc4\xc4\xc5\xc4\xc4\xc4\xb4")); // SCREEN(3, 4, F("\xb3 X \xb3 O \xb3 O \xb3 O \xb3 X \xb3")); // SCREEN(3, 5, F("\xc3\xc4\xc4\xc4\xc5\xc4\xc4\xc4\xc5\xc4\xc4\xc4\xc5\xc4\xc4\xc4\xc5\xc4\xc4\xc4\xb4")); // SCREEN(3, 6, F("\xb3 X \xb3 O \xb3 O \xb3 O \xb3 X \xb3")); // SCREEN(3, 7, F("\xc0\xc4\xc4\xc4\xc1\xc4\xc4\xc4\xc1\xc4\xc4\xc4\xc1\xc4\xc4\xc4\xc1\xc4\xc4\xc4\xd9")); // Blocks of different greyness // SCREEN(3, 0, F("\xb0\xb0\xb0\xb0\xb1\xb1\xb1\xb1\xb2\xb2\xb2\xb2\xdb\xdb\xdb\xdb")); // SCREEN(3, 1, F("\xb0\xb0\xb0\xb0\xb1\xb1\xb1\xb1\xb2\xb2\xb2\xb2\xdb\xdb\xdb\xdb")); // SCREEN(3, 2, F("\xb0\xb0\xb0\xb0\xb1\xb1\xb1\xb1\xb2\xb2\xb2\xb2\xdb\xdb\xdb\xdb")); // DCCEX logo // SCREEN(3, 1, F("\xb0\xb0\x20\x20\x20\xb0\x20\x20\x20\xb0\x20\x20\x20\x20\xb0\xb0\xb0\x20\xb0\x20\xb0")); // SCREEN(3, 2, F("\xb0\x20\xb0\x20\xb0\x20\xb0\x20\xb0\x20\xb0\x20\x20\x20\xb0\x20\x20\x20\xb0\x20\xb0")); // SCREEN(3, 3, F("\xb0\x20\xb0\x20\xb0\x20\x20\x20\xb0\x20\x20\x20\xb0\x20\xb0\xb0\x20\x20\x20\xb0\x20")); // SCREEN(3, 4, F("\xb0\x20\xb0\x20\xb0\x20\xb0\x20\xb0\x20\xb0\x20\x20\x20\xb0\x20\x20\x20\xb0\x20\xb0")); // SCREEN(3, 5, F("\xb0\xb0\x20\x20\x20\xb0\x20\x20\x20\xb0\x20\x20\x20\x20\xb0\xb0\xb0\x20\xb0\x20\xb0")); // SCREEN(3, 7, F("\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1\xb1")); #if 0 // List versions of devices that respond to the version request for (uint8_t address = 8; address<0x78; address++) { uint8_t buffer[3]; uint8_t status = I2CManager.read(0x7c, buffer, sizeof(buffer), 1, address); if (status == I2C_STATUS_OK) { uint16_t manufacturer = ((uint16_t)buffer[0] << 4 ) | (buffer[1] >> 4); uint16_t deviceID = ((uint16_t)(buffer[1] & 0x0f) << 5) | (buffer[2] >> 3); uint16_t dieRevision = buffer[2] & 0x1f; DIAG(F("Addr %s version: %x %x %x"), address.toString(), manufacturer, deviceID, dieRevision); } } #endif #if I2C_STRESS_TEST UserAddin::create(I2CTest, I2cTestPeriod); #endif #if WIRE_TEST // Test of Wire-I2CManager interface Wire.begin(); Wire.setClock(400000); Wire.beginTransmission(0x23); Wire.print("Hello"); uint8_t status = Wire.endTransmission(); if (status==0) DIAG(F("Wire: device Found on 0x23")); Wire.beginTransmission(0x23); Wire.write(0xde); Wire.endTransmission(false); // don't send stop Wire.requestFrom(0x23, 1); if (Wire.available()) { DIAG(F("Wire: value=x%x"), Wire.read()); } uint8_t st = I2CManager.write(0x33, 0, 0); DIAG(F("I2CManager 0x33 st=%d \"%S\""), st, I2CManager.getErrorMessage(st)); #endif #if I2C_SETCLOCK // Test I2C clock changes // Set up two I2C request blocks I2CRB rb1, rb2; uint8_t readBuff[32]; rb1.setRequestParams(0x23, readBuff, sizeof(readBuff), readBuff, sizeof(readBuff)); rb2.setRequestParams(0x23, readBuff, sizeof(readBuff), readBuff, sizeof(readBuff)); // First set clock to 400kHz and then issue requests I2CManager.forceClock(400000); I2CManager.queueRequest(&rb1); I2CManager.queueRequest(&rb2); // Wait a little to allow the first transaction to start delayMicroseconds(2); // ... then request a clock speed change I2CManager.forceClock(100000); DIAG(F("I2CClock: rb1 status=%d"), rb1.wait()); DIAG(F("I2CClock: rb2 status=%d"), rb2.wait()); // Reset clock speed I2CManager.forceClock(400000); #endif EXIOExpander::create(2200, 18, {SubBus_0, 0x65}); //UserAddin::create(myTest, 1000); // ServoTurnout::create(2200, 2200, 400, 200, 0); // ServoTurnout::create(2200, 2200, 400, 200, 0); TouchKeypad::create(2300, 16, 25, 24); // GPIO PCF8574::create(800, 8, {SubBus_1, 0x23}); //PCF8574::create(808, 8, {SubBus_2, 0x27}); PCF8574::create(65000, 8, 0x27); MCP23017::create(164,16,{SubBus_3, 0x20}); //MCP23017::create(180,16,{SubBus_0, 0x27}); Sensor::create(170, 170, 1); // Hall effect, enable pullup. Sensor::create(171, 171, 1); // PWM (LEDs and Servos) // For servos, use default 50Hz pulses. PCA9685::create(100, 16, {SubBus_1, 0x41}); // For LEDs, use 1kHz pulses. PCA9685::create(116, 16, {SubBus_1, 0x40}, 1000); // 4-pin Analogue Input Module //ADS111x::create(4500, 4, 0x48); // Laser Time-Of-Flight Sensors VL53L0X::create(5000, 3, {SubBus_0, 0x60}, 300, 310, 46); //VL53L0X::create(5003, 3, {SubBus_6, 0x61}, 300, 310, 47); Sensor::create(5000, 5000, 0); Sensor::create(5003, 5003, 0); // Monitor reset digital on first TOF //Sensor::create(46,46,0); // // External 24C256 EEPROM (256kBytes) on I2C address 0x50. // ExternalEEPROM::create({SubBus_0, 0x50}, 256); // Play up to 10 sounds on pins 10000-10009. Player is connected to Serial1 or Serial2. #if defined(HAVE_HWSERIAL1) && !defined(ARDUINO_ARCH_STM32) DFPlayer::create(10000, 14, Serial1); #elif defined(ARDUINO_ARCH_STM32) DFPlayer::create(10000, 10, Serial3); // Pins PC11 (RX) and PC10 (TX) #endif // Ultrasound echo device HCSR04::create(2000, 32, 33, 80, 85 /*, HCSR04::LOOP */); Sensor::create(2000, 2000, 0); #if __has_include("IO_CMRI.h") CMRIbus::create(0, Serial2, 115200, 50, 40); // 50ms cycle, pin 40 for DE/!RE pins CMRInode::create(25000, 72, 0, 0, 'M'); // SMINI address 0 for (int pin=0; pin<24; pin++) { Sensor::create(25000+pin, 25000+pin, 0); } #endif //CMRInode::create(25072, 72, 0, 13, 'M'); // SMINI address 13 //CMRInode::create(25144, 288, 0, 14, 'C', 144, 144); // CPNODE address 14 #ifdef NETWORK_PRESENT // Define remote pins to be used. The range of remote pins is like a common data area shared // between all nodes. // For outputs, a write to a remote VPIN causes a message to be sent to another node, which then performs // the write operation on the device VPIN that is local to that node. // For inputs, the state of remote input VPIN is read on the node where it is connected, and then // sent to other nodes in the system where the state is saved and processed. Updates are sent on change, and // also periodically if no changes. // // Each definition is a triple of remote node, remote pin, indexed by relative pin. Up to 224 rpins can // be configured (per node). This is to fit into a 32-byte packet. REMOTEPINS rpins[] = { {30,164,RPIN_IN} , //4000 Node 30, first MCP23017 pin, input {30,165,RPIN_IN}, //4001 Node 30, second MCP23017 pin, input {30,166,RPIN_OUT}, //4002 Node 30, third MCP23017 pin, output {30,166,RPIN_OUT}, //4003 Node 30, fourth MCP23017 pin, output {30,100,RPIN_INOUT}, //4004 Node 30, first PCA9685 servo pin {30,101,RPIN_INOUT}, //4005 Node 30, second PCA9685 servo pin {30,102,RPIN_INOUT}, //4006 Node 30, third PCA9685 servo pin {30,103,RPIN_INOUT}, //4007 Node 30, fourth PCA9685 servo pin {30,24,RPIN_IN}, //4008 Node 30, Arduino pin D24 {30,25,RPIN_IN}, //4009 Node 30, Arduino pin D25 {30,26,RPIN_IN}, //4010 Node 30, Arduino pin D26 {30,27,RPIN_IN}, //4011 Node 30, Arduino pin D27 {30,1000,RPIN_OUT}, //4012 Node 30, DFPlayer playing flag (when read) / Song selector (when written) {30,5000,RPIN_IN}, //4013 Node 30, VL53L0X detect pin {30,VPIN_NONE,0}, //4014 Node 30, spare {30,VPIN_NONE,0}, //4015 Node 30, spare {31,164,RPIN_IN} , //4016 Node 31, first MCP23017 pin, input {31,165,RPIN_IN}, //4017 Node 31, second MCP23017 pin, input {31,166,RPIN_OUT}, //4018 Node 31, third MCP23017 pin, output {31,166,RPIN_OUT}, //4019 Node 31, fourth MCP23017 pin, output {31,100,RPIN_INOUT}, //4020 Node 31, first PCA9685 servo pin {31,101,RPIN_INOUT}, //4021 Node 31, second PCA9685 servo pin {31,102,RPIN_INOUT}, //4022 Node 31, third PCA9685 servo pin {31,103,RPIN_INOUT}, //4023 Node 31, fourth PCA9685 servo pin {31,24,RPIN_IN}, //4024 Node 31, Arduino pin D24 {31,25,RPIN_IN}, //4025 Node 31, Arduino pin D25 {31,26,RPIN_IN}, //4026 Node 31, Arduino pin D26 {31,27,RPIN_IN}, //4027 Node 31, Arduino pin D27 {31,3,RPIN_IN}, //4028 Node 31, Arduino pin D3 {31,VPIN_NONE,0}, //4029 Node 31, spare {31,VPIN_NONE,0}, //4030 Node 31, spare {31,VPIN_NONE,0} //4031 Node 31, spare }; // FirstVPIN, nPins, thisNode, pinDefs, CEPin, CSNPin // Net_RF24 *rf24Driver = new Net_RF24(48, 49); // Network::create(4000, NUMREMOTEPINS(rpins), NODE, rpins, rf24Driver); #if NODE==30 //Net_ENC28J60 *encDriver = new Net_ENC28J60(49); //Network::create(4000, NUMREMOTEPINS(rpins), NODE, rpins, encDriver); #elif NODE==31 Net_ENC28J60 *encDriver = new Net_ENC28J60(53); Network::create(4000, NUMREMOTEPINS(rpins), NODE, rpins, encDriver); #else Net_Ethernet *etherDriver = new Net_Ethernet(); Network::create(4000, NUMREMOTEPINS(rpins), NODE, rpins, etherDriver); #endif for (int i=0; i<=32; i++) Sensor::create(4000+i, 4000+i, 0); #endif #ifdef ARDUINO_ARCH_STM32 //PCF8574::create(1900, 8, 0x27); Sensor::create(1900,100,1); Sensor::create(1901,101,1); #endif } #endif // IO_NO_HAL ================================================ FILE: myHal.cpp_example.txt ================================================ // Sample myHal.cpp file. // // To use this file, copy it to myHal.cpp and uncomment the directives and/or // edit them to satisfy your requirements. If you only want to use up to // two MCP23017 GPIO Expander modules and/or up to two PCA9685 Servo modules, // then you don't need this file as DCC++EX configures these for free! // Note that if the file has a .cpp extension it WILL be compiled into the build // and the halSetup() function WILL be invoked. // // To prevent this, temporarily rename the file to myHal.txt or similar. // // The #if directive prevent compile errors for Uno and Nano by excluding the // HAL directives from the build. #if !defined(IO_NO_HAL) // Include devices you need. #include "IODevice.h" //#include "IO_HALDisplay.h" // Auxiliary display devices (LCD/OLED) //#include "IO_HCSR04.h" // Ultrasonic range sensor //#include "IO_VL53L0X.h" // Laser time-of-flight sensor //#include "IO_DFPlayer.h" // MP3 sound player //#include "IO_TouchKeypad.h // Touch keypad with 16 keys //#include "IO_EXTurntable.h" // Turntable-EX turntable controller //#include "IO_EXFastClock.h" // FastClock driver //#include "IO_PCA9555.h" // 16-bit I/O expander (NXP & Texas Instruments). //#include "IO_I2CDFPlayer.h" // DFPlayer over I2C //========================================================================== // The function halSetup() is invoked from CS if it exists within the build. // The setup calls are included between the open and close braces "{ ... }". // Comments (lines preceded by "//") are optional. //========================================================================== void halSetup() { //======================================================================= // The following directives define auxiliary display devices. // These can be defined in addition to the system display (display // number 0) that is defined in config.h. // A write to a line which is beyond the length of the screen will overwrite // the bottom line, unless the line number is 255 in which case the // screen contents will scroll up before the text is written to the // bottom line. //======================================================================= // // Create a 128x32 OLED display device as display number 1 // (line 0 is written by EX-RAIL 'SCREEN(1, 0, "text")'). //HALDisplay::create(1, 0x3d, 128, 32); // Create a 20x4 LCD display device as display number 2 // (line 0 is written by EX-RAIL 'SCREEN(2, 0, "text")'). // HALDisplay::create(2, 0x27, 20, 4); //======================================================================= // User Add-ins //======================================================================= // User add-ins can be created when you want to do something that // can't be done in EX-RAIL but does not merit a HAL driver. The // user add-in is a C++ function that is executed periodically by the // HAL subsystem. // Example: The function will be executed once per second and will display, // on screen #3, the first eight entries (assuming an 8-line display) // from the loco speed table. // Put the following block of code in myHal.cpp OUTSIDE of the // halSetup() function: // // void updateLocoScreen() { // for (int i=0; i<8; i++) { // if (DCC::speedTable[i].loco > 0) { // int speed = DCC::speedTable[i].speedCode; // char direction = (speed & 0x80) ? 'R' : 'F'; // speed = speed & 0x7f; // if (speed > 0) speed = speed - 1; // SCREEN(3, i, F("Loco:%4d %3d %c"), DCC::speedTable[i].loco, // speed, direction); // } // } // } // // Put the following line INSIDE the halSetup() function: // // UserAddin::create(updateLocoScreen, 1000); // //======================================================================= // The following directive defines a PCA9685 PWM Servo driver module. //======================================================================= // The parameters are: // First Vpin=100 // Number of VPINs=16 (numbered 100-115) // I2C address of module=0x40 //PCA9685::create(100, 16, 0x40); //======================================================================= // The following directive defines an MCP23017 16-port I2C GPIO Extender module. //======================================================================= // The parameters are: // First Vpin=196 // Number of VPINs=16 (numbered 196-211) // I2C address of module=0x22 //MCP23017::create(196, 16, 0x22); // Alternative form, which allows the INT pin of the module to request a scan // by pulling Arduino pin 40 to ground. Means that the I2C isn't being polled // all the time, only when a change takes place. Multiple modules' INT pins // may be connected to the same Arduino pin. //MCP23017::create(196, 16, 0x22, 40); //======================================================================= // The following directive defines an MCP23008 8-port I2C GPIO Extender module. //======================================================================= // The parameters are: // First Vpin=300 // Number of VPINs=8 (numbered 300-307) // I2C address of module=0x22 //MCP23008::create(300, 8, 0x22); //======================================================================= // The following directive defines a PCF8574 8-port I2C GPIO Extender module. //======================================================================= // The parameters are: // First Vpin=200 // Number of VPINs=8 (numbered 200-207) // I2C address of module=0x23 //PCF8574::create(200, 8, 0x23); // Alternative form using INT pin (see above) //PCF8574::create(200, 8, 0x23, 40); // Alternative form to initialize 8 pins as output // INT pin -1, when INT is not used //PCF8574::create(200, 8, 0x23, -1, 255); 8 pins High //PCF8574::create(200, 8, 0x23, -1, 0); 8 pins Low //PCF8574::create(200, 8, 0x23, -1, 0b11000010); // pins listed sequentially from 7 to 0 //======================================================================= // The following directive defines a PCF8575 16-port I2C GPIO Extender module. //======================================================================= // The parameters are: // First Vpin=200 // Number of VPINs=16 (numbered 200-215) // I2C address of module=0x23 //PCF8575::create(200, 16, 0x23); // Alternative form using INT pin (see above) //PCF8575::create(200, 16, 0x23, 40); //======================================================================= // The following directive defines an HCSR04 ultrasonic ranging module. //======================================================================= // The parameters are: // Vpin=2000 (only one VPIN per directive) // Number of VPINs=1 // Arduino pin connected to TRIG=30 // Arduino pin connected to ECHO=31 // Minimum trigger range=20cm (VPIN goes to 1 when <20cm) // Maximum trigger range=25cm (VPIN goes to 0 when >25cm) // Note: Multiple devices can be configured by using a different ECHO pin // for each one. The TRIG pin can be shared between multiple devices. // Be aware that the 'ping' of one device may be received by another // device and position them accordingly! //HCSR04::create(2000, 30, 31, 20, 25); //HCSR04::create(2001, 30, 32, 20, 25); //======================================================================= // The following directive defines a single VL53L0X Time-of-Flight range sensor. //======================================================================= // The parameters are: // VPIN=5000 // Number of VPINs=1 // I2C address=0x29 (default for this chip) // Minimum trigger range=200mm (VPIN goes to 1 when <20cm) // Maximum trigger range=250mm (VPIN goes to 0 when >25cm) //VL53L0X::create(5000, 1, 0x29, 200, 250); // For multiple VL53L0X modules, add another parameter which is a VPIN connected to the // module's XSHUT pin. This allows the modules to be configured, at start, // with distinct I2C addresses. In this case, the address 0x29 is only used during // initialisation to configure each device in turn with the desired unique I2C address. // The examples below have the modules' XSHUT pins connected to the first two pins of // the first MCP23017 module (164 and 165), but Arduino pins may be used instead. // The first module here is given I2C address 0x30 and the second is 0x31. //VL53L0X::create(5000, 1, 0x30, 200, 250, 164); //VL53L0X::create(5001, 1, 0x31, 200, 250, 165); //======================================================================= // Play mp3 files from a Micro-SD card, using a DFPlayer MP3 Module. //======================================================================= // Parameters: // 10000 = first VPIN allocated. // 10 = number of VPINs allocated. // Serial1 = name of serial port (usually Serial1 or Serial2). // With these parameters, up to 10 files may be played on pins 10000-10009. // Play is started from EX-RAIL with SET(10000) for first mp3 file, SET(10001) // for second file, etc. Play may also be initiated by writing an analogue // value to the first pin, e.g. ANOUT(10000,23,0,0) will play the 23rd mp3 file. // ANOUT(10000,23,30,0) will do the same thing, as well as setting the volume to // 30 (maximum value). // Play is stopped by RESET(10000) (or any other allocated VPIN). // Volume may also be set by writing an analogue value to the second pin for the player, // e.g. ANOUT(10001,30,0,0) sets volume to maximum (30). // The EX-RAIL script may check for completion of play by calling WAITFOR(pin), which will only proceed to the // following line when the player is no longer busy. // E.g. // SEQUENCE(1) // AT(164) // Wait for sensor attached to pin 164 to activate // SET(10003) // Play fourth MP3 file // LCD(4, "Playing") // Display message on LCD/OLED // WAITFOR(10003) // Wait for playing to finish // LCD(4, "") // Clear LCD/OLED line // FOLLOW(1) // Go back to start // DFPlayer::create(10000, 10, Serial1); //======================================================================= // Play mp3 files from a Micro-SD card, using a DFPlayer MP3 Module on a SC16IS750/SC16IS752 I2C UART //======================================================================= // DFPlayer via NXP SC16IS752 I2C Dual UART. // I2C address range 0x48 - 0x57 // // Generic format: // I2CDFPlayer::create(1st vPin, vPins, I2C address, xtal); // Parameters: // 1st vPin : First virtual pin that EX-Rail can control to play a sound, use PLAYSOUND command (alias of ANOUT) // vPins : Total number of virtual pins allocated (1 vPin is supported currently) // 1st vPin for UART 0 // I2C Address : I2C address of the serial controller, in 0x format // xtal : 0 for 1.8432Mhz, 1 for 14.7456Mhz // // The vPin is also a pin that can be read with the WAITFOR(vPin) command indicating if the DFPlayer has finished playing a track // // I2CDFPlayer::create(10000, 1, 0x48, 1); // // Configuration example on a multiplexer // I2CDFPlayer::create(10000, 1, {I2CMux_0, SubBus_0, 0x48}, 1); //======================================================================= // 16-pad capacitative touch key pad based on TP229 IC. //======================================================================= // Parameters below: // 11000 = first VPIN allocated // 16 = number of VPINs allocated // 25 = local GPIO pin number for clock signal // 24 = local GPIO pin number for data signal // // Pressing the key pads numbered 1-16 cause each of the nominated digital VPINs // (11000-11015 in this case) to be activated. // TouchKeypad::create(11000, 16, 25, 24); //======================================================================= // The following directive defines an EX-Turntable turntable instance. //======================================================================= // EXTurntable::create(VPIN, Number of VPINs, I2C Address) // // The parameters are: // VPIN=600 // Number of VPINs=1 (Note there is no reason to change this) // I2C address=0x60 // // Note that the I2C address is defined in the EX-Turntable code, and 0x60 is the default. //EXTurntable::create(600, 1, 0x60); //======================================================================= // The following directive defines an EX-IOExpander instance. //======================================================================= // EXIOExpander::create(VPIN, Number of VPINs, I2C Address) // // The parameters are: // VPIN=an available Vpin // Number of VPINs=pin count (must match device in use as per documentation) // I2C address=an available I2C address (default 0x65) // // Note that the I2C address is defined in the EX-IOExpander code, and 0x65 is the default. // The example is for an Arduino Nano. //EXIOExpander::create(800, 18, 0x65); //======================================================================= // The following directive defines a rotary encoder instance. //======================================================================= // The parameters are: // firstVpin = First available Vpin to allocate // numPins= Number of Vpins to allocate, can be either 1 to 3 // i2cAddress = Available I2C address (default 0x67) //RotaryEncoder::create(firstVpin, numPins, i2cAddress); //RotaryEncoder::create(700, 1, 0x67); //RotaryEncoder::create(700, 2, 0x67); //RotaryEncoder::create(700, 3, 0x67); //======================================================================= // The following directive defines an EX-FastClock instance. //======================================================================= // EXFastCLock::create(I2C Address) // // The parameters are: // // I2C address=0x55 (decimal 85) // // Note that the I2C address is defined in the EX-FastClock code, and 0x55 is the default. // EXFastClock::create(0x55); } #endif ================================================ FILE: myTrackStatus.example.h ================================================ // ************* OLED JL Display Track mA Amperage **************** // // by Herb Morton [Ash] March 23, 2025 // Colin Murdoch [ColinM] // Inside your config.h file First edit OLED max char rows set to 17 // #define MAX_CHARACTER_ROWS 17 // myAutomation.h // Reporting power status and mA for each track on the LCD HAL(Bitmap,8236,1) // create flag 8236 AUTOSTART DELAY(5000) ROUTE("TRACKSTATUS"_hk, "Resume/Pause JL Display") IF(8236) RESET(8236) ROUTE_CAPTION("TRACKSTATUS"_hk, "Paused") ROUTE_INACTIVE("TRACKSTATUS"_hk) SCREEN(0, 8, "Track status paused") SCREEN(0, 9, "") SCREEN(0,10, "") // several blank lines as needed SCREEN(0,11, "") SCREEN(0,12, "") SCREEN(0,13, "") SCREEN(0,14, "") SCREEN(0,15, "") SCREEN(0,16, "") PRINT("to pause/resume: \n") DONE ENDIF SET(8236) ROUTE_CAPTION("TRACKSTATUS"_hk, "Running") ROUTE_ACTIVE("TRACKSTATUS"_hk) PRINT("Resume JL Display") FOLLOW("PAUSETRACKSTATUS"_hk) SEQUENCE("PAUSETRACKSTATUS"_hk) PARSE("") // screen 0 start on line 8 PRINT("to pause/resume: \n") DELAY(3000) IF(8236) FOLLOW("PAUSETRACKSTATUS"_hk) ENDIF DONE // ************ End OLED JL Display Track mA Amperage ************** // // Display motor shield after 10 seconds AUTOSTART DELAY(10000) STEALTH(StringFormatter::lcd(1, F("MS: %S"), DCC::getMotorShieldName());) DONE ================================================ FILE: objdump.bat ================================================ ECHO ON FOR /F "delims=" %%i IN ('dir %TMP%\CommandStation-EX.ino.elf /s /b /o-D') DO SET ELF=%%i SET DUMP=%TEMP%\OBJDUMP.txt echo Most recent subfolder: %ELF% >%DUMP% set PATH="C:\Program Files (x86)\Arduino\hardware\tools\avr\bin\";%PATH% avr-objdump --private=mem-usage %ELF% >>%DUMP% ECHO ++++++++++++++++++++++++++++++++++ >>%DUMP% avr-objdump -x -C %ELF% | find ".text" | sort /+25 /R >>%DUMP% ECHO ++++++++++++++++++++++++++++++++++ >>%DUMP% avr-objdump -x -C %ELF% | find ".data" | sort /+25 /R >>%DUMP% ECHO ++++++++++++++++++++++++++++++++++ >>%DUMP% avr-objdump -x -C %ELF% | find ".bss" | sort /+25 /R >>%DUMP% ECHO ++++++++++++++++++++++++++++++++++ >>%DUMP% avr-objdump -D -S %ELF% >>%DUMP% %DUMP% EXIT ================================================ FILE: objdump.sh ================================================ #!/bin/bash # Find avr-objdump that matches the installed arduino binary ARDUINOBIN=$(ls -l $(type -p arduino)| awk '{print $NF ; exit 0}') PATH=$(dirname "$ARDUINOBIN")/hardware/tools/avr/bin:$PATH LASTBUILD=$(ls -tr /tmp/arduino_build_*/*.ino.elf | tail -1) avr-objdump --private=mem-usage "$LASTBUILD" for segment in .text .data .bss ; do echo '++++++++++++++++++++++++++++++++++' avr-objdump -x -C "$LASTBUILD" | awk '$2 == "'$segment'" && $3 != 0 {print $3,$2} ; $4 == "'$segment'" && $5 != 0 { print $5,$6}' | sort -r done ================================================ FILE: platformio.ini ================================================ ; PlatformIO Project Configuration File ; ; Build options: build flags, source filter ; Upload options: custom upload port, speed and extra flags ; Library options: dependencies, extra library storages ; Advanced options: extra scripting ; ; Please visit documentation for the other options and examples ; https://docs.platformio.org/page/projectconf.html [platformio] default_envs = mega2560 ; uno ; nano ESP32 Nucleo-F411RE Nucleo-F446RE Nucleo-F429ZI src_dir = . include_dir = . [env] build_flags = -Wall -Wextra ; monitor_filters = time [env:samd21-dev-usb] platform = atmelsam board = sparkfun_samd21_dev_usb framework = arduino upload_protocol = sam-ba lib_deps = ${env.lib_deps} monitor_speed = 115200 monitor_echo = yes build_flags = -std=c++17 ${env.build_flags} [env:samd21-zero-usb] platform = atmelsam board = zeroUSB framework = arduino upload_protocol = sam-ba lib_deps = ${env.lib_deps} monitor_speed = 115200 monitor_echo = yes build_flags = -std=c++17 ${env.build_flags} [env:Arduino-M0] platform = atmelsam board = mzeroUSB framework = arduino lib_deps = ${env.lib_deps} monitor_speed = 115200 monitor_echo = yes build_flags = -std=c++17 ${env.build_flags} [env:mega2560-debug] platform = atmelavr board = megaatmega2560 framework = arduino lib_deps = ${env.lib_deps} arduino-libraries/Ethernet SPI monitor_speed = 115200 monitor_echo = yes build_flags = -DDIAG_IO=2 -DDIAG_LOOPTIMES ${env.build_flags} [env:mega2560-no-HAL] platform = atmelavr board = megaatmega2560 framework = arduino lib_deps = ${env.lib_deps} arduino-libraries/Ethernet SPI monitor_speed = 115200 monitor_echo = yes build_flags = -DIO_NO_HAL ${env.build_flags} [env:mega2560-I2C-wire] platform = atmelavr board = megaatmega2560 framework = arduino lib_deps = ${env.lib_deps} arduino-libraries/Ethernet SPI monitor_speed = 115200 monitor_echo = yes build_flags = -DI2C_USE_WIRE ${env.build_flags} [env:mega2560] platform = atmelavr board = megaatmega2560 framework = arduino lib_deps = ${env.lib_deps} arduino-libraries/Ethernet SPI lib_ignore = WiFi101 WiFi101_Generic WiFiEspAT WiFiMulti_Generic WiFiNINA_Generic monitor_speed = 115200 monitor_echo = yes build_flags = ${env.build_flags} [env:mega2560-eth] platform = atmelavr board = megaatmega2560 framework = arduino lib_deps = ${env.lib_deps} arduino-libraries/Ethernet SPI lib_ignore = WiFi101 WiFi101_Generic WiFiEspAT WiFiMulti_Generic WiFiNINA_Generic monitor_speed = 115200 monitor_echo = yes build_flags = ${env.build_flags} [env:mega328] platform = atmelavr board = uno framework = arduino lib_deps = ${env.lib_deps} arduino-libraries/Ethernet SPI monitor_speed = 115200 monitor_echo = yes build_flags= ${env.build_flags} [env:unowifiR2] platform = atmelmegaavr board = uno_wifi_rev2 framework = arduino lib_deps = ${env.lib_deps} arduino-libraries/Ethernet SPI monitor_speed = 115200 monitor_echo = yes build_flags = ${env.build_flags} "-DF_CPU=16000000L -DARDUINO=10813 -DARDUINO_AVR_UNO_WIFI_DEV_ED -DARDUINO_ARCH_AVR -DESP_CH_UART -DESP_CH_UART_BR=19200" [env:nanoevery] platform = atmelmegaavr board = nano_every framework = arduino lib_deps = ${env.lib_deps} arduino-libraries/Ethernet SPI monitor_speed = 115200 monitor_echo = yes upload_speed = 19200 build_flags = ${env.build_flags} [env:uno] platform = atmelavr board = uno framework = arduino lib_deps = ${env.lib_deps} monitor_speed = 115200 monitor_echo = yes build_flags = -mcall-prologues ${env.build_flags} [env:nano] platform = atmelavr board = nanoatmega328new board_upload.maximum_size = 32256 framework = arduino lib_deps = ${env.lib_deps} monitor_speed = 115200 monitor_echo = yes build_flags = -mcall-prologues ${env.build_flags} [env:ESP32] ; Lock version to 6.7.0 as that is ; Arduino v2.0.16 (based on IDF v4.4.7) ; which is the latest version based ; on IDF v4. We can not use IDF v5. platform = espressif32 @ 6.7.0 board = esp32dev framework = arduino lib_deps = ${env.lib_deps} build_flags = -std=c++17 ${env.build_flags} monitor_speed = 115200 monitor_echo = yes [env:Nucleo-F411RE] platform = ststm32 @ 19.0.0 board = nucleo_f411re framework = arduino lib_deps = ${env.lib_deps} build_flags = -std=c++17 -Os -g2 ${env.build_flags} monitor_speed = 115200 monitor_echo = yes [env:Nucleo-F446RE] platform = ststm32 @ 19.0.0 board = nucleo_f446re framework = arduino lib_deps = ${env.lib_deps} build_flags = -std=c++17 -Os -g2 ${env.build_flags} monitor_speed = 115200 monitor_echo = yes ; Experimental - no reason this should not work, but not ; tested as yet ; [env:Nucleo-F401RE] platform = ststm32 @ 19.0.0 board = nucleo_f401re framework = arduino lib_deps = ${env.lib_deps} build_flags = -std=c++17 -Os -g2 ${env.build_flags} monitor_speed = 115200 monitor_echo = yes ; Commented out by default as the F13ZH has variant files ; but NOT the nucleo_f413zh.json file which needs to be ; installed before you can let PlatformIO see this ; ; [env:Nucleo-F413ZH] ; platform = ststm32 @ 19.0.0 ; board = nucleo_f413zh ; framework = arduino ; lib_deps = ${env.lib_deps} ; build_flags = -std=c++17 -Os -g2 -Wunused-variable ; monitor_speed = 115200 ; monitor_echo = yes ; Commented out by default as the F446ZE needs variant files ; installed before you can let PlatformIO see this ; [env:Nucleo-F446ZE] platform = ststm32 @ 19.0.0 board = nucleo_f446ze framework = arduino lib_deps = ${env.lib_deps} build_flags = -std=c++17 -Os -g2 ${env.build_flags} monitor_speed = 115200 monitor_echo = yes ; Commented out by default as the F412ZG needs variant files ; installed before you can let PlatformIO see this ; ; [env:Nucleo-F412ZG] ; platform = ststm32 @ 19.0.0 ; board = nucleo_f412zg ; framework = arduino ; lib_deps = ${env.lib_deps} ; build_flags = -std=c++17 -Os -g2 -Wunused-variable ; monitor_speed = 115200 ; monitor_echo = yes ; upload_protocol = stlink ; Experimental - Ethernet beta test ; [env:Nucleo-F429ZI] platform = ststm32 @ 19.0.0 board = nucleo_f429zi framework = arduino lib_deps = ${env.lib_deps} stm32duino/STM32Ethernet @ ^1.4.0 ; for test only https://github.com/habazut/lwip#stm32 stm32duino/STM32duino LwIP @ ^2.1.3 lib_ignore = WiFi101 WiFi101_Generic WiFiEspAT WiFiMulti_Generic WiFiNINA_Generic build_flags = -std=c++17 -Os -g2 ${env.build_flags} -DCUSTOM_PERIPHERAL_PINS monitor_speed = 115200 monitor_echo = yes upload_protocol = stlink ; Experimental - Ethernet beta test ; [env:Nucleo-F439ZI] platform = ststm32 @ 19.0.0 board = nucleo_f439zi framework = arduino lib_deps = ${env.lib_deps} stm32duino/STM32Ethernet @ ^1.4.0 stm32duino/STM32duino LwIP @ ^2.1.3 lib_ignore = WiFi101 WiFi101_Generic WiFiEspAT WiFiMulti_Generic WiFiNINA_Generic build_flags = -std=c++17 -Os -g2 ${env.build_flags} -DCUSTOM_PERIPHERAL_PINS monitor_speed = 115200 monitor_echo = yes upload_protocol = stlink [env:Teensy3_2] platform = teensy board = teensy31 framework = arduino build_flags = -std=c++17 -Os -g2 ${env.build_flags} lib_deps = ${env.lib_deps} lib_ignore = NativeEthernet [env:Teensy3_5] platform = teensy board = teensy35 framework = arduino build_flags = -std=c++17 -Os -g2 ${env.build_flags} lib_deps = ${env.lib_deps} lib_ignore = NativeEthernet [env:Teensy3_6] platform = teensy board = teensy36 framework = arduino build_flags = -std=c++17 -Os -g2 ${env.build_flags} lib_deps = ${env.lib_deps} lib_ignore = NativeEthernet [env:Teensy4_0] platform = teensy board = teensy40 framework = arduino build_flags = -std=c++17 -Os -g2 ${env.build_flags} lib_deps = ${env.lib_deps} lib_ignore = NativeEthernet [env:Teensy4_1] platform = teensy board = teensy41 framework = arduino build_flags = -std=c++17 -Os -g2 ${env.build_flags} lib_deps = ${env.lib_deps} lib_ignore = ================================================ FILE: release_notes.md ================================================ 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 `` 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 `` 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 `` 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 `` command and `` 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 - `` 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 `` 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 `` 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** - `` command allows setting functions based on their number, not based on a code as in `` - **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 `` 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) ================================================ FILE: version.h ================================================ #ifndef version_h #define version_h #include "StringFormatter.h" #define VERSION "5.6.0" // 5.6.0 - Minor adaptions to make production version // 5.5.68 - EXRAIL: BITMAP_SET // - EXRAIL: Comments corrections for doc build // - RailCom: Simplification for sniffer-based detector implementation // 5.5.67 - RailCom, AVR: Correct cutout timer calculation // - RailCom: Improved block handling // - EXRAIL: new IF_ALL,IF_ANY // 5.5.66 - Bugfix: NeoPixel buffer size for RGBW devices // - for SerialUsbLog diagnostics // 5.5.65 - Enable ETHERNET_HOST_NAME (defaults to WIFI_HOST_NAME) // - SerialUsbLog restructure // 5.5.64 - I2C scan included in // 5.5.63 - Bugfix: EXRAIL IFLOCO did not handle -1 (loco not found) // 5.5.62 - EXRAIL IFLOCO(list) // - NEOPIXEL automatic WHITE(if available) when red=green=blue // 5.5.61 - Bugfix: PCA9685 driver did not handle mux I2C addresses for writing registers // 5.5.60 - EXRAIL SPEEDUP(by) SLOWDOWN(by) SPEED_REL(percent) // - EXRAIL ZTEST diff between cmds and test captions // - Tuning DFPlayer base timing. // 5.5.59 - Bugfix buffer size for consist feedback // - command to query estop lock status // 5.5.58 - Freemem in 4k blocks on 32bit cpus // - newline fix for Engine Driver // 5.5.57 - XL9535 HAL driver // - ESTOP LOCK feedback to throttles // 5.5.56 - ESTOP_PAUSE and ESTOP_RESUME functions/commands // - DFPlayerI2C auto detect UART crystal frequency // - DFPlayer PAUSE and RESUME commands, and EQ names // - TCA9555 alias of PCA9555 // 5.5.55 - Bugfix: Real time clock i2c address recognition // - DFPlayer redesign to amalgamate Serial and i2c drivers // - DFPlayer commands and EXRAIL PLAY_ macros // - EXRAIL Documentation spelling corrections // 5.5.54 - Bugfix: Allow longer serial payload length in parser on 32 bit arch, save RAM on AVR // 5.5.53 - Bugfix: EXRAIL Asserts pbSize calculation error for pin blacklist // 5.5.52 - Command station consists <^> and EXRAIL BUILD_CONSIST/BREAK_COMNSIST // 5.5.51 - Bugfix: EXRAIL failed TURNTABLE create commands (I2C off) can crash CS // - Bugfix: EXRAIL be extra careful not to deref nullptr // 5.5.50 - Replace the SC power status with something better // - EXRAIL RANDOM_CALL, RANDOM_FOLLOW // 5.5.49 - EXRAIL displays wait_while_red state // - EXRAIL SAVE_SPEED,RESTORE_SPEED,XSAVE_SPEED,XRESTORE_SPEED macros // 5.4.48 - EXRAIL improvements: // - IFROUTE_HIDDEN, IFROUTE_DISABLED, IFROUTE_ACTIVE, IFROUTE_INACTIVE macros // - FREEALL and to free all reserves // - WAIT_WHILE_RED macro to wait at red signals // - START_SHARED nd START_SEND macros to share or transfer locos to new tasks // 5.5.47 - Make it possible to turn off max ack duration check // - Wifi: Make it possible to hide the SSID // - New trainbrains debug option // - ESP32: SSID named "OFF" will turn all WIFI off // - DCCEX protocol change: <#> returns <# N> where N is the number of presumably empty slots for mobile decoders // - Bugfix: Race condition with RMTChannel::dataRepeat causes packets to be lost #460 // - Handle loco table full // 5.5.46 - Major rewrite of loco table // 5.5.45 - Incoming <@ row col "text"> command // - Bugfix: for unknown loco // - new and commands // - new EXRAIL IFSTASHED_HERE(stashId) function // 5.5.44 - Config simplification (default obvious values) // - Config will no longer include config.example.h // - Bugfix: DS1307 serial when clock not set // - Bugfix: I2C speed set in some drivers // 5.5.43 - Upgraded Trainbrains HAL driver // 5.5.42 - Bugfix: ESP32 WIFI AP mode was not always selected when wanted // 5.5.41 - Bugfix: Toolbox not showing sensors // - MAX_LOCOS can be defined in config.h // 5.5.40 - Bugfix: EXSensorCAM.h use check byte for i2c error detection // 5.5.39 - Remove of unused EX-CommandStation-installer.exe // - Bugfix: Sniffer and reminder table overflow // 5.5.38 - Bugfix: restore EXRAIL/ENDEXRAIL obsolete macros as no-operations // - RAM Saver feature: JMRI_SENSOR and JMRI_SENSOR_NOPULLUP // 5.5.37 - Bugfix: Keep power status of track when doing join/unjoin, new keep power option for setTrackMode() // 5.5.36 - make more diag conditional // - Bugfix: SSD1309 OLED controllers // 5.5.35 - BUGFIX DCC Packet Queue timing leak with single loco // 5.5.34 - STM32: Remove I2C interrupt blocking waveform interrupt // - Bugfix: Negative route Ids // 5.5.33 - Fix CONFIG_SERVO when default PCA9685 definition used. // 5.5.32 - Feature: Enable sniffer on CSB-1 // 5.5.31 - track status command // - myTrackStatus.example.h added // - Provide for WiFi false on ESP32 // 5.5.30 - EXRAIL shows why tasks are waiting // 5.5.29 - Resolved compiler warnings // 5.5.28 - DCC Queue memory leak fix // 5.5.27 - PCF8574 output pin initialization parameter // 5.5.26 - PCA9554 and TCA9554/9534 I2C 8-bit GPIO expander drivers // 5.2.25 - IO_Bitmap and assicated Exrail macros // 5.5.24 - SensorCAM in I2C scan and automatically setClock // 5.5.23 - Reminder loop Idle packet optimization // 5.5.22 - (5.4.9) Handle non-compliant decoders returning 255 for cv 20 and confusing with bad consist addresses. // - DCC 5mS gap to same loco DCC packet restriction // - Catch up MASTER for ESP32 IDF version check // - Catch up MASTER for Serial input length check // - Catch up MASTER for JOIN/POWER order change // 5.5.21 - Backed out the broken merge with frequency change and // 5.5.20 - EXRAIL SET/RESET assert fix // 5.5.19 - Railcom change to use RailcomCollector device // 5.5.18 - New STASH internals // - EXRAIL IFSTASH/CLEAR_ANY_STASH // - to clear any stash with loco id // - See Release_Notes/Stash.md // 5.5.17 - Extensive new compile time checking in exrail scripts (duplicate sequences etc), no function change // 5.5.16 - DOXYGEN comments in EXRAIL2MacroReset.h // 5.5.15 - Support for F429ZI/F329ZI // - Own mDNS support for (wired) Ethernet // 5.5.14 - DCC Non-blocking packet queue with priority // 5.5.13 - Update STM32duino core to v19.0.0. for updated PeripheralPins.c in preparation for F429/439ZI Ethernet support // 5.5.12 - Websocket support (wifi only) // 5.5.11 - (5.4.2) accessory command reverse // 5.5.10 - CamParser fix // 5.5.9 - (5.4.3) fix changeFn for functions 29..31 // 5.5.8 - EXSensorCam clean up to match other filters and // - avoid need for config.h settings // - Test: IO_I2CDFPlayer.h inserted 10mS deleay in Init_SC16IS752() just after soft-reset for board with 1.8432 Mhz xtal // - IO_I2CDFPlayer.h: fixed 2 compiler errors as the compilers are getting stricter // 5.5.7 - ESP32 bugfix packet buffer race (as 5.4.1) // 5.5.6 - Fix ESP32 build bug caused by include reference loop // 5.5.5 - Railcom implementation with IO_I2CRailcom driver // - response analysis and block management. // - POM read using Railcom. // - See Release_notes/Railcom.md // 5.5.4 - Split ESP32 from DCCWaveform to DCCWaveformRMT // - Railcom Cutout control (DCCTimerAVR Mega only so far) // 5.5.3 - EXRAIL ESTOPALL,XPOM, // - Bugfix RESERVE to cause ESTOP.(was STOP) // - Correct direction sync after manual throttle change. // - plus ONBLOCKENTER/EXIT in preparation for Railcom // 5.5.2 - DS1307 Real Time clock // 5.5.1 - Momentum // 5.5.0 - New version on devel // 5.4.3 - bugfix changeFn for functions 29..31 // 5.4.2 - Reversed turnout bugfix // 5.4.1 - ESP32 bugfix packet buffer race // 5.4.0 - New version on master // 5.2.96 - EXRAIL additions XFWD() and XREV() // 5.2.95 - Release candidate for 5.4 // 5.2.94 - Bugfix: Less confusion and simpler code around the RCN213 defines // 5.2.93 - Bugfix ESP32: clear progTrackSyncMain (join flag) when prog track is removed // 5.2.92 - Bugfix: FADE power off fix, EXRAIL power diagnostic fix. // 5.2.91 - Bugfix: Neopixel I2C overlap check // 5.2.90 - Bugfix: EXRAIL EXTT_TURNTABLE() now has description as optional in line with ocumentation (also fixed DCC_TURNTABLE) // 5.2.89 - EXRAIL SET(vpin[,npins]) RESET(vpin,[,npins]) pin range manipulation // 5.2.88 - Fix bug where EX-Turntable objects return incorrect angle for home with // 5.2.87 - CamParser and IO_EXSensorCam driver // 5.2.86 - IO_TCA8418 driver for keypad matrix input now fully functioning, including being able to use an interrupt pin // 5.2.85 - IO_TM1638 driver, SEG7 Exrail macro and _s7 segment pattern generator. // 5.2.84 - Fix TrackManager setDCCSignal and setPROGSignal for STM32 shadowing of PORTG/PORTH - this time it really is correct! // 5.2.83 - Various STM32 related fixes for serial ports, I2C pullups now turned off, and shadowing of PORTG/PORTH for TrackManager now correct // 5.2.82 - TrackManager and EXRAIL: Introduce more consistent names for <= ...> and SET_TRACK // 5.2.81 - STM32 Ethernet boards support, also now have specific EX8874 motor driver definition // 5.2.80 - EthernetInterface upgrade, including STM32 Ethernet support // 5.2.79 - serial manager loop that handles quoted strings // - WiFiESP32 reconfig // 5.2.78 - NeoPixel support. // - // - EXRAIL SETFREQ drop loco param (breaking since 5.2.28) // 5.2.65 - Speedup Exrail SETFREQ // 5.2.64 - Bugfix: <0 PROG> updated to undo JOIN // 5.2.63 - Implement WIFI_LED for ESP32, ESPduino32 and EX-CSB1, that is turned on when STA mode connects or AP mode is up // - Add BOOSTER_INPUT definitions for ESPduino32 and EX-CSB1 to config.example.h // - Add WIFI_LED definitions for ESPduino32 and EX-CSB1 to config.example.h // 5.2.62 - Allow acks way longer than standard // 5.2.61 - Merg CBUS ACON/ACOF/ONACON/ONACOF Adapter interface. // - LCC Adapter interface throttled startup, // (Breaking change with Adapter base code) // 5.2.60 - Bugfix: Opcode AFTEROVERLOAD does not have an argument that is a pin and needs to be initialized // - Remove inrush throttle after half good time so that we go to mode overload if problem persists // 5.2.59 - STM32 bugfix correct Serial1 definition for Nucleo-F401RE // - STM32 add support for ARDUINO_NUCLEO_F4X9ZI type to span F429/F439 in upcoming STM32duino release v2.8 as a result of our PR // 5.2.58 - EXRAIL ALIAS allows named pins // 5.2.57 - Bugfix autoreverse: Apply mode by binart bit match and not by equality // 5.2.56 - Bugfix and refactor for EXRAIL getSignalSlot // 5.2.55 - Move EXRAIL isSignal() to public to allow use in STEALTH call // 5.2.54 - Bugfix for EXRAIL signal handling for active high // 5.2.53 - Bugfix for EX-Fastclock, call I2CManager.begin() before checking I2C address // 5.2.52 - Bugfix for ADCee() to handle ADC2 and ADC3 channel inputs on F446ZE and others // - Add support for ports G and H on STM32 for ADCee() and MotorDriver pins/shadow regs // 5.2.51 - Bugfix for SIGNAL: Distinguish between sighandle and sigid // 5.2.50 - EXRAIL ONBUTTON/ONSENSOR observe LATCH // 5.2.49 - EXRAIL additions: // ONBUTTON, ONSENSOR // 5.2.48 - Bugfix: HALDisplay was generating I2C traffic prior to I2C being initialised // 5.2.47 - EXRAIL additions: // STEALTH_GLOBAL // BLINK // TOGGLE_TURNOUT // FTOGGLE, XFTOGGLE // Reduced code-developmenmt DIAG noise // 5.2.46 - Support for extended consist CV20 in and // - New cmd to handle long/short consist ids // 5.2.45 - ESP32 Trackmanager reset cab number to 0 when track is not DC // ESP32 fix PWM LEDC inverted pin mode // ESP32 rewrite PWM LEDC to use pin mux // 5.2.42 - ESP32 Bugfix: Uninitialized stack variable // 5.2.41 - Update rotary encoder default address to 0x67 // 5.2.40 - Allow no shield // 5.2.39 - Functions for DC frequency: Use func up to F31 // 5.2.38 - Exrail MESSAGE("text") to send a user message to all // connected throttles (uses and withrottle Hmtext. // 5.2.37 - Bugfix ESP32: Use BOOSTER_INPUT define // 5.2.36 - Variable frequency for DC mode // 5.2.35 - Bugfix: Make DCC Extended Accessories follow RCN-213 // 5.2.34 - Command fopr DCC Extended Accessories // - Exrail ASPECT(address,aspect) for above. // - EXRAIL DCCX_SIGNAL(Address,redAspect,amberAspect,greenAspect) // - Exrail intercept for DCC Signals. // 5.2.33 - Exrail CONFIGURE_SERVO(vpin,pos1,pos2,profile) // 5.2.32 - Railcom Cutout (Initial trial Mega2560 only) // 5.2.31 - Exrail JMRI_SENSOR(vpin [,count]) creates types. // 5.2.30 - Bugfix: WiThrottle sendIntro after initial N message as well // 5.2.29 - Added IO_I2CDFPlayer.h to support DFPLayer over I2C connected to NXP SC16IS750/SC16IS752 (currently only single UART for SC16IS752) // - Added enhanced IO_I2CDFPLayer enum commands to EXRAIL2.h // - Added PLAYSOUND alias of ANOUT to EXRAILMacros.h // - Added UART detection to I2CManager.cpp // 5.2.28 - ESP32: Can all Wifi channels. // - ESP32: Only write Wifi password to display if it is a well known one // 5.2.27 - Bugfix: IOExpander memory allocation // 5.2.26 - Silently ignore overridden HAL defaults // - include HAL_IGNORE_DEFAULTS macro in EXRAIL // 5.2.25 - Fix bug causing after working & <1 A> etc. and update to <=> // Added EXRAIL SET_POWER(track, ON/OFF) // Fixed a problem whereby <1 MAIN> also powered on PROG track // Added functions to TrackManager.cpp to allow UserAddin code for power display on OLED/LCD // Added - returnMode(byte t), returnDCAddr(byte t) & getModeName(byte Mode) // 5.1.11 - STM32F4xx revised I2C clock setup, no correctly sets clock and has fully variable frequency selection // 5.1.10 - STM32F4xx DCCEXanalogWrite to handle PWM generation for TrackManager DC/DCX // - STM32F4xx DCC 58uS timer now using non-PWM output timers where possible // - ESP32 brakeCanPWM check now detects UNUSED_PIN // - ARM architecture brakeCanPWM now uses digitalPinHasPWM() // - STM32F4xx shadowpin extensions to handle pins on ports D, E and F // 5.1.9 - Fixed IO_PCA9555'h to work with PCA9548 mux, tested OK // 5.1.8 - STM32Fxx ADCee extension to support ADCs #2 and #3 // 5.1.7 - Fix turntable broadcasts for non-movement activities and result // 5.1.6 - STM32F4xx native I2C driver added // 5.1.5 - Added turntable object and EXRAIL commands // - , , - turntable commands // - DCC_TURNTABLE, EXTT_TURNTABLE, IFTTPOSITION, ONROTATE, ROTATE, ROTATE_DCC, TT_ADDPOSITION, WAITFORTT EXRAIL // 5.1.4 - Added ONOVERLOAD & AFTEROVERLOAD to EXRAIL // 5.1.3 - Make parser more fool proof // 5.1.2 - Bugfix: ESP32 30ms off time // 5.1.1 - Check bad AT firmware version // - Update IO_PCA9555.h reflecting IO_MCP23017.h changes to support PCA9548 mux // 5.0.1 - Bugfix: execute 30ms off time before rejoin // 5.0.0 - Make 4.2.69 the 5.0.0 release // 4.2.69 - Bugfix: Make work in DC mode // 4.2.68 - Rename track mode OFF to NONE // 4.2.67 - AVR: Pin specific timer register seting // - Protect Uno user from choosing DC(X) // - More Nucleo variant defines // - GPIO PCA9555 / TCA9555 support // 4.2.66 - Throttle inrush current by applying PWM to brake pin when // fault pin goes active // 4.2.65 - new config WIFI_FORCE_AP option // 4.2.63 - completely new overcurrent detection // - ESP32 protect from race in RMT code // 4.2.62 - Update IO_RotaryEncoder.h to ignore sending current position // - Update IO_EXTurntable.h to remove forced I2C clock speed // - Show device offline if EX-Turntable not connected // 4.2.61 - MAX_CURRENT restriction (caps motor shield value) // 4.2.60 - Add mDNS capability to ESP32 for autodiscovery // 4.2.59 - Fix: AP SSID was DCC_ instead of DCCEX_ // 4.2.58 - Start motordriver as soon as possible but without waveform // 4.2.57 - New overload handling (faster and handles commonFaultPin again) // - Optimize analog read STM32 // 4.2.56 - Update IO_RotaryEncoder.h: // - Improved I2C communication, non-blocking reads // - Enable sending positions to the encoder from EXRAIL via SERVO() // 4.2.55 - Optimize analog read for AVR // 4.2.54 - EX8874 shield in config.example.h // - Fix: Better warnings for pin number errors // - Fix: Default roster list possible in Withrottle and // - Fix: Pin handling supports pins up to 254 // 4.2.53 - Fix: Fault pin handling made more straight forward // 4.2.52 - Experimental support for sabertooth motor controller on ESP32 // 4.2.51 - Add DISABLE_PROG to disable programming to save RAM/Flash // 4.2.50 - Fixes: estop all, turnout eeprom, cab ID check // 4.2.49 - Exrail SPEED take notice of external direction change // 4.2.48 - BROADCAST/WITHROTTLE Exrail macros // 4.2.47 - Correct response to // 4.2.46 - Support boards with inverted fault pin // 4.2.45 - Add ONCLOCKMINS to FastClock to allow hourly repeat events // 4.2.44 - Add PowerShell installer EX-CommandStation-installer.exe // 4.2.43 - Fix STM32 set right port mode bits for analog // 4.2.42 - Added EXRAIL TURNOUTL Macro definition // 4.2.41 - Move HAl startup to ASAP in setup() // - Fix DNOU8 output pin setup to all LOW // 4.2.40 - Automatically detect conflicting default I2C devices and disable // 4.2.39 - DFplayer driver now polls device to detect failures and errors. // 4.2.38 - Clean up compiler warning when IO_RotaryEncoder.h included // 4.2.37 - Add new FLAGS HAL device for communications to/from EX-RAIL; // - Fix diag display of high VPINs within IODevice class. // 4.2.36 - do not broadcast a turnout state that has not changed // - Use A2/A3 for current sensing on ESP32 + Motor Shield // 4.2.35 - add direct pin manipulation command // 4.2.34 - Completely fix EX-IOExpander analogue inputs // 4.2.33 - Fix EX-IOExpander non-working analogue inputs // 4.2.32 - Fix LCD/Display bugfixes from 4.2.29 // 4.2.31 - Removes EXRAIL statup from top of file. (BREAKING CHANGE !!) // Just add AUTOSTART to the top of your myAutomation.h to restore this function. // 4.2.30 - Fixes/enhancements to EX-IOExpander device driver. // 4.2.29 - Bugfix Scroll LCD without empty lines and consistent // 4.2.28 - Reinstate use of timer11 in STM32 - remove HA mode. // - Update IO_DFPlayer to work with MP3-TF-16P rev3. // 4.2.27 - Bugfix LCD showed random characters in SCROLLMODE 2 // 4.2.26 - EX-IOExpander device driver enhancements // - Enhance I2C error checking // - Introduce delays to _loop to allow room for other I2C device comms // - Improve analogue read reliability // 4.2.25 - Bugfix SAMD21 Exrail odd byte boundary // 4.2.24 - Bugfix Ethernet shield: Static IP now possible // 4.2.23 - Bugfix signalpin2 was not set up in shadow port // 4.2.22 - Implement broadcast of Track Manager changes // 4.2.21 - Implement non-blocking I2C for EX-IOExpander device driver // 4.2.20 - & commands for multi-track gauges // - Reinstate but remember its a bit useless when TM involved. // 4.2.19 - Bugfix for analog reading of track current sensor offset. // 4.2.18 - I2C Multiplexer support through Extended Addresses, // added for Wire, 4209 and AVR I2C drivers. // - I2C retries when an operation fails. // - I2C timeout handling and recovery completed. // - I2C SAMD Driver Read code completed. // - PCF8575 I2C GPIO driver added. // - EX-RAIL ANOUT function for triggering analogue // HAL drivers (e.g. analogue outputs, DFPlayer, PWM). // - EX-RAIL SCREEN function for writing to screens other // than the primary one. // - Installable HALDisplay Driver, with support // for multiple displays. // - Layered HAL Drivers PCA9685pwm and Servo added for // native PWM on PCA9685 module and // for animations of servo movement via PCA9685pwm. // This is intended to support EXIOExpander and also // replace the existing PCA9685 driver. // - Add to reinitialise failed drivers. // - Add UserAddin facility to allow a user-written C++ function to be // declared in myHal.cpp, to be called at a user-specified frequency. // - Add ability to configure clock speed of PCA9685 drivers // (to allow flicker-free LED control). // - Improve stability of VL53L0X driver when XSHUT pin connected. // - Enable DCC high accuracy mode for STM32 on standard motor shield (pins D12/D13). // - Incorporate improvements to ADC scanning performance (courtesy of HABA). // 4.2.17 LCN bugfix // 4.2.16 Move EX-IOExpander servo support to the EX-IOExpander software // 4.2.15 Add basic experimental PWM support to EX-IOExpander // EX-IOExpander 0.0.14 minimum required // 4.2.14 STM32F4xx fast ADC read implementation // 4.2.13 Broadcast power for again // 4.2.12 Bugfix for issue #299 TurnoutDescription NULL // 4.2.11 Exrail IFLOCO feature added // 4.2.10 SIGNAL/SIGNALH bug fix as they were inverted // IO_EXIOExpander.h input speed optimisation // ONCLOCK and ONCLOCKTIME command added to EXRAIL for EX-FastCLock // Serial command added for EX-FastClock // Broadcast added for EX-FastClock // IO_EXFastClock.h added for I2C FastClock connection // 4.2.9 duinoNodes support // 4.2.8 HIGHMEM (EXRAIL support beyond 64kb) // Withrottle connect/disconnect improvements // Report BOARD_TYPE if provided by compiler // 4.2.7 FIX: Static IP addr // FIX: Reuse WiThrottle list entries // 4.2.6 FIX: Remove RAM thief // FIX: ADC port 8-15 fix // 4.2.5 Make GETFLASHW code more universal // FIX: Withrottle roster index // Ethernet start improvement and link detection // 4.2.4 ESP32 experimental BT support // More DC configurations possible and lower frequency // Handle decoders that do not ack at write better // 4.2.3 Bugfix direction when togging between MAIN and DC // Bugfix return fail when F/f argument out of range // More error checking for out of bounds motor driver current trip limit // 4.2.2 ESP32 beta // JOIN/UMJOIN on ESP32 // 4.2.1 ESP32 alpha // Ready for alpha test on ESP32. Track switching with <=> untested // Send DCC signal on MAIN // Detects ACK on PROG // 4.2.0 Track Manager additions: // Broadcast improvements to separate <> and Withrottle responses // Float eliminated saving >1.5kb PROGMEM and speed. // SET_TRACK(track,mode) Functions (A-H, MAIN|PROG|DC|DCX|OFF) // New DC track function and DCX reverse polarity function // TrackManager DCC & DC up to 8 Districts Architecture // Automatic ALIAS(name) // Command Parser now accepts Underscore in Alias Names // 4.1.1 Bugfix: preserve turnout format // Bugfix: parse multiple commands in one buffer string correct // Bugfix: command signal status in Exrail // 4.1.0 ... // // 4.0.2 EXRAIL additions: // ACK defaults set to 50mA LIMIT, 2000uS MIN, 20000uS MAX // myFilter automatic detection (no need to call setFilter) // FIX negative route ids in WIthrottle problem. // IFRED(signal_id), IFAMBER(signal_id), IFGREEN(signal_id) // commands // command to obtain current throttle settings // JA, JR, JT commands to obtain route, roster and turnout descriptions // HIDDEN turnouts // PARSE <> commands in EXRAIL // VIRTUAL_TURNOUT // and KILLALL command to stop all tasks. // FORGET forgets the current loco in DCC reminder tables. // Servo signals (SERVO_SIGNAL) // High-On signal pins (SIGNALH) // Wait for analog value (ATGTE, ATLT) // 4.0.1 Small EXRAIL updates // EXRAIL BROADCAST("msg") // EXRAIL POWERON // 4.0.0 Major functional and non-functional changes. // Engine Driver "DriveAway" feature enhancement // 'Discovered Server' multicast Dynamic Network Server (mDNS) displays available WiFi connections to a DCC++EX Command Station // New EX-RAIL "Extended Railroad Automation Instruction Language" automation capability. // EX-Rail Function commands for creating Automation, Route & Sequence Scripts // EX-RAIL “ROSTER” Engines Id & Function key layout on Engine Driver or WiThrottle // EX-RAIL DCC++EX Commands to Control EX-RAIL via JMRI Send pane and IDE Serial monitors // New JMRI feature enhancements; // Reads DCC++EX EEPROM & automatically uploades any Signals, DCC Turnouts, Servo Turnouts, Vpin Turnouts , & Output pane // Turnout class revised to expand turnout capabilities, new commands added. // Provides for multiple additional DCC++EX WiFi connections as accessory controllers or CS for a programming track when Motor Shields are added // Supports Multiple Command Station connections and individual tracking of Send DCC++ Command panes and DCC++ Traffic Monitor panes // New HAL added for I/O (digital and analogue inputs and outputs, servos etc) // Automatically detects & connects to supported devices included in your config.h file // Support for MCP23008, MCP23017 and PCF9584 I2C GPIO Extender modules. // Support for PCA9685 PWM (servo) control modules. // Support for analogue inputs on Arduino pins and on ADS111x I2C modules. // Support for MP3 sound playback via DFPlayer module. // Support for HC-SR04 Ultrasonic range sensor module. // Support for VL53L0X Laser range sensor module (Time-Of-Flight). // Added diagnostic command to show configured devices // New Processor Support added // Compiles on Nano Every and Teensy // Native non-blocking I2C drivers for AVR and Nano architectures (fallback to blocking Wire library for other platforms). // Can disable EEPROM code // EEPROM layout change - deletes EEPROM contents on first start following upgrade. // Output class now allows ID > 255. // Configuration options to globally flip polarity of DCC Accessory states when driven from command and command. // Increased use of display for showing loco decoder programming information. // Can define border between long and short addresses // Turnout and accessory states (thrown/closed = 0/1 or 1/0) can be set to match RCN-213 // Bugfix: one-off error in CIPSEND drop // Bugfix: disgnostic display of ack pulses >32kus // Bugfix: Current read from wrong ADC during interrupt // 3.2.0 Development Release Includes all of 3.1.1 thru 3.1.7 enhancements // 3.1.7 Bugfix: Unknown locos should have speed forward // 3.1.6 Make output ID two bytes and guess format/size of registered outputs found in EEPROM // 3.1.5 Fix LCD corruption on power-up // 3.1.4 Refactor OLED and LCD drivers and remove unused code // 3.1.3 Add a loop delay to give more time for sensing an Ethernet cable connection // 3.1.2 Eliminate wait after write when prog is joined or prog power is off // 3.1.1 SH1106 OLED Display Offset Fix // 3.0.16 Ignore CV1 bit 7 read rejected by decoder when identifying loco id. // 3.0.15 only send function commands once, not 4 times // 3.0.14 gap in ack tolerant fix, prog track power management over join fix. // 3.0.13 Functions>127 fix // 3.0.12 Fix HOSTNAME function for STA mode for WiFi // 3.0.11 28 speedstep support // 3.0.10 Teensy Support // 3.0.9 rearranges serial newlines for the benefit of JMRI. // 3.0.8 Includes <* *> wraps around DIAGs for the benefit of JMRI. // 3.0.7 Includes merge from assortedBits (many changes) and ACK manager change for lazy decoders // 3.0.6 Includes: // Fix Bug that did not let us transmit 5 byte sized packets like PoM // 3.0.5 Includes: // Fix Fn Key startup with loco ID and fix state change for F16-28 // 3.0.4 Includes: // Wifi startup bugfixes // 3.0.3 Includes: // command to write loco address and clear consist // command will allow for consist address // Startup commands implemented #endif

#endif // 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 if (!stashCallback(stream, p, ringStream)) break; if (params == 1) // Write new loco id (clearing consist and managing short/long) DCC::setLocoId(p[0],callback_Wloco); else if (params == 4) // WRITE CV ON PROG DCC::writeCVByte(p[0], p[1], callback_W4); else if ((params==2 || params==3 ) && p[0]=="CONSIST"_hk ) { DCC::setConsistId(p[1],p[2]=="REVERSE"_hk,callback_Wconsist); } else if (params == 2) // WRITE CV ON PROG DCC::writeCVByte(p[0], p[1], callback_W); else break; return; case 'V': // VERIFY CV ON PROG if (params == 2) { // if (!stashCallback(stream, p, ringStream)) break; DCC::verifyCVByte(p[0], p[1], callback_Vbyte); return; } if (params == 3) { if (!stashCallback(stream, p, ringStream)) break; DCC::verifyCVBit(p[0], p[1], p[2], callback_Vbit); return; } break; case 'B': // WRITE CV BIT ON PROG or if (params != 3 && params != 5) break; if (!stashCallback(stream, p, ringStream)) break; DCC::writeCVBit(p[0], p[1], p[2], callback_B); return; case 'R': // READ CV ON PROG if (params == 1) { if (!stashCallback(stream, p, ringStream)) break; if (p[0]=="LOCOID"_hk) { // read consist id DCC::getLocoId(callback_Rloco); return; } if (p[0]=="CONSIST"_hk) { // read consist id DCC::getConsistId(callback_Rloco); return; } // -- uses verify callback DCC::verifyCVByte(p[0], 0, callback_Vbyte); return; } if (params == 3) { // if (!stashCallback(stream, p, ringStream)) break; DCC::readCV(p[0], callback_R); return; } if (params == 0) { // New read driveaway loco id if (!stashCallback(stream, p, ringStream)) break; DCC::getDriveawayLocoId(callback_Rloco); return; } break; #endif case '1': // POWERON <1 [MAIN|PROG|JOIN]> { if (params > 1) break; if (params==0) { // All TrackManager::setTrackPower(TRACK_ALL, POWERMODE::ON); } if (params==1) { if (p[0]=="MAIN"_hk) { // <1 MAIN> TrackManager::setTrackPower(TRACK_MODE_MAIN, POWERMODE::ON); } #ifndef DISABLE_PROG else if (p[0] == "JOIN"_hk) { // <1 JOIN> TrackManager::setJoin(true); TrackManager::setTrackPower(TRACK_MODE_MAIN|TRACK_MODE_PROG, POWERMODE::ON); } else if (p[0]=="PROG"_hk) { // <1 PROG> TrackManager::setJoin(false); TrackManager::setTrackPower(TRACK_MODE_PROG, POWERMODE::ON); } #endif else if (p[0] >= "A"_hk && p[0] <= "H"_hk) { // <1 A-H> byte t = (p[0] - 'A'); TrackManager::setTrackPower(POWERMODE::ON, t); //StringFormatter::send(stream, F("\n"), t+'A'); } else break; // will reply } //TrackManager::streamTrackState(NULL,t); return; } case '0': // POWEROFF <0 [MAIN | PROG] > { if (params > 1) break; if (params==0) { // All TrackManager::setJoin(false); TrackManager::setTrackPower(TRACK_ALL, POWERMODE::OFF); } if (params==1) { if (p[0]=="MAIN"_hk) { // <0 MAIN> TrackManager::setJoin(false); TrackManager::setTrackPower(TRACK_MODE_MAIN, POWERMODE::OFF); } #ifndef DISABLE_PROG else if (p[0]=="PROG"_hk) { // <0 PROG> TrackManager::setJoin(false); TrackManager::progTrackBoosted=false; // Prog track boost mode will not outlive prog track off TrackManager::setTrackPower(TRACK_MODE_PROG, POWERMODE::OFF); } #endif else if (p[0] >= "A"_hk && p[0] <= "H"_hk) { // <1 A-H> byte t = (p[0] - 'A'); TrackManager::setJoin(false); TrackManager::setTrackPower(POWERMODE::OFF, t); //StringFormatter::send(stream, F("\n"), t+'A'); } else break; // will reply } return; } case '!': // ESTOPALL if (p[0]=="P"_hk) DCC::estopLock(true); // else if (p[0]=="R"_hk) DCC::estopLock(false); // \n"): F("\n")); // else DCC::estopAll(); // this broadcasts speed 1(estop) and sets all reminders to speed 1. return; #ifdef HAS_ENOUGH_MEMORY case 'c': // SEND METER RESPONSES // No longer useful because of multiple tracks See and if (params>0) break; TrackManager::reportObsoleteCurrent(stream); return; #endif case 'Q': // SENSORS Sensor::printAll(stream); return; case 's': // STATUS StringFormatter::send(stream, F("\n"), F(VERSION), F(ARDUINO_TYPE), DCC::getMotorShieldName(), F(GITHUB_SHA)); CommandDistributor::broadcastPower(); // is the only "get power status" command we have Turnout::printAll(stream); //send all Turnout states Sensor::printAll(stream); //send all Sensor states return; #ifndef DISABLE_EEPROM case 'E': // STORE EPROM EEStore::store(); StringFormatter::send(stream, F("\n"), EEStore::eeStore->data.nTurnouts, EEStore::eeStore->data.nSensors, EEStore::eeStore->data.nOutputs); return; case 'e': // CLEAR EPROM EEStore::clear(); StringFormatter::send(stream, F("\n")); return; #endif case ' ': // < > StringFormatter::send(stream, F("\n")); return; case 'C': // CONFIG #if defined(ARDUINO_ARCH_ESP32) // currently this only works on ESP32 if (p[0] == "SNIFFER"_hk) { // bool on = false; if (params>1 && p[1] == "ON"_hk) { on = true; } DCCDecoder::onoff(on); return; } #if WIFI_ON if (p[0] == "WIFI"_hk) { // if (params != 5) // the 5 params 0 to 4 are (kinda): WIFI_hk 0x7777 &SSID 0x7777 &PASSWORD break; if (p[1] == 0x7777 && p[3] == 0x7777) { WifiESP::setup((const char*)(com + p[2]), (const char*)(com + p[4]), WIFI_HOSTNAME, IP_PORT, WIFI_CHANNEL, WIFI_FORCE_AP); } return; } #endif #endif //ESP32 if (parseC(stream, params, p)) return; break; #ifndef DISABLE_DIAG case 'D': // DIAG if (parseD(stream, params, p)) return; break; #endif case '=': // TRACK MANAGER CONTROL <= [params]> if (TrackManager::parseEqualSign(stream, params, p)) return; break; case '#': // NUMBER OF LOCOSLOTS <#> { int free = DCCTimer::getMinimumFreeMemory(); int freeSlotGuess = free/sizeof(LocoSlot); freeSlotGuess = freeSlotGuess - 2; // be conservative if (freeSlotGuess > MAX_LOCOS) freeSlotGuess = MAX_LOCOS; if (freeSlotGuess < 0) freeSlotGuess = 0; StringFormatter::send(stream, F("<# %d>\n"), freeSlotGuess); } return; case '-': // Forget Loco <- [cab]> if (params > 1 || p[0]<0) break; if (p[0]==0) DCC::forgetAllLocos(); else DCC::forgetLoco(p[0]); return; case 'F': // New command to call the new Loco Function API if(params!=3) break; if (p[1]=="DCFREQ"_hk) { // if (p[2]<0 || p[2]>3) break; DCC::setDCFreq(p[0],p[2]); return; } if (Diag::CMD) DIAG(F("Setting loco %d F%d %S"), p[0], p[1], p[2] ? F("ON") : F("OFF")); if (DCC::setFn(p[0], p[1], p[2] == 1)) return; break; case '^': // Consist <^ [cab0..7]> if (DCCConsist::parse(stream,params,p)) return; break; #if WIFI_ON case '+': // Complex Wifi interface command (not usual parse) if (atCommandCallback && !ringStream) { TrackManager::setPower(POWERMODE::OFF); atCommandCallback((HardwareSerial *)stream,com); return; } break; #endif case 'J' : // throttle info access { if (params<1) break; // //if ((params<1) | (params>2)) break; // int16_t id=(params==2)?p[1]:0; switch(p[0]) { case "C"_hk: // sets time and speed if (params==1) { // returns latest time int16_t x = CommandDistributor::retClockTime(); StringFormatter::send(stream, F("\n"), x); return; } CommandDistributor::setClockTime(p[1], p[2]); return; case "G"_hk: // current gauge limits if (params>1) break; TrackManager::reportGauges(stream); // return; case "I"_hk: // current values if (params>1) break; TrackManager::reportCurrent(stream); // return; case "L"_hk: // track state and mA value on display if (params<3) break; TrackManager::reportCurrentLCD(p[1], p[2]); // Track power status return; case "A"_hk: // intercepted by EXRAIL// returns automations/routes if (params!=1) break; // StringFormatter::send(stream, F("\n")); return; case "M"_hk: // Stash management if (parseJM(stream, params, p)) return; break; case "R"_hk: // returns rosters StringFormatter::send(stream, F("\n")); return; case "T"_hk: // returns turnout list StringFormatter::send(stream, F(" for ( Turnout * t=Turnout::first(); t; t=t->next()) { if (t->isHidden()) continue; StringFormatter::send(stream, F(" %d"),t->getId()); } } else { // 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; // No turntables without HAL support #ifndef IO_NO_HAL case "O"_hk: // for (Turntable * tto=Turntable::first(); tto; tto=tto->next()) { if (tto->isHidden()) continue; StringFormatter::send(stream, F(" %d"),tto->getId()); } StringFormatter::send(stream, F(">\n")); } else { // Turntable *tto=Turntable::get(id); if (!tto || tto->isHidden()) { StringFormatter::send(stream, F(" %d X>\n"), id); } else { uint8_t pos = tto->getPosition(); uint8_t type = tto->isEXTT(); uint8_t posCount = tto->getPositionCount(); const FSH *todesc = NULL; #ifdef EXRAIL_ACTIVE todesc = RMFT2::getTurntableDescription(id); #endif if (todesc == NULL) todesc = F(""); StringFormatter::send(stream, F(" %d %d %d %d \"%S\">\n"), id, type, pos, posCount, todesc); } } return; case "P"_hk: // returns turntable position list for the turntable id if (params==2) { // Turntable *tto=Turntable::get(id); if (!tto || tto->isHidden()) { StringFormatter::send(stream, F(" %d X>\n"), id); } else { uint8_t posCount = tto->getPositionCount(); const FSH *tpdesc = NULL; for (uint8_t p = 0; p < posCount; p++) { StringFormatter::send(stream, F("getPositionAngle(p); #ifdef EXRAIL_ACTIVE tpdesc = RMFT2::getTurntablePositionDescription(id, p); #endif if (tpdesc == NULL) tpdesc = F(""); StringFormatter::send(stream, F(" %d %d %d \"%S\""), id, p, angle, tpdesc); StringFormatter::send(stream, F(">\n")); } } } else { StringFormatter::send(stream, F("\n")); } return; #endif default: break; } // switch(p[1]) break; // case J } // No turntables without HAL support #ifndef IO_NO_HAL case 'I': // TURNTABLE if (parseI(stream, params, p)) return; break; #endif case '/': // implemented in EXRAIL parser case 'L': // LCC interface implemented in EXRAIL parser case 'N': // interface implemented in CamParser break; // Will if not intercepted by filters case '@': #ifndef DISABLE_VDPY if (params==0) { // <@> JMRI saying "give me virtual LCD msgs" CommandDistributor::setVirtualLCDSerial(stream); StringFormatter::send(stream, F("<@ 0 0 \"DCC-EX v" VERSION "\">\n" "<@ 0 1 \"Lic GPLv3\">\n")); return; } #endif if (params==4 && p[2]==0x7777) { // <@ x y "string"> // p[2] will be 0x7777 string marker. StringFormatter::lcd2(p[0],p[1], F("%s"),(const char*)(com + p[3])); return; } break; // will default: //anything else will diagnose and drop out to if (opcode >= ' ' && opcode <= '~') { DIAG(F("Opcode=%c params=%d"), opcode, params); for (int i = 0; i < params; i++) DIAG(F("p[%d]=%d (0x%x)"), i, p[i], p[i]); } else { DIAG(F("Unprintable %x"), opcode); } break; } // end of opcode switch out:// Any fallout here sends an StringFormatter::send(stream, F("\n")); } bool DCCEXParser::parseZ(Print *stream, int16_t params, int16_t p[]) { switch (params) { case 2: // { Output *o = Output::get(p[0]); if (o == NULL) return false; o->activate(p[1]); StringFormatter::send(stream, F("\n"), p[0], p[1]); } return true; case 3: // if (p[0] < 0 || p[2] < 0 || p[2] > 7 ) return false; if (!Output::create(p[0], p[1], p[2], 1)) return false; StringFormatter::send(stream, F("\n")); return true; case 1: // if (!Output::remove(p[0])) return false; StringFormatter::send(stream, F("\n")); return true; case 0: // list Output definitions { bool gotone = false; for (Output *tt = Output::firstOutput; tt != NULL; tt = tt->nextOutput) { gotone = true; StringFormatter::send(stream, F("\n"), tt->data.id, tt->data.pin, tt->data.flags, tt->data.active); } return gotone; } default: return false; } } #include "IO_DFPlayerBase.h" bool DCCEXParser::parsey(Print *stream, int16_t params, int16_t p[]) { (void)stream; // unused parameter // // // // // // // // // if (params<2) return false; int16_t v1=0; uint8_t v2=0; uint16_t cmd=0; switch (p[1]) { case "PLAY"_hk: if (params<3) return false; v1=p[2]; // track cmd=DFPlayerBase::DF_PLAY; if (params>=4) v2=p[3]; // volume break; case "REPEAT"_hk: if (params<3) return false; v1=p[2]; // track cmd=DFPlayerBase::DF_REPEATPLAY; if (params>=4) v2=p[3]; // volume break; case "FOLDER"_hk: if (params!=3) return false; v2=p[2]; // folder cmd=DFPlayerBase::DF_FOLDER; break; case "STOP"_hk: if (params!=2) return false; cmd=DFPlayerBase::DF_STOPPLAY; break; case "PAUSE"_hk: if (params!=2) return false; cmd=DFPlayerBase::DF_PAUSE; break; case "RESUME"_hk: if (params!=2) return false; cmd=DFPlayerBase::DF_RESUME; break; case "RESET"_hk: if (params!=2) return false; cmd=DFPlayerBase::DF_RESET; break; case "VOL"_hk: if (params!=3) return false; cmd=DFPlayerBase::DF_VOL; v2=p[2]; // volume break; case "EQ"_hk: if (params!=3) return false; cmd=DFPlayerBase::DF_EQ; v2=p[2]; // EQ type break; default: return false; } IODevice::writeAnalogue((VPIN)p[0],v1,v2,cmd); return true; } //=================================== 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); 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; } bool DCCEXParser::funcmap(int16_t cab, byte value, byte fstart, byte fstop) { for (int16_t i = fstart; i <= fstop; i++) { if (! DCC::setFn(cab, i, value & 1)) return false; value >>= 1; } return true; } //=================================== bool DCCEXParser::parseT(Print *stream, int16_t params, int16_t p[]) { switch (params) { case 0: // list turnout definitions return Turnout::printAll(stream); // will if none found case 1: // delete turnout if (!Turnout::remove(p[0])) return false; StringFormatter::send(stream, F("\n")); return true; case 2: // { bool state = false; switch (p[1]) { // Turnout messages use 1=throw, 0=close. case 0: case "C"_hk: state = true; break; case 1: case "T"_hk: state= false; break; case "X"_hk: { 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; return true; } default: // Anything else is some kind of turnout create function. if (params == 6 && p[1] == "SERVO"_hk) { // if (!ServoTurnout::create(p[0], (VPIN)p[2], (uint16_t)p[3], (uint16_t)p[4], (uint8_t)p[5])) return false; } else if (params == 3 && p[1] == "VPIN"_hk) { // if (!VpinTurnout::create(p[0], p[2])) return false; } else if (params >= 3 && p[1] == "DCC"_hk) { // 0<=addr<=511, 0<=subadd<=3 (like command). if (params==4 && p[2]>=0 && p[2]<512 && p[3]>=0 && p[3]<4) { // if (!DCCTurnout::create(p[0], p[2], p[3])) return false; } else if (params==3 && p[2]>0 && p[2]<=512*4) { // , 1<=nn<=2048 // Linearaddress 1 maps onto decoder address 1/0 (not 0/0!). if (!DCCTurnout::create(p[0], (p[2]-1)/4+1, (p[2]-1)%4)) return false; } else return false; } else if (params==3) { // legacy for DCC accessory if (p[1]>=0 && p[1]<512 && p[2]>=0 && p[2]<4) { if (!DCCTurnout::create(p[0], p[1], p[2])) return false; } else return false; } else if (params==4) { // legacy for Servo if (!ServoTurnout::create(p[0], (VPIN)p[1], (uint16_t)p[2], (uint16_t)p[3], 1)) return false; } else return false; StringFormatter::send(stream, F("\n")); return true; } } bool DCCEXParser::parseS(Print *stream, int16_t params, int16_t p[]) { switch (params) { case 3: // create sensor. pullUp indicator (0=LOW/1=HIGH) if (!Sensor::create(p[0], p[1], p[2])) return false; StringFormatter::send(stream, F("\n")); return true; case 1: // S id> remove sensor if (!Sensor::remove(p[0])) return false; StringFormatter::send(stream, F("\n")); return true; case 0: // list sensor definitions Sensor::dumpAll(stream); return true; default: // invalid number of arguments break; } return false; } bool DCCEXParser::parseC(Print *stream, int16_t params, int16_t p[]) { (void)stream; // arg not used, maybe later? if (params == 0) return false; switch (p[0]) { #ifndef DISABLE_PROG case "PROGBOOST"_hk: TrackManager::progTrackBoosted=true; return true; #endif case "RESET"_hk: DCCTimer::reset(); break; // and if we didnt restart case "SPEED28"_hk: DCC::setGlobalSpeedsteps(28); DIAG(F("28 Speedsteps")); return true; case "SPEED128"_hk: DCC::setGlobalSpeedsteps(128); DIAG(F("128 Speedsteps")); return true; #if defined(HAS_ENOUGH_MEMORY) && !defined(ARDUINO_ARCH_UNO) case "RAILCOM"_hk: { // if (params<2) return false; bool on=false; switch (p[1]) { case "ON"_hk: case 1: on=true; break; case "OFF"_hk: case 0: break; default: return false; } DIAG(F("Railcom %S") ,DCCWaveform::setRailcom(on)?F("ON"):F("OFF")); return true; } #endif #ifndef DISABLE_PROG case "ACK"_hk: // if (params >= 3) { long duration; if (p[1] == "LIMIT"_hk) { DCCACK::setAckLimit(p[2]); LCD(1, F("Ack Limit=%dmA"), p[2]); // } else if (p[1] == "MIN"_hk) { if (params == 4 && p[3] == "MS"_hk) duration = p[2] * 1000L; else duration = p[2]; DCCACK::setMinAckPulseDuration(duration); LCD(0, F("Ack Min=%lus"), duration); // } else if (p[1] == "MAX"_hk) { if (params == 4 && p[3] == "MS"_hk) // duration = p[2] * 1000L; else duration = p[2]; DCCACK::setMaxAckPulseDuration(duration); LCD(0, F("Ack Max=%lus"), duration); // } else if (p[1] == "RETRY"_hk) { if (p[2] >255) p[2]=3; LCD(0, F("Ack Retry=%d Sum=%d"), p[2], DCCACK::setAckRetry(p[2])); // } } else { bool onOff = (params > 0) && (p[1] == 1 || p[1] == "ON"_hk); // dont care if other stuff or missing... just means off DIAG(F("Ack diag %S"), onOff ? F("on") : F("off")); Diag::ACK = onOff; } return true; #endif default: // invalid/unknown break; } return false; } bool DCCEXParser::parseD(Print *stream, int16_t params, int16_t p[]) { if (params == 0) return false; bool onOff = (params > 0) && (p[1] == 1 || p[1] == "ON"_hk); // dont care if other stuff or missing... just means off switch (p[0]) { case "CABS"_hk: // DCC::displayCabList(stream); return true; case "RAM"_hk: // DIAG(F("Free memory=%d"), DCCTimer::getMinimumFreeMemory()); return true; case "CMD"_hk: // Diag::CMD = onOff; return true; #ifdef HAS_ENOUGH_MEMORY case "RAILCOM"_hk: // Diag::RAILCOM = onOff; return true; case "WIFI"_hk: // Diag::WIFI = onOff; return true; case "ETHERNET"_hk: // Diag::ETHERNET = onOff; return true; case "WIT"_hk: // Diag::WITHROTTLE = onOff; return true; case "LCN"_hk: // Diag::LCN = onOff; return true; case "SNIFFER"_hk: // Diag::SNIFFER = onOff; return true; case "WEBSOCKET"_hk: // Diag::WEBSOCKET = onOff; return true; #endif #ifndef DISABLE_EEPROM case "EEPROM"_hk: // if (params >= 2) EEStore::dump(p[1]); return true; #endif case "SERVO"_hk: // case "ANOUT"_hk: // IODevice::writeAnalogue(p[1], p[2], params>3 ? p[3] : 0); return true; case "ANIN"_hk: // Display analogue input value DIAG(F("VPIN=%u value=%d"), p[1], IODevice::readAnalogue(p[1])); return true; #if !defined(IO_NO_HAL) case "HAL"_hk: if (p[1] == "SHOW"_hk) { I2CManager.scanForDevices(&USB_SERIAL); IODevice::DumpAll(); } else if (p[1] == "RESET"_hk) IODevice::reset(); return true; #endif case "TT"_hk: // IODevice::writeAnalogue(p[1], p[2], params>3 ? p[3] : 0); return true; default: // invalid/unknown return parseC(stream, params, p); } return false; } // ========================== // Turntable - no support if no HAL // - list all // - broadcast type and current position // - create DCC - This is TBA // - operate (DCC) // - operate (EXTT) // - add position // - create EXTT #ifndef IO_NO_HAL bool DCCEXParser::parseI(Print *stream, int16_t params, int16_t p[]) { switch (params) { case 0: // list turntable objects return Turntable::printAll(stream); case 1: // broadcast type and current position { Turntable *tto = Turntable::get(p[0]); if (tto) { bool type = tto->isEXTT(); uint8_t position = tto->getPosition(); StringFormatter::send(stream, F("\n"), type, position); } else { return false; } } return true; case 2: // - rotate a DCC turntable { Turntable *tto = Turntable::get(p[0]); if (tto && !tto->isEXTT()) { if (!tto->setPosition(p[0], p[1])) return false; } else { return false; } } return true; case 3: // | - rotate to position for EX-Turntable or create DCC turntable { Turntable *tto = Turntable::get(p[0]); if (p[1] == "DCC"_hk) { if (tto || p[2] < 0 || p[2] > 3600) return false; if (!DCCTurntable::create(p[0])) return false; Turntable *tto = Turntable::get(p[0]); tto->addPosition(0, 0, p[2]); StringFormatter::send(stream, F("\n")); } else { if (!tto) return false; if (!tto->isEXTT()) return false; if (!tto->setPosition(p[0], p[1], p[2])) return false; } } return true; case 4: // create an EXTT turntable { Turntable *tto = Turntable::get(p[0]); if (p[1] == "EXTT"_hk) { if (tto || p[3] < 0 || p[3] > 3600) return false; if (!EXTTTurntable::create(p[0], (VPIN)p[2])) return false; Turntable *tto = Turntable::get(p[0]); tto->addPosition(0, 0, p[3]); StringFormatter::send(stream, F("\n")); } else { return false; } } return true; case 5: // add a position { Turntable *tto = Turntable::get(p[0]); if (p[1] == "ADD"_hk) { // tto must exist, no more than 48 positions, angle 0 - 3600 if (!tto || p[2] > 48 || p[4] < 0 || p[4] > 3600) return false; tto->addPosition(p[2], p[3], p[4]); StringFormatter::send(stream, F("\n")); } else { return false; } } return true; default: // Anything else is invalid return false; } } #endif bool DCCEXParser::parseJM(Print *stream, int16_t params, int16_t p[]) { switch (params) { case 1: // list all stashed automations Stash::list(stream); return true; case 2: // get stash value Stash::list(stream, p[1]); return true; case 3: // if (p[1]=="CLEAR"_hk) { if (p[2]=="ALL"_hk) { // Stash::clearAll(); return true; } Stash::clear(p[2]); // return true; } Stash::set(p[1], p[2]); // return true; case 4: // if (p[1]=="CLEAR"_hk && p[2]=="ANY"_hk) { // Stash::clearAny(p[3]); return true; } default: break; } return false; } // CALLBACKS must be static bool DCCEXParser::stashCallback(Print *stream, int16_t p[MAX_COMMAND_PARAMS], RingStream * ringStream) { if (stashBusy ) return false; stashBusy = true; stashStream = stream; stashRingStream=ringStream; if (ringStream) stashTarget= ringStream->peekTargetMark(); memcpy(stashP, p, MAX_COMMAND_PARAMS * sizeof(p[0])); return true; } Print * DCCEXParser::getAsyncReplyStream() { if (stashRingStream) { stashRingStream->mark(stashTarget); return stashRingStream; } return stashStream; } void DCCEXParser::commitAsyncReplyStream() { if (stashRingStream) stashRingStream->commit(); stashBusy = false; } void DCCEXParser::callback_W(int16_t result) { StringFormatter::send(getAsyncReplyStream(), F("\n"), stashP[0], result == 1 ? stashP[1] : -1); commitAsyncReplyStream(); } void DCCEXParser::callback_W4(int16_t result) { StringFormatter::send(getAsyncReplyStream(), F("\n"), stashP[2], stashP[3], stashP[0], result == 1 ? stashP[1] : -1); commitAsyncReplyStream(); } void DCCEXParser::callback_B(int16_t result) { StringFormatter::send(getAsyncReplyStream(), F("\n"), stashP[3], stashP[4], stashP[0], stashP[1], result == 1 ? stashP[2] : -1); commitAsyncReplyStream(); } void DCCEXParser::callback_Vbit(int16_t result) { StringFormatter::send(getAsyncReplyStream(), F("\n"), stashP[0], stashP[1], result); commitAsyncReplyStream(); } void DCCEXParser::callback_Vbyte(int16_t result) { StringFormatter::send(getAsyncReplyStream(), F("\n"), stashP[0], result); commitAsyncReplyStream(); } void DCCEXParser::callback_R(int16_t result) { StringFormatter::send(getAsyncReplyStream(), F("\n"), stashP[1], stashP[2], stashP[0], result); commitAsyncReplyStream(); } void DCCEXParser::callback_r(int16_t result) { StringFormatter::send(getAsyncReplyStream(), F("\n"), stashP[0], stashP[1], result); commitAsyncReplyStream(); } void DCCEXParser::callback_Rloco(int16_t result) { // determine type of \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("\n"); else detail=F("\n"); } StringFormatter::send(getAsyncReplyStream(), detail, typetag,result); commitAsyncReplyStream(); } void DCCEXParser::callback_Wloco(int16_t result) { if (result==1) result=stashP[0]; // pick up original requested id from command StringFormatter::send(getAsyncReplyStream(), F("\n"), result); commitAsyncReplyStream(); } void DCCEXParser::callback_Wconsist(int16_t result) { if (result==-4) DIAG(F("Long Consist %d not supported by decoder"),stashP[1]); if (result==1) result=stashP[1]; // pick up original requested id from command StringFormatter::send(getAsyncReplyStream(), F("\n"), result, stashP[2]=="REVERSE"_hk ? F(" REVERSE") : F("")); commitAsyncReplyStream(); } ================================================ FILE: DCCEXParser.h ================================================ /* * © 2021 Mike S * © 2021 Fred Decker * © 2020-2025 Chris Harlow * 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 . */ #ifndef DCCEXParser_h #define DCCEXParser_h #include #include "FSH.h" #include "RingStream.h" #include "defines.h" typedef void (*FILTER_CALLBACK)(Print * stream, byte & opcode, byte & paramCount, int16_t p[]); typedef void (*AT_COMMAND_CALLBACK)(HardwareSerial * stream,const byte * command); struct DCCEXParser { 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 setCamParserFilter(FILTER_CALLBACK filter); static void setAtCommandCallback(AT_COMMAND_CALLBACK filter); static const int MAX_COMMAND_PARAMS=10; // Must not exceed this static bool funcmap(int16_t cab, byte value, byte fstart, byte fstop); private: static const int16_t MAX_BUFFER=50; // longest command sent in static int16_t splitValues( int16_t result[MAX_COMMAND_PARAMS], byte * command, bool usehex); static bool parseT(Print * stream, int16_t params, int16_t p[]); static bool parseZ(Print * stream, int16_t params, int16_t p[]); static bool parsey(Print * stream, int16_t params, int16_t p[]); static bool parseS(Print * stream, int16_t params, int16_t p[]); static bool parsef(Print * stream, int16_t params, int16_t p[]); static bool parseC(Print * stream, int16_t params, int16_t p[]); static bool parseD(Print * stream, int16_t params, int16_t p[]); static bool parseJM(Print * stream, int16_t params, int16_t p[]); #ifndef IO_NO_HAL static bool parseI(Print * stream, int16_t params, int16_t p[]); #endif static Print * getAsyncReplyStream(); static void commitAsyncReplyStream(); static bool stashBusy; static byte stashTarget; static Print * stashStream; static RingStream * stashRingStream; static int16_t stashP[MAX_COMMAND_PARAMS]; 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); // prog static void callback_r(int16_t result); // main static void callback_Rloco(int16_t result); static void callback_Wloco(int16_t result); static void callback_Wconsist(int16_t result); static void callback_Vbit(int16_t result); static void callback_Vbyte(int16_t result); static FILTER_CALLBACK filterCallback; static FILTER_CALLBACK filterRMFTCallback; static FILTER_CALLBACK filterCamParserCallback; static AT_COMMAND_CALLBACK atCommandCallback; static void sendFlashList(Print * stream,const int16_t flashList[]); }; #endif ================================================ FILE: DCCPacket.h ================================================ /* * © 2025 Harald Barth * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #include #ifndef DCCPacket_h #define DCCPacket_h #include #include "defines.h" class DCCPacket { public: DCCPacket() { _len = 0; _data = NULL; }; DCCPacket(byte *d, byte l) { _len = l; _data = new byte[_len]; for (byte n = 0; n<_len; n++) _data[n] = d[n]; }; DCCPacket(const DCCPacket &old) { _len = old._len; _data = new byte[_len]; for (byte n = 0; n<_len; n++) _data[n] = old._data[n]; }; DCCPacket &operator=(const DCCPacket &rhs) { if (this == &rhs) return *this; delete[]_data; _len = rhs._len; _data = new byte[_len]; for (byte n = 0; n<_len; n++) _data[n] = rhs._data[n]; return *this; }; ~DCCPacket() { if (_len) { delete[]_data; _len = 0; _data = NULL; } }; inline bool operator==(const DCCPacket &right) { if (_len != right._len) return false; if (_len == 0) return true; return (bcmp(_data, right._data, _len) == 0); }; void print() { static const char hexchars[]="0123456789ABCDEF"; USB_SERIAL.print(F("<* DCCPACKET ")); for (byte n = 0; n< _len; n++) { USB_SERIAL.print(hexchars[_data[n]>>4]); USB_SERIAL.print(hexchars[_data[n] & 0x0f]); USB_SERIAL.print(' '); } USB_SERIAL.print(F("*>\n")); }; inline byte len() {return _len;}; inline byte *data() {return _data;}; private: byte _len = 0; byte *_data = NULL; }; #endif ================================================ FILE: DCCQueue.cpp ================================================ /* * © 2025 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 . */ /* What does this queue manager do: 1. It provides a high priority queue and a low priority queue. 2. It manages situations where multiple loco speed commands are in the queue. 3. It allows an ESTOP to jump the queue and eliminate any outstanding speed commands that would later undo the stop. 4. It allows for coil on/off accessory commands to be synchronized to a given time delay. 5. It prevents transmission of sequential packets to the same loco id */ #include "Arduino.h" #include "defines.h" #include "DCCQueue.h" #include "DCCWaveform.h" #include "DIAG.h" // create statics DCCQueue* DCCQueue::lowPriorityQueue=new DCCQueue(); DCCQueue* DCCQueue::highPriorityQueue=new DCCQueue(); PendingSlot* DCCQueue::recycleList=nullptr; uint16_t DCCQueue::lastSentPacketLocoId=0; // used to prevent two packets to the same loco in a row DCCQueue::DCCQueue() { head=nullptr; tail=nullptr; } void DCCQueue::addQueue(PendingSlot* p) { if (tail) tail->next=p; else head=p; tail=p; p->next=nullptr; } void DCCQueue::jumpQueue(PendingSlot* p) { p->next=head; head=p; if (!tail) tail=p; } void DCCQueue::recycle(PendingSlot* p) { p->next=recycleList; recycleList=p; } void DCCQueue::remove(PendingSlot* premove) { PendingSlot* previous=nullptr; for (auto p=head;p;previous=p,p=p->next) { if (p==premove) { // remove this slot from the queue if (previous) previous->next=p->next; else head=p->next; if (p==tail) tail=previous; // if last packet, update tail return; } } DIAG(F("DCCQueue::remove slot not found")); } // Packet joins end of low priority queue. void DCCQueue::scheduleDCCPacket(byte* packet, byte length, byte repeats, uint16_t loco) { lowPriorityQueue->addQueue(getSlot(NORMAL_PACKET,packet,length,repeats,loco)); } // Packet replaces existing loco speed packet or joins end of high priority queue. void DCCQueue::scheduleDCCSpeedPacket(byte* packet, byte length, byte repeats, uint16_t loco) { for (auto p=highPriorityQueue->head;p;p=p->next) { if (p->locoId==loco) { // replace existing packet memcpy(p->packet,packet,length); p->packetLength=length; p->packetRepeat=repeats; return; } } highPriorityQueue->addQueue(getSlot(SPEED_PACKET,packet,length,repeats,loco)); } // Packet replaces existing loco function packet or joins end of high priority queue. void DCCQueue::scheduleDCCFunctionPacket(byte* packet, byte length, uint16_t loco, byte group) { PendingType type=DEAD_PACKET; switch(group) { case 1: type=FUNCTION1_PACKET; break; case 2: type=FUNCTION2_PACKET; break; case 3: type=FUNCTION3_PACKET; break; case 4: type=FUNCTION4_PACKET; break; case 5: type=FUNCTION5_PACKET; break; default: DIAG(F("DCCQueue::scheduleDCCFunctionPacket invalid group %d"),group); return; // invalid group } for (auto p=lowPriorityQueue->head;p;p=p->next) { if (p->locoId==loco && p->type==type) { // replace existing packet for same loco and function group memcpy(p->packet,packet,length); p->packetLength=length; p->packetRepeat=0; return; } } lowPriorityQueue->addQueue(getSlot(type,packet,length,0,loco)); } // ESTOP - // any outstanding throttle packet for this loco (all if loco=0) discarded // Packet joins start of queue, void DCCQueue::scheduleEstopPacket(byte* packet, byte length, byte repeats,uint16_t loco) { // DIAG(F("DCC ESTOP loco=%d"),loco); // kill any existing throttle packets for this loco (or all locos if broadcast) // this will also remove any estop packets for this loco (or all locos if broadcast) but they will be replaced PendingSlot * pNext=nullptr; for (auto p=highPriorityQueue->head;p;p=pNext) { pNext=p->next; // save next packet in case we recycle this one if (p->type!=ACC_OFF_PACKET && (loco==0 || p->locoId==loco)) { // remove this slot from the queue or it will interfere with our ESTOP highPriorityQueue->remove(p); recycle(p); // recycle this slot } } // add the estop packet to the start of the queue highPriorityQueue->jumpQueue(getSlot(SPEED_PACKET,packet,length,repeats,0)); } // Accessory coil-On Packet joins end of queue as normal. // When dequeued, packet is retained at start of queue // but modified to coil-off and given the delayed start. // getNext will ignore this packet until the requested start time. void DCCQueue::scheduleAccOnOffPacket(byte* packet, byte length, byte repeats,int16_t delayms) { auto p=getSlot(ACC_ON_PACKET,packet,length,repeats,0); p->delayOff=delayms; lowPriorityQueue->addQueue(p); }; // Schedule the next dcc packet from the queues or an idle packet if none pending. const byte idlePacket[] = {0xFF, 0x00}; bool DCCQueue::scheduleNext(bool force) { if (highPriorityQueue->scheduleNextInternal()) return true; if (lowPriorityQueue->scheduleNextInternal()) return true; if (force) { // This will arise when there is nothing available to be sent that will not compromise the rules // typically this will only happen when there is only one loco in the reminders as the closely queued // speed and function reminders must be separated by at least one packet not sent to that loco. DCCWaveform::mainTrack.schedulePacket(idlePacket,sizeof(idlePacket),0); lastSentPacketLocoId=0; return true; } return false; } bool DCCQueue::scheduleNextInternal() { for (auto p=head;p;p=p->next) { // skip over pending ACC_OFF packets which are still delayed if (p->type == ACC_OFF_PACKET && millis()startTime) continue; if (p->locoId) { // Prevent two consecutive packets to the same loco. // this also means repeats cant be done by waveform if (p->locoId==lastSentPacketLocoId) continue; // try again later DCCWaveform::mainTrack.schedulePacket(p->packet,p->packetLength,0); lastSentPacketLocoId=p->locoId; if (p->packetRepeat) { p->packetRepeat--; return true; // leave this packet in the queue } } else { // Non loco packets can repeat automatically DCCWaveform::mainTrack.schedulePacket(p->packet,p->packetLength,p->packetRepeat); lastSentPacketLocoId=0; } // remove this slot from the queue remove(p); // special cases handling if (p->type == ACC_ON_PACKET) { // convert to a delayed off packet and jump the high priority queue p->type= ACC_OFF_PACKET; p->packet[1] &= ~0x08; // set C to 0 (gate off) p->startTime=millis()+p->delayOff; highPriorityQueue->jumpQueue(p); } else recycle(p); return true; } // No packets found return false; } // obtain and initialise slot for a PendingSlot. PendingSlot* DCCQueue::getSlot(PendingType type, byte* packet, byte length, byte repeats,uint16_t loco) { PendingSlot * p; if (recycleList) { p=recycleList; recycleList=p->next; } else { static int16_t created=0; int16_t q1=0; int16_t q2=0; for (auto p=highPriorityQueue->head;p;p=p->next) q1++; for (auto p=lowPriorityQueue->head;p;p=p->next) q2++; bool leak=(q1+q2)!=created; DIAG(F("New DCC queue slot type=%d length=%d loco=%d q1=%d q2=%d created=%d"), (int16_t)type,length,loco,q1,q2, created); if (leak) { for (auto p=highPriorityQueue->head;p;p=p->next) DIAG(F("q1 %d %d"),p->type,p->locoId); for (auto p=lowPriorityQueue->head;p;p=p->next) DIAG(F("q2 %d %d"),p->type,p->locoId); } p=new PendingSlot; // need a queue entry created++; } p->next=nullptr; p->type=type; p->packetLength=length; p->packetRepeat=repeats; if (length>sizeof(p->packet)) { DIAG(F("DCC bad packet length=%d"),length); length=sizeof(p->packet); // limit to size of packet } p->startTime=0; // not used for loco packets memcpy((void*)p->packet,packet,length); p->locoId=loco; return p; } ================================================ FILE: DCCQueue.h ================================================ /* * © 2025 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 . */ #ifndef DCCQueue_h #define DCCQueue_h #include "Arduino.h" #include "DCCWaveform.h" enum PendingType:byte {NORMAL_PACKET, FUNCTION1_PACKET, FUNCTION2_PACKET, FUNCTION3_PACKET, FUNCTION4_PACKET, FUNCTION5_PACKET, SPEED_PACKET,ACC_ON_PACKET,ACC_OFF_PACKET,DEAD_PACKET}; struct PendingSlot { PendingSlot* next; PendingType type; byte packetLength; byte packetRepeat; byte packet[MAX_PACKET_SIZE]; union { // use depends on packet type uint16_t locoId; // SPEED & FUNCTION packets uint16_t delayOff; // ACC_ON_PACKET delay to apply between on/off uint32_t startTime; // ACC_OFF_PACKET time (mS) to transmit }; }; class DCCQueue { public: // Non-speed packets are queued in the main queue static void scheduleDCCPacket(byte* packet, byte length, byte repeats, uint16_t loco=0); // Speed packets are queued in the high priority queue static void scheduleDCCSpeedPacket(byte* packet, byte length, byte repeats, uint16_t loco); // Function group packets are queued in the low priority queue static void scheduleDCCFunctionPacket(byte* packet, byte length, uint16_t loco, byte group); // ESTOP packets jump the high priority queue and discard any outstanding throttle packets for this loco static void scheduleEstopPacket(byte* packet, byte length, byte repeats,uint16_t loco); // Accessory gate-On Packet joins end of main queue as normal. // When dequeued, packet is modified to gate-off and given the delayed start in the high priority queue. // getNext will ignore this packet until the requested start time. static void scheduleAccOnOffPacket(byte* packet, byte length, byte repeats,int16_t delayms); // Schedules a main track packet from the queues. static bool scheduleNext(bool force); private: bool scheduleNextInternal(); // statics to manage high and low priority queues and recycleing of PENDINGs static PendingSlot* recycleList; static DCCQueue* highPriorityQueue; static DCCQueue* lowPriorityQueue; static uint16_t lastSentPacketLocoId; // used to prevent two packets to the same loco in a row DCCQueue(); PendingSlot* head; PendingSlot * tail; // obtain and initialise slot for a PendingSlot. static PendingSlot* getSlot(PendingType type, byte* packet, byte length, byte repeats, uint16_t loco); static void recycle(PendingSlot* p); void addQueue(PendingSlot * p); void jumpQueue(PendingSlot * p); void remove(PendingSlot * p); }; #endif // DCCQueue_h ================================================ FILE: DCCRMT.cpp ================================================ /* * © 2021-2024, Harald Barth. * * This file is part of DCC-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * RMT has "channels" which us FIFO RAM where you place what you want to send * or receive. Channels can be merged to get more words per channel. * * WROOM: 8 channels total of 512 words, 64 words per channel. We use currently * channel 0+1 for 128 words for DCC MAIN and 2+3 for DCC PROG. * * S3: 8 channels total of 384 words. 4 channels dedicated for TX and 4 channels * dedicated for RX. 48 words per channel. So for TX there are 4 channels and we * could use them with 96 words for MAIN and PROG if DCC data does fit in there. * * C3: 4 channels total of 192 words. As we do not use RX we can use all for TX * so the situation is the same as for the -S3 * * C6, H2: 4 channels total of 192 words. 2 channels dedictaed for TX and * 2 channels dedicated for RX. Half RMT capacity compared to the C3. * */ #if defined(ARDUINO_ARCH_ESP32) #include "defines.h" #include "DIAG.h" #include "DCCRMT.h" #include "DCCTimer.h" #include "DCCWaveform.h" // for MAX_PACKET_SIZE #include "soc/gpio_sig_map.h" // check for right type of ESP32 #include "soc/soc_caps.h" #ifndef SOC_RMT_MEM_WORDS_PER_CHANNEL #error This symobol should be defined #endif #if SOC_RMT_MEM_WORDS_PER_CHANNEL < 64 #warning This is not an ESP32-WROOM but some other unsupported variant #warning You are outside of the DCC-EX supported hardware #endif static const byte RMT_CHAN_PER_DCC_CHAN = 2; // Number of bits resulting out of X bytes of DCC payload data // Each byte has one bit extra and at the end we have one EOF marker #define DATA_LEN(X) ((X)*9+1) #if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(4,2,0) #error wrong IDF version #endif void setDCCBit1(rmt_item32_t* item) { item->level0 = 1; item->duration0 = DCC_1_HALFPERIOD; item->level1 = 0; item->duration1 = DCC_1_HALFPERIOD; } void setDCCBit0(rmt_item32_t* item) { item->level0 = 1; item->duration0 = DCC_0_HALFPERIOD; item->level1 = 0; item->duration1 = DCC_0_HALFPERIOD; } // special long zero to trigger scope void setDCCBit0Long(rmt_item32_t* item) { item->level0 = 1; item->duration0 = DCC_0_HALFPERIOD + DCC_0_HALFPERIOD/10; item->level1 = 0; item->duration1 = DCC_0_HALFPERIOD + DCC_0_HALFPERIOD/10; } void setEOT(rmt_item32_t* item) { item->val = 0; } // This is an array that contains the this pointers // to all uses channel objects. This is used to determine // which of the channels was triggering the ISR as there // is only ONE common ISR routine for all channels. RMTChannel *channelHandle[8] = { 0 }; void IRAM_ATTR interrupt(rmt_channel_t channel, void *t) { RMTChannel *tt = channelHandle[channel]; if (tt) tt->RMTinterrupt(); if (channel == 0) DCCTimer::updateMinimumFreeMemoryISR(0); } RMTChannel::RMTChannel(pinpair pins, bool isMain) { byte ch; byte plen; // Below we check if the DCC packet actually fits into the RMT hardware // Currently MAX_PACKET_SIZE = 5 so with checksum there are // MAX_PACKET_SIZE+1 data packets. Each need DATA_LEN (9) bits. // To that we add the preamble length, the fencepost DCC end bit // and the RMT EOF marker. // SOC_RMT_MEM_WORDS_PER_CHANNEL is either 64 (original WROOM) or // 48 (all other ESP32 like the -C3 or -S2 // The formula to get the possible MAX_PACKET_SIZE is // // ALLOCATED = RMT_CHAN_PER_DCC_CHAN * SOC_RMT_MEM_WORDS_PER_CHANNEL // MAX_PACKET_SIZE = floor((ALLOCATED - PREAMBLE_LEN - 2)/9 - 1) // if (isMain) { ch = 0; plen = PREAMBLE_BITS_MAIN; static_assert (DATA_LEN(MAX_PACKET_SIZE+1) + PREAMBLE_BITS_MAIN + 2 <= RMT_CHAN_PER_DCC_CHAN * SOC_RMT_MEM_WORDS_PER_CHANNEL, "Number of DCC packet bits greater than ESP32 RMT memory available"); } else { ch = RMT_CHAN_PER_DCC_CHAN; // number == offset plen = PREAMBLE_BITS_PROG; static_assert (DATA_LEN(MAX_PACKET_SIZE+1) + PREAMBLE_BITS_PROG + 2 <= RMT_CHAN_PER_DCC_CHAN * SOC_RMT_MEM_WORDS_PER_CHANNEL, "Number of DCC packet bits greater than ESP32 RMT memory available"); } // preamble preambleLen = plen+2; // plen 1 bits, one 0 bit and one EOF marker preamble = (rmt_item32_t*)malloc(preambleLen*sizeof(rmt_item32_t)); for (byte n=0; n 0) // we have still old work to do return dr; } 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 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 ================================================ FILE: DCCRMT.h ================================================ /* * © 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 . */ #if defined(ARDUINO_ARCH_ESP32) #pragma once #include #include "driver/rmt.h" #include "soc/rmt_reg.h" #include "soc/rmt_struct.h" #include "MotorDriver.h" // for class pinpair // make calculations easy and set up for microseconds #define RMT_CLOCK_DIVIDER 80 #define DCC_1_HALFPERIOD 58 //4640 // 1 / 80000000 * 4640 = 58us #define DCC_0_HALFPERIOD 100 //8000 class RMTChannel { public: RMTChannel(pinpair pins, bool isMain); bool addPin(byte pin, bool inverted=0); bool addPin(pinpair pins); void IRAM_ATTR RMTinterrupt(); void RMTprefill(); //int RMTfillData(dccPacket packet); int RMTfillData(const byte buffer[], byte byteCount, byte repeatCount); inline bool busy() { if (dataRepeat > 0) // we have still old work to do return true; return dataReady; }; inline void waitForDataCopy() { while(1) { // do nothing and wait for interrupt clearing dataReady to happen if (dataReady == false) break; } }; inline uint32_t packetCount() { return packetCounter; }; private: rmt_channel_t channel; // 3 types of data to send, preamble and then idle or data // if this is prog track, idle will contain reset instead rmt_item32_t *idle; byte idleLen; rmt_item32_t *preamble; byte preambleLen; rmt_item32_t *data; byte dataLen; byte maxDataLen; uint32_t packetCounter = 0; // flags volatile bool dataReady = false; // do we have real data available or send idle volatile byte dataRepeat = 0; }; #endif //ESP32 ================================================ FILE: DCCTimer.h ================================================ /* * © 2022-2024 Paul M. Antoine * © 2021 Mike S * © 2021-2023 Harald Barth * © 2021 Fred Decker * All rights reserved. * * This file is part of CommandStation-EX * * 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 . */ /* 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" typedef void (*INTERRUPT_CALLBACK)(); class DCCTimer { public: static void begin(INTERRUPT_CALLBACK interrupt); static void getSimulatedMacAddress(byte mac[6]); static bool isPWMPin(byte pin); static void setPWM(byte pin, bool high); static void clearPWM(); static void startRailcomTimer(byte brakePin); static void ackRailcomTimer(); static void DCCEXanalogWriteFrequency(uint8_t pin, uint32_t frequency); static void DCCEXanalogWrite(uint8_t pin, int value, bool invert); static void DCCEXledcDetachPin(uint8_t pin); static void DCCEXanalogCopyChannel(int8_t frompin, int8_t topin); static void DCCEXInrushControlOn(uint8_t pin, int duty, bool invert); static void DCCEXledcAttachPin(uint8_t pin, int8_t channel, bool inverted); // Update low ram level. Allow for extra bytes to be specified // by estimation or inspection, that may be used by other // called subroutines. Must be called with interrupts disabled. // // Although __brkval may go up and down as heap memory is allocated // and freed, this function records only the worst case encountered. // So even if all of the heap is freed, the reported minimum free // memory will not increase. // static void inline updateMinimumFreeMemoryISR(unsigned char extraBytes=0) __attribute__((always_inline)) { int spare = freeMemory()-extraBytes; if (spare < 0) spare = 0; if (spare < minimum_free_memory) minimum_free_memory = spare; }; static int getMinimumFreeMemory(); static void reset(); private: static void DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t frequency); static int freeMemory(); static volatile int minimum_free_memory; static const int DCC_SIGNAL_TIME=58; // this is the 58uS DCC 1-bit waveform half-cycle #if defined(ARDUINO_ARCH_STM32) // TODO: PMA temporary hack - assumes 100Mhz F_CPU as STM32 can change frequency static const long CLOCK_CYCLES=(100000000L / 1000000 * DCC_SIGNAL_TIME) >>1; #else static const long CLOCK_CYCLES=(F_CPU / 1000000 * DCC_SIGNAL_TIME) >>1; #endif }; // Class ADCee implements caching of the ADC value for platforms which // have a too slow ADC read to wait for. On these platforms the ADC is // scanned continiously in the background from an ISR. On such // architectures that use the analog read during DCC waveform with // specially configured ADC, for example AVR, init must be called // PRIOR to the start of the waveform. It returns the current value so // that an offset can be initialized. class ADCee { public: // begin is called for any setup that must be done before // **init** can be called. On some architectures this involves ADC // initialisation and clock routing, sampling times etc. static void begin(); // init adds the pin to the list of scanned pins (if this // platform's implementation scans pins) and returns the first // read value (which is why it required begin to have been called first!) // It must be called before the regular scan is started. static int init(uint8_t pin); // read does read the pin value from the scanned cache or directly // if this is a platform that does not scan. fromISR is a hint if // it was called from ISR because for some implementations that // makes a difference. static int read(uint8_t pin, bool fromISR=false); // returns possible max value that the ADC can return static int16_t ADCmax(); private: // On platforms that scan, it is called from waveform ISR // only on a regular basis. static void scan(); #if defined (ARDUINO_ARCH_STM32) // bit array of used pins (max 32) static uint32_t usedpins; static uint32_t * analogchans; // Array of channel numbers to be scanned static ADC_TypeDef * * adcchans; // Array to capture which ADC is each input channel on #else // bit array of used pins (max 16) static uint16_t usedpins; #endif static uint8_t highestPin; // cached analog values (malloc:ed to actual number of ADC channels) static int *analogvals; // friend so that we can call scan() and begin() friend class DCCWaveform; }; #endif ================================================ FILE: DCCTimerAVR.cpp ================================================ /* * © 2021 Mike S * © 2021-2023 Harald Barth * © 2021 Fred Decker * © 2021-2025 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 . */ // 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 #include #include "DCCTimer.h" #include "DIAG.h" #ifdef DEBUG_ADC #include "TrackManager.h" #endif INTERRUPT_CALLBACK interruptHandler=0; // Arduino nano, uno, mega etc #if defined(__AVR_ATmega1280__) || defined(__AVR_ATmega2560__) #define TIMER1_A_PIN 11 #define TIMER1_B_PIN 12 #define TIMER1_C_PIN 13 #define TIMER2_A_PIN 10 #define TIMER2_B_PIN 9 #else #define TIMER1_A_PIN 9 #define TIMER1_B_PIN 10 #endif void DCCTimer::begin(INTERRUPT_CALLBACK callback) { interruptHandler=callback; noInterrupts(); TCCR1A = 0; ICR1 = CLOCK_CYCLES; TCNT1 = 0; TCCR1B = _BV(WGM13) | _BV(CS10); // Mode 8, clock select 1 TIMSK1 = _BV(TOIE1); // Enable Software interrupt interrupts(); //diagnostic pinMode(4,OUTPUT); } void DCCTimer::startRailcomTimer(byte brakePin) { (void) brakePin; // Ignored... works on pin 9 only // diagnostic digitalWrite(4,HIGH); /* The Railcom timer is started in such a way that it - First triggers a calculated time after the previous TIMER1 tick. This provides an accurate offset (in High Accuracy mode) for the start of the Railcom cutout. The delayBeforeCutout value reflects that this call is made at the start of the end-packet bit thus the delay is nominally 58+58+Tcs BUT in HA mode, the dcc pin is flipped at the NEXT interrupt so runs 1 tick behind the code. Thus an extra 58uS is needed. - Timer2 Sets the Railcom pin high at first tick and subsequent ticks until its reset to setting pin 9 low at next tick. - Cycles at cutoutDuration so the second tick is the correct distance from the cutout. - Waveform code is responsible for resetting any time between the first and second tick. (there will be 7 DCC timer1 ticks in which to do this.) */ const int Tcs=28; // NMRA spec is 26..32 const int cutoutDuration_uS = 450; // As chosen by most const uint16_t delayBeforeCutout_uS=58+58+58+Tcs; const uint16_t timer1_ticks_per_uS = 8; const uint16_t timer2_uS_per_tick = 2; // Set Timer2 to CTC mode with set on compare match TCCR2A = (1 << WGM21) | (1 << COM2B0) | (1 << COM2B1); // Prescaler of 32 TCCR2B = (1 << CS21) | (1 << CS20); OCR2A = cutoutDuration_uS/timer2_uS_per_tick; // Compare match value for cutout duration in timer2 ticks (2uSec) // Enable Timer2 output on pin 9 (OC2B) DDRB |= (1 << DDB1); // timeSlip is the expired time since the DCC timer interrupt that triggered this call. // This allows us to cope with any delays between the interrupt and this code executing. noInterrupts(); // Time already used since DCC interrupt uint16_t timeSlip_uS=TCNT1/timer1_ticks_per_uS; // Calculate the time left before the cutout is to be triggered uint16_t timeToCutout_uS=cutoutDuration_uS+timeSlip_uS-delayBeforeCutout_uS; // Adjust clock2 to trigger on time TCNT2=timeToCutout_uS/timer2_uS_per_tick; interrupts(); } void DCCTimer::ackRailcomTimer() { // Change Timer2 to CTC mode with RESET pin 9 on next compare match TCCR2A = (1 << WGM21) | (1 << COM2B1); } // ISR called by timer interrupt every 58uS ISR(TIMER1_OVF_vect){ interruptHandler(); } // Alternative pin manipulation via PWM control. bool DCCTimer::isPWMPin(byte pin) { return pin==TIMER1_A_PIN || pin==TIMER1_B_PIN #ifdef TIMER1_C_PIN || pin==TIMER1_C_PIN #endif ; } void DCCTimer::setPWM(byte pin, bool high) { if (pin==TIMER1_A_PIN) { TCCR1A |= _BV(COM1A1); OCR1A= high?1024:0; } else if (pin==TIMER1_B_PIN) { TCCR1A |= _BV(COM1B1); OCR1B= high?1024:0; } #ifdef TIMER1_C_PIN else if (pin==TIMER1_C_PIN) { TCCR1A |= _BV(COM1C1); OCR1C= high?1024:0; } #endif } void DCCTimer::clearPWM() { TCCR1A= 0; } void DCCTimer::getSimulatedMacAddress(byte mac[6]) { for (byte i=0; i<6; i++) { // take the fist 3 and last 3 of the serial. // the first 5 of 8 are at 0x0E to 0x013 // the last 3 of 8 are at 0x15 to 0x017 mac[i]=boot_signature_byte_get(0x0E + i + (i>2? 4 : 0)); } mac[0] &= 0xFE; mac[0] |= 0x02; } volatile int DCCTimer::minimum_free_memory=__INT_MAX__; // Return low memory value... int DCCTimer::getMinimumFreeMemory() { noInterrupts(); // Disable interrupts to get volatile value int retval = minimum_free_memory; interrupts(); return retval; } extern char *__brkval; extern char *__malloc_heap_start; int DCCTimer::freeMemory() { char top; return __brkval ? &top - __brkval : &top - __malloc_heap_start; } void DCCTimer::reset() { // 250ms chosen to circumwent bootloader bug which // hangs at too short timepout (like 15ms) wdt_enable( WDTO_250MS); // set Arduino watchdog timer for 250ms delay(500); // wait for it to happen } void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) { DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, f); } void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t fbits) { #if defined(ARDUINO_AVR_UNO) (void)fbits; (void) pin; // Not worth doin something here as: // If we are on pin 9 or 10 we are on Timer1 and we can not touch Timer1 as that is our DCC source. // If we are on pin 5 or 6 we are on Timer 0 ad we can not touch Timer0 as that is millis() etc. // We are most likely not on pin 3 or 11 as no known motor shield has that as brake. #endif #if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560) // Speed mapping is done like this: // No functions buttons: 000 0 -> low 131Hz // Only F29 pressed 001 1 -> mid 490Hz // F30 with or w/o F29 01x 2-3 -> high 3400Hz // F31 with or w/o F29/30 1xx 4-7 -> supersonic 62500Hz uint8_t abits; uint8_t bbits; if (pin == 9 || pin == 10) { // timer 2 is different if (fbits >= 4) abits = B00000011; else abits = B00000001; if (fbits >= 4) bbits = B0001; else if (fbits >= 2) bbits = B0010; else if (fbits == 1) bbits = B0100; else // fbits == 0 bbits = B0110; TCCR2A = (TCCR2A & B11111100) | abits; // set WGM0 and WGM1 TCCR2B = (TCCR2B & B11110000) | bbits; // set WGM2 and 3 bits of prescaler DIAG(F("Timer 2 A=%x B=%x"), TCCR2A, TCCR2B); } else { // not timer 9 or 10 abits = B01; if (fbits >= 4) bbits = B1001; else if (fbits >= 2) bbits = B0010; else if (fbits == 1) bbits = B0011; else bbits = B0100; switch (pin) { // case 9 and 10 taken care of above by if() case 6: case 7: case 8: // Timer4 TCCR4A = (TCCR4A & B11111100) | abits; // set WGM0 and WGM1 TCCR4B = (TCCR4B & B11100000) | bbits; // set WGM2 and WGM3 and divisor //DIAG(F("Timer 4 A=%x B=%x"), TCCR4A, TCCR4B); break; case 46: case 45: case 44: // Timer5 TCCR5A = (TCCR5A & B11111100) | abits; // set WGM0 and WGM1 TCCR5B = (TCCR5B & B11100000) | bbits; // set WGM2 and WGM3 and divisor //DIAG(F("Timer 5 A=%x B=%x"), TCCR5A, TCCR5B); break; default: break; } } #endif } #if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560) #define NUM_ADC_INPUTS 16 #else #define NUM_ADC_INPUTS 8 #endif uint16_t ADCee::usedpins = 0; uint8_t ADCee::highestPin = 0; int * ADCee::analogvals = NULL; static bool ADCusesHighPort = false; /* * Register a new pin to be scanned * Returns current reading of pin and * stores that as well */ int ADCee::init(uint8_t pin) { uint8_t id = pin - A0; if (id >= NUM_ADC_INPUTS) return -1023; if (id > 7) ADCusesHighPort = true; pinMode(pin, INPUT); int value = analogRead(pin); if (analogvals == NULL) analogvals = (int *)calloc(NUM_ADC_INPUTS, sizeof(int)); analogvals[id] = value; usedpins |= (1< highestPin) highestPin = id; return value; } int16_t ADCee::ADCmax() { return 1023; } /* * Read function ADCee::read(pin) to get value instead of analogRead(pin) */ int ADCee::read(uint8_t pin, bool fromISR) { uint8_t id = pin - A0; if ((usedpins & (1<setBrake(0); #endif waiting = false; id++; mask = mask << 1; if (id > highestPin) { id = 0; mask = 1; } } if (!waiting) { if (usedpins == 0) // otherwise we would loop forever return; // look for a valid track to sample or until we are around while (true) { if (mask & usedpins) { // start new ADC aquire on id #if defined(ADCSRB) && defined(MUX5) if (ADCusesHighPort) { // if we ever have started to use high pins) if (id > 7) // if we use a high ADC pin bitSet(ADCSRB, MUX5); // set MUX5 bit else bitClear(ADCSRB, MUX5); } #endif ADMUX=(1<setBrake(1); #endif waiting = true; return; } id++; mask = mask << 1; if (id > highestPin) { id = 0; mask = 1; } } } } #pragma GCC pop_options void ADCee::begin() { noInterrupts(); // ADCSRA = (ADCSRA & 0b11111000) | 0b00000100; // speed up analogRead sample time // Set up ADC for free running mode ADMUX=(1<. */ // ATTENTION: this file only compiles on an ESP8266 and ESP32 // On ESP32 we do not even use the functions but they are here for completeness sake // Please refer to DCCTimer.h for general comments about how this class works // This is to avoid repetition and duplication. #ifdef ARDUINO_ARCH_ESP8266 #include "DCCTimer.h" INTERRUPT_CALLBACK interruptHandler=0; void DCCTimer::begin(INTERRUPT_CALLBACK callback) { interruptHandler=callback; timer1_disable(); // There seem to be differnt ways to attach interrupt handler // ETS_FRC_TIMER1_INTR_ATTACH(NULL, NULL); // ETS_FRC_TIMER1_NMI_INTR_ATTACH(interruptHandler); // Let us choose the one from the API timer1_attachInterrupt(interruptHandler); // not exactly sure of order: timer1_enable(TIM_DIV1, TIM_EDGE, TIM_LOOP); timer1_write(CLOCK_CYCLES); } // We do not support to use PWM to make the Waveform on ESP bool IRAM_ATTR DCCTimer::isPWMPin(byte pin) { return false; } void IRAM_ATTR DCCTimer::setPWM(byte pin, bool high) { } void IRAM_ATTR DCCTimer::clearPWM() { } // Fake this as it should not be used void DCCTimer::getSimulatedMacAddress(byte mac[6]) { mac[0] = 0xFE; mac[1] = 0xBE; mac[2] = 0xEF; mac[3] = 0xC0; mac[4] = 0xFF; mac[5] = 0xEE; } volatile int DCCTimer::minimum_free_memory=__INT_MAX__; // Return low memory value... int DCCTimer::getMinimumFreeMemory() { noInterrupts(); // Disable interrupts to get volatile value int retval = minimum_free_memory; interrupts(); return retval; } int DCCTimer::freeMemory() { return ESP.getFreeHeap(); } #endif //////////////////////////////////////////////////////////////////////// #ifdef ARDUINO_ARCH_ESP32 #if __has_include("esp_idf_version.h") #include "esp_idf_version.h" #endif #if ESP_IDF_VERSION_MAJOR == 4 // all well correct IDF version #else #error "DCC-EX does not support compiling with IDF version 5.0 or later. Downgrade your ESP32 library to a version that contains IDF version 4. Arduino ESP32 library 3.0.0 is too new. Downgrade to one of 2.0.9 to 2.0.17" #endif // protect all the rest of the code from IDF version 5 #if ESP_IDF_VERSION_MAJOR == 4 #include "DIAG.h" #include #include #include #undef ADC_INPUT_MAX_VALUE #define ADC_INPUT_MAX_VALUE 4095 // 12 bit ADC #define pinToADC1Channel(X) (adc1_channel_t)(((X) > 35) ? (X)-36 : (X)-28) int IRAM_ATTR local_adc1_get_raw(int channel) { uint16_t adc_value; SENS.sar_meas_start1.sar1_en_pad = (1 << channel); // only one channel is selected while (SENS.sar_slave_addr1.meas_status != 0); SENS.sar_meas_start1.meas1_start_sar = 0; SENS.sar_meas_start1.meas1_start_sar = 1; while (SENS.sar_meas_start1.meas1_done_sar == 0); adc_value = SENS.sar_meas_start1.meas1_data_sar; return adc_value; } #include "DCCTimer.h" INTERRUPT_CALLBACK interruptHandler=0; // https://www.visualmicro.com/page/Timer-Interrupts-Explained.aspx portMUX_TYPE timerMux = portMUX_INITIALIZER_UNLOCKED; void DCCTimer::begin(INTERRUPT_CALLBACK callback) { // This should not be called on ESP32 so disable it return; interruptHandler = callback; hw_timer_t *timer = NULL; timer = timerBegin(0, 2, true); // prescaler can be 2 to 65536 so choose 2 timerAttachInterrupt(timer, interruptHandler, true); timerAlarmWrite(timer, CLOCK_CYCLES / 6, true); // divide by prescaler*3 (Clockbase is 80Mhz and not F_CPU 240Mhz) timerAlarmEnable(timer); } // We do not support to use PWM to make the Waveform on ESP bool IRAM_ATTR DCCTimer::isPWMPin(byte pin) { return false; } void IRAM_ATTR DCCTimer::setPWM(byte pin, bool high) { } void IRAM_ATTR DCCTimer::clearPWM() { } // Fake this as it should not be used void DCCTimer::getSimulatedMacAddress(byte mac[6]) { mac[0] = 0xFE; mac[1] = 0xBE; mac[2] = 0xEF; mac[3] = 0xC0; mac[4] = 0xFF; mac[5] = 0xEE; } volatile int DCCTimer::minimum_free_memory=__INT_MAX__; // Return low memory value... int DCCTimer::getMinimumFreeMemory() { noInterrupts(); // Disable interrupts to get volatile value int retval = minimum_free_memory; interrupts(); return retval; } int DCCTimer::freeMemory() { return ESP.getFreeHeap(); } void DCCTimer::reset() { ESP.restart(); } void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) { if (f >= 16) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, f); /* else if (f == 7) // not used on ESP32 DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 62500); */ else if (f >= 4) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 32000); else if (f >= 3) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 16000); else if (f >= 2) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 3400); else if (f == 1) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 480); else DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 131); } #include "esp32-hal.h" #include "soc/soc_caps.h" #ifdef SOC_LEDC_SUPPORT_HS_MODE #define LEDC_CHANNELS (SOC_LEDC_CHANNEL_NUM<<1) #else #define LEDC_CHANNELS (SOC_LEDC_CHANNEL_NUM) #endif static int8_t pin_to_channel[SOC_GPIO_PIN_COUNT] = { 0 }; static int cnt_channel = LEDC_CHANNELS; void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t frequency) { if (pin < SOC_GPIO_PIN_COUNT) { if (pin_to_channel[pin] != 0) { ledcSetup(pin_to_channel[pin], frequency, 8); } } } void DCCTimer::DCCEXledcDetachPin(uint8_t pin) { #ifdef DIAG_IO DIAG(F("Clear pin %d from ledc channel"), pin); #endif pin_to_channel[pin] = 0; pinMatrixOutDetach(pin, false, false); } static byte LEDCToMux[] = { LEDC_HS_SIG_OUT0_IDX, LEDC_HS_SIG_OUT1_IDX, LEDC_HS_SIG_OUT2_IDX, LEDC_HS_SIG_OUT3_IDX, LEDC_HS_SIG_OUT4_IDX, LEDC_HS_SIG_OUT5_IDX, LEDC_HS_SIG_OUT6_IDX, LEDC_HS_SIG_OUT7_IDX, LEDC_LS_SIG_OUT0_IDX, LEDC_LS_SIG_OUT1_IDX, LEDC_LS_SIG_OUT2_IDX, LEDC_LS_SIG_OUT3_IDX, LEDC_LS_SIG_OUT4_IDX, LEDC_LS_SIG_OUT5_IDX, LEDC_LS_SIG_OUT6_IDX, LEDC_LS_SIG_OUT7_IDX, }; void DCCTimer::DCCEXledcAttachPin(uint8_t pin, int8_t channel, bool inverted) { DIAG(F("Attaching pin %d to channel %d %c"), pin, channel, inverted ? 'I' : ' '); ledcAttachPin(pin, channel); if (inverted) // we attach again but with inversion gpio_matrix_out(pin, LEDCToMux[channel], inverted, 0); } void DCCTimer::DCCEXanalogCopyChannel(int8_t frompin, int8_t topin) { // arguments are signed depending on inversion of pins DIAG(F("Pin %d copied to %d"), frompin, topin); bool inverted = false; if (frompin<0) frompin = -frompin; if (topin<0) { inverted = true; topin = -topin; } int channel = pin_to_channel[frompin]; // after abs(frompin) pin_to_channel[topin] = channel; DCCTimer::DCCEXledcAttachPin(topin, channel, inverted); } void DCCTimer::DCCEXanalogWrite(uint8_t pin, int value, bool invert) { // This allocates channels 15, 13, 11, .... // so each channel gets its own timer. if (pin < SOC_GPIO_PIN_COUNT) { if (pin_to_channel[pin] == 0) { int search_channel; int n; if (!cnt_channel) { log_e("No more PWM channels available! All %u already used", LEDC_CHANNELS); return; } // search for free channels top down for (search_channel=LEDC_CHANNELS-1; search_channel >=cnt_channel; search_channel -= 2) { bool chanused = false; for (n=0; n < SOC_GPIO_PIN_COUNT; n++) { if (pin_to_channel[n] == search_channel) { // current search_channel used chanused = true; break; } } if (chanused) continue; if (n == SOC_GPIO_PIN_COUNT) // current search_channel unused break; } if (search_channel >= cnt_channel) { pin_to_channel[pin] = search_channel; DIAG(F("Pin %d assigned to search channel %d"), pin, search_channel); } else { pin_to_channel[pin] = --cnt_channel; // This sets 15, 13, ... DIAG(F("Pin %d assigned to new channel %d"), pin, cnt_channel); --cnt_channel; // Now we are at 14, 12, ... } ledcSetup(pin_to_channel[pin], 1000, 8); DCCEXledcAttachPin(pin, pin_to_channel[pin], invert); } else { // This else is only here so we can enable diag // Pin should be already attached to channel // DIAG(F("Pin %d assigned to old channel %d"), pin, pin_to_channel[pin]); } ledcWrite(pin_to_channel[pin], value); } } void DCCTimer::DCCEXInrushControlOn(uint8_t pin, int duty, bool inverted) { // this uses hardcoded channel 0 ledcSetup(0, 62500, 8); DCCEXledcAttachPin(pin, 0, inverted); ledcWrite(0, duty); } int ADCee::init(uint8_t pin) { pinMode(pin, ANALOG); adc1_config_width(ADC_WIDTH_BIT_12); // Espressif deprecated ADC_ATTEN_DB_11 somewhere between 2.0.9 and 2.0.17 #ifdef ADC_ATTEN_11db adc1_config_channel_atten(pinToADC1Channel(pin),ADC_ATTEN_11db); #else adc1_config_channel_atten(pinToADC1Channel(pin),ADC_ATTEN_DB_11); #endif return adc1_get_raw(pinToADC1Channel(pin)); } int16_t ADCee::ADCmax() { return 4095; } /* * Read function ADCee::read(pin) to get value instead of analogRead(pin) */ int ADCee::read(uint8_t pin, bool fromISR) { return local_adc1_get_raw(pinToADC1Channel(pin)); } /* * Scan function that is called from interrupt */ void ADCee::scan() { } void ADCee::begin() { } #endif //IDF v4 #endif //ESP32 ================================================ FILE: DCCTimerMEGAAVR.cpp ================================================ /* * © 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 . */ /* This timer class is used to manage the single timer required to handle the DCC waveform. * All timer access comes through this class so that it can be compiled for * various hardware CPU types. * * DCCEX works on a single timer interrupt at a regular 58uS interval. * The DCCWaveform class generates the signals to the motor shield * based on this timer. * * If the motor drivers are BOTH configured to use the correct 2 pins for the architecture, * (see isPWMPin() function. ) * then this allows us to use a hardware driven pin switching arrangement which is * achieved by setting the duty cycle of the NEXT clock interrupt to 0% or 100% depending on * the required pin state. (see setPWM()) * This is more accurate than the software interrupt but at the expense of * limiting the choice of available pins. * Fortunately, a standard motor shield on a Mega uses pins that qualify for PWM... * Other shields may be jumpered to PWM pins or run directly using the software interrupt. * * Because the PWM-based waveform is effectively set half a cycle after the software version, * it is not acceptable to drive the two tracks on different methiods or it would cause * problems for <1 JOIN> etc. * */ // ATTENTION: this file only compiles on a UnoWifiRev3 or NanoEvery // Please refer to DCCTimer.h for general comments about how this class works // This is to avoid repetition and duplication. #ifdef ARDUINO_ARCH_MEGAAVR #include "DCCTimer.h" INTERRUPT_CALLBACK interruptHandler=0; extern char *__brkval; extern char *__malloc_heap_start; void DCCTimer::begin(INTERRUPT_CALLBACK callback) { interruptHandler=callback; noInterrupts(); ADC0.CTRLC = (ADC0.CTRLC & 0b00110000) | 0b01000011; // speed up analogRead sample time TCB0.CTRLB = TCB_CNTMODE_INT_gc & ~TCB_CCMPEN_bm; // timer compare mode with output disabled TCB0.CTRLA = TCB_CLKSEL_CLKDIV2_gc; // 8 MHz ~ 0.125 us TCB0.CCMP = CLOCK_CYCLES -1; // 1 tick less for timer reset TCB0.INTFLAGS = TCB_CAPT_bm; // clear interrupt request flag TCB0.INTCTRL = TCB_CAPT_bm; // Enable the interrupt TCB0.CNT = 0; TCB0.CTRLA |= TCB_ENABLE_bm; // start interrupts(); } // ISR called by timer interrupt every 58uS ISR(TCB0_INT_vect){ TCB0.INTFLAGS = TCB_CAPT_bm; // Clear interrupt request flag interruptHandler(); } void DCCTimer::startRailcomTimer(byte brakePin) { // TODO: for intended operation see DCCTimerAVR.cpp (void) brakePin; } void DCCTimer::ackRailcomTimer() { // TODO: for intended operation see DCCTimerAVR.cpp } bool DCCTimer::isPWMPin(byte pin) { (void) pin; return false; // TODO what are the relevant pins? } void DCCTimer::setPWM(byte pin, bool high) { (void) pin; (void) high; // TODO what are the relevant pins? } void DCCTimer::clearPWM() { // Do nothing unless we implent HA } void DCCTimer::getSimulatedMacAddress(byte mac[6]) { memcpy(mac,(void *) &SIGROW.SERNUM0,6); // serial number mac[0] &= 0xFE; mac[0] |= 0x02; } volatile int DCCTimer::minimum_free_memory=__INT_MAX__; // Return low memory value... int DCCTimer::getMinimumFreeMemory() { noInterrupts(); // Disable interrupts to get volatile value int retval = minimum_free_memory; interrupts(); return retval; } extern char *__brkval; extern char *__malloc_heap_start; int DCCTimer::freeMemory() { char top; return __brkval ? &top - __brkval : &top - __malloc_heap_start; } void DCCTimer::reset() { CPU_CCP=0xD8; WDT.CTRLA=0x4; while(true){} } void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) { } void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t fbits) { } int16_t ADCee::ADCmax() { return 4095; } int ADCee::init(uint8_t pin) { return analogRead(pin); } /* * Read function ADCee::read(pin) to get value instead of analogRead(pin) */ int ADCee::read(uint8_t pin, bool fromISR) { int current; if (!fromISR) noInterrupts(); current = analogRead(pin); if (!fromISR) interrupts(); return current; } /* * Scan function that is called from interrupt */ void ADCee::scan() { } void ADCee::begin() { noInterrupts(); interrupts(); } #endif ================================================ FILE: DCCTimerSAMD.cpp ================================================ /* * © 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 . */ // 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 INTERRUPT_CALLBACK interruptHandler=0; void DCCTimer::begin(INTERRUPT_CALLBACK callback) { interruptHandler=callback; noInterrupts(); // Timer setup - setup clock sources first REG_GCLK_GENDIV = GCLK_GENDIV_DIV(1) | // Divide 48MHz by 1 GCLK_GENDIV_ID(4); // Apply to GCLK4 while (GCLK->STATUS.bit.SYNCBUSY); // Wait for synchronization REG_GCLK_GENCTRL = GCLK_GENCTRL_GENEN | // Enable GCLK GCLK_GENCTRL_SRC_DFLL48M | // Set the 48MHz clock source GCLK_GENCTRL_ID(4); // Select GCLK4 while (GCLK->STATUS.bit.SYNCBUSY); // Wait for synchronization REG_GCLK_CLKCTRL = GCLK_CLKCTRL_CLKEN | // Enable generic clock 4 << GCLK_CLKCTRL_GEN_Pos | // Apply to GCLK4 GCLK_CLKCTRL_ID_TCC0_TCC1; // Feed GCLK to TCC0/1 while (GCLK->STATUS.bit.SYNCBUSY); // Assume we're using TCC0... as we're bit-bashing the DCC waveform output pins anyway // for "normal accuracy" DCC waveform generation. For high accuracy we're going to need // to a good deal more. The TCC waveform output pins are mux'd on the SAMD, and output // pins for each TCC are only available on certain pins TCC0->WAVE.reg = TCC_WAVE_WAVEGEN_NPWM; // Select NPWM as waveform while (TCC0->SYNCBUSY.bit.WAVE); // Wait for sync // Set the frequency TCC0->CTRLA.reg |= TCC_CTRLA_PRESCALER(TCC_CTRLA_PRESCALER_DIV1_Val); TCC0->PER.reg = CLOCK_CYCLES * 2; while (TCC0->SYNCBUSY.bit.PER); // Start the timer TCC0->CTRLA.bit.ENABLE = 1; while (TCC0->SYNCBUSY.bit.ENABLE); // Set the interrupt condition, priority and enable it in the NVIC TCC0->INTENSET.reg = TCC_INTENSET_OVF; // Only interrupt on overflow int USBprio = NVIC_GetPriority((IRQn_Type) USB_IRQn); // Fetch the USB priority NVIC_SetPriority((IRQn_Type)TCC0_IRQn, USBprio); // Match the USB priority // NVIC_SetPriority((IRQn_Type)TCC0_IRQn, 0); // Make this highest priority NVIC_EnableIRQ((IRQn_Type)TCC0_IRQn); // Enable the interrupt interrupts(); } void DCCTimer::startRailcomTimer(byte brakePin) { // TODO: for intended operation see DCCTimerAVR.cpp (void) brakePin; } void DCCTimer::ackRailcomTimer() { // TODO: for intended operation see DCCTimerAVR.cpp } // Timer IRQ handlers replace the dummy handlers (in cortex_handlers) // copied from rf24 branch void TCC0_Handler() { if(TCC0->INTFLAG.bit.OVF) { TCC0->INTFLAG.bit.OVF = 1; // writing a 1 clears the flag interruptHandler(); } } void TCC1_Handler() { if(TCC1->INTFLAG.bit.OVF) { TCC1->INTFLAG.bit.OVF = 1; // writing a 1 clears the flag interruptHandler(); } } void TCC2_Handler() { if(TCC2->INTFLAG.bit.OVF) { TCC2->INTFLAG.bit.OVF = 1; // writing a 1 clears the flag interruptHandler(); } } bool DCCTimer::isPWMPin(byte pin) { //TODO: SAMD whilst this call to digitalPinHasPWM will reveal which pins can do PWM, // there's no support yet for High Accuracy, so for now return false // return digitalPinHasPWM(pin); return false; } void DCCTimer::setPWM(byte pin, bool high) { // TODO: High Accuracy mode is not supported as yet, and may never need to be (void) pin; (void) high; } void DCCTimer::clearPWM() { return; } void DCCTimer::getSimulatedMacAddress(byte mac[6]) { volatile uint32_t *serno1 = (volatile uint32_t *)0x0080A00C; volatile uint32_t *serno2 = (volatile uint32_t *)0x0080A040; // volatile uint32_t *serno3 = (volatile uint32_t *)0x0080A044; // volatile uint32_t *serno4 = (volatile uint32_t *)0x0080A048; volatile uint32_t m1 = *serno1; volatile uint32_t m2 = *serno2; mac[0] = m1 >> 8; mac[1] = m1 >> 0; mac[2] = m2 >> 24; mac[3] = m2 >> 16; mac[4] = m2 >> 8; mac[5] = m2 >> 0; } volatile int DCCTimer::minimum_free_memory=__INT_MAX__; // Return low memory value... int DCCTimer::getMinimumFreeMemory() { noInterrupts(); // Disable interrupts to get volatile value int retval = freeMemory(); interrupts(); return retval; } extern "C" char* sbrk(int incr); int DCCTimer::freeMemory() { char top; return (int)(&top - reinterpret_cast(sbrk(0))); } void DCCTimer::reset() { __disable_irq(); NVIC_SystemReset(); while(true) {}; } void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) { } void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t fbits) { } #define NUM_ADC_INPUTS NUM_ANALOG_INPUTS uint16_t ADCee::usedpins = 0; int * ADCee::analogvals = NULL; int ADCee::init(uint8_t pin) { uint8_t id = pin - A0; int value = 0; if (id > NUM_ADC_INPUTS) return -1023; // Permanently configure SAMD IO MUX for that pin pinPeripheral(pin, PIO_ANALOG); ADC->INPUTCTRL.bit.MUXPOS = g_APinDescription[pin].ulADCChannelNumber; // Selection for the positive ADC input // Start conversion ADC->SWTRIG.bit.START = 1; // Wait for the conversion to be ready while (ADC->INTFLAG.bit.RESRDY == 0); // Waiting for conversion to complete // Read the value value = ADC->RESULT.reg; if (analogvals == NULL) analogvals = (int *)calloc(NUM_ADC_INPUTS+1, sizeof(int)); analogvals[id] = value; usedpins |= (1<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 ================================================ FILE: DCCTimerSTM32.cpp ================================================ /* * © 2023 Neil McKechnie * © 2022-2024 Paul M. Antoine * © 2021 Mike S * © 2021, 2023 Harald Barth * © 2021 Fred Decker * © 2021 Chris Harlow * © 2021 David Cutting * All rights reserved. * * This file is part of Asbelos DCC API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ // ATTENTION: this file only compiles on a STM32 based boards // Please refer to DCCTimer.h for general comments about how this class works // This is to avoid repetition and duplication. #ifdef ARDUINO_ARCH_STM32 #include "DCCTimer.h" #ifdef DEBUG_ADC #include "TrackManager.h" #endif #include "DIAG.h" #include #if defined(ARDUINO_NUCLEO_F401RE) // Nucleo-64 boards don't have additional serial ports defined by default // Serial1 is available on the F401RE, but not hugely convenient. // Rx pin on PB7 is useful, but all the Tx pins map to Arduino digital pins, specifically: // PA9 == D8 // PB6 == D10 // of which D8 is needed by the standard and EX8874 motor shields. D10 would be used if a second // EX8874 is stacked. So only disable this if using a second motor shield. HardwareSerial Serial1(PB7, PB6); // Rx=PB7, Tx=PB6 -- CN7 pin 17 and CN10 pin 17 // Serial2 is defined to use USART2 by default, but is in fact used as the diag console // via the debugger on the Nucleo-64. It is therefore unavailable for other DCC-EX uses like WiFi, DFPlayer, etc. // Let's define Serial6 as an additional serial port (the only other option for the F401RE) HardwareSerial Serial6(PA12, PA11); // Rx=PA12, Tx=PA11 -- CN10 pins 12 and 14 - F401RE #elif defined(ARDUINO_NUCLEO_F411RE) // Nucleo-64 boards don't have additional serial ports defined by default HardwareSerial Serial1(PB7, PA15); // Rx=PB7, Tx=PA15 -- CN7 pins 17 and 21 - F411RE // Serial2 is defined to use USART2 by default, but is in fact used as the diag console // via the debugger on the Nucleo-64. It is therefore unavailable for other DCC-EX uses like WiFi, DFPlayer, etc. // Let's define Serial6 as an additional serial port (the only other option for the Nucleo-64s) HardwareSerial Serial6(PA12, PA11); // Rx=PA12, Tx=PA11 -- CN10 pins 12 and 14 - F411RE #elif defined(ARDUINO_NUCLEO_F446RE) // Nucleo-64 boards don't have additional serial ports defined by default // On the F446RE, Serial1 isn't really useable as it's Rx/Tx pair sit on already used D2/D10 pins // HardwareSerial Serial1(PA10, PB6); // Rx=PA10 (D2), Tx=PB6 (D10) -- CN10 pins 17 and 9 - F446RE // Serial2 is defined to use USART2 by default, but is in fact used as the diag console // via the debugger on the Nucleo-64. It is therefore unavailable for other DCC-EX uses like WiFi, DFPlayer, etc. // On the F446RE, Serial3 and Serial5 are easy to use: HardwareSerial Serial3(PC11, PC10); // Rx=PC11, Tx=PC10 -- USART3 - F446RE HardwareSerial Serial5(PD2, PC12); // Rx=PD2, Tx=PC12 -- UART5 - F446RE // On the F446RE, Serial4 and Serial6 also use pins we can't readily map while using the Arduino pins #elif defined(ARDUINO_NUCLEO_F412ZG) || defined(ARDUINO_NUCLEO_F413ZH) || defined(ARDUINO_NUCLEO_F446ZE) || \ defined(ARDUINO_NUCLEO_F429ZI) || defined(ARDUINO_NUCLEO_F439ZI) || defined(ARDUINO_NUCLEO_F4X9ZI) // Nucleo-144 boards don't have Serial1 defined by default HardwareSerial Serial6(PG9, PG14); // Rx=PG9, Tx=PG14 -- USART6 HardwareSerial Serial2(PD6, PD5); // Rx=PD6, Tx=PD5 -- UART2 #if !defined(ARDUINO_NUCLEO_F412ZG) // F412ZG does not have UART5 HardwareSerial Serial5(PD2, PC12); // Rx=PD2, Tx=PC12 -- UART5 #endif // Serial3 is defined to use USART3 by default, but is in fact used as the diag console // via the debugger on the Nucleo-144. It is therefore unavailable for other DCC-EX uses like WiFi, DFPlayer, etc. #else #error STM32 board selected is not yet explicitly supported - so Serial1 peripheral is not defined #endif /////////////////////////////////////////////////////////////////////////////////////////////// // Experimental code for High Accuracy (HA) DCC Signal mode // Warning - use of TIM2 and TIM3 can affect the use of analogWrite() function on certain pins, // which is used by the DC motor types. /////////////////////////////////////////////////////////////////////////////////////////////// // INTERRUPT_CALLBACK interruptHandler=0; // // Let's use STM32's timer #2 which supports hardware pulse generation on pin D13. // // Also, timer #3 will do hardware pulses on pin D12. This gives // // accurate timing, independent of the latency of interrupt handling. // // We only need to interrupt on one of these (TIM2), the other will just generate // // pulses. // HardwareTimer timer(TIM2); // HardwareTimer timerAux(TIM3); // static bool tim2ModeHA = false; // static bool tim3ModeHA = false; // // Timer IRQ handler // void Timer_Handler() { // interruptHandler(); // } // void DCCTimer::begin(INTERRUPT_CALLBACK callback) { // interruptHandler=callback; // noInterrupts(); // // adc_set_sample_rate(ADC_SAMPLETIME_480CYCLES); // timer.pause(); // timerAux.pause(); // timer.setPrescaleFactor(1); // timer.setOverflow(DCC_SIGNAL_TIME, MICROSEC_FORMAT); // timer.attachInterrupt(Timer_Handler); // timer.refresh(); // timerAux.setPrescaleFactor(1); // timerAux.setOverflow(DCC_SIGNAL_TIME, MICROSEC_FORMAT); // timerAux.refresh(); // timer.resume(); // timerAux.resume(); // interrupts(); // } // bool DCCTimer::isPWMPin(byte pin) { // // Timer 2 Channel 1 controls pin D13, and Timer3 Channel 1 controls D12. // // Enable the appropriate timer channel. // switch (pin) { // case 12: // return true; // case 13: // return true; // default: // return false; // } // } // void DCCTimer::setPWM(byte pin, bool high) { // // Set the timer so that, at the next counter overflow, the requested // // pin state is activated automatically before the interrupt code runs. // // TIM2 is timer, TIM3 is timerAux. // switch (pin) { // case 12: // if (!tim3ModeHA) { // timerAux.setMode(1, TIMER_OUTPUT_COMPARE_INACTIVE, D12); // tim3ModeHA = true; // } // if (high) // TIM3->CCMR1 = (TIM3->CCMR1 & ~TIM_CCMR1_OC1M_Msk) | TIM_CCMR1_OC1M_0; // else // TIM3->CCMR1 = (TIM3->CCMR1 & ~TIM_CCMR1_OC1M_Msk) | TIM_CCMR1_OC1M_1; // break; // case 13: // if (!tim2ModeHA) { // timer.setMode(1, TIMER_OUTPUT_COMPARE_INACTIVE, D13); // tim2ModeHA = true; // } // if (high) // TIM2->CCMR1 = (TIM2->CCMR1 & ~TIM_CCMR1_OC1M_Msk) | TIM_CCMR1_OC1M_0; // else // TIM2->CCMR1 = (TIM2->CCMR1 & ~TIM_CCMR1_OC1M_Msk) | TIM_CCMR1_OC1M_1; // break; // } // } // void DCCTimer::clearPWM() { // timer.setMode(1, TIMER_OUTPUT_COMPARE_INACTIVE, NC); // tim2ModeHA = false; // timerAux.setMode(1, TIMER_OUTPUT_COMPARE_INACTIVE, NC); // tim3ModeHA = false; // } /////////////////////////////////////////////////////////////////////////////////////////////// INTERRUPT_CALLBACK interruptHandler=0; // On STM32F4xx models that have them, Timers 6 and 7 have no PWM output capability, // so are good choices for general timer duties - they are used for tone and servo // in stm32duino so we shall usurp those as DCC-EX doesn't use tone or servo libs. // NB: the F401, F410 and F411 do **not** have Timer 6 or 7, so we use Timer 11 #ifndef DCC_EX_TIMER #if defined(TIM6) #define DCC_EX_TIMER TIM6 #elif defined(TIM7) #define DCC_EX_TIMER TIM7 #elif defined(TIM11) #define DCC_EX_TIMER TIM11 #else #warning This STM32F4XX variant does not have Timers 6,7 or 11!! #endif #endif // ifndef DCC_EX_TIMER HardwareTimer dcctimer(DCC_EX_TIMER); void DCCTimer_Handler() __attribute__((interrupt)); // Timer IRQ handler void DCCTimer_Handler() { interruptHandler(); } void DCCTimer::begin(INTERRUPT_CALLBACK callback) { interruptHandler=callback; noInterrupts(); dcctimer.pause(); dcctimer.setPrescaleFactor(1); // timer.setOverflow(CLOCK_CYCLES * 2); dcctimer.setOverflow(DCC_SIGNAL_TIME, MICROSEC_FORMAT); // dcctimer.attachInterrupt(Timer11_Handler); dcctimer.attachInterrupt(DCCTimer_Handler); dcctimer.setInterruptPriority(1, 0); // Set second highest preemptive priority! dcctimer.refresh(); dcctimer.resume(); interrupts(); } void DCCTimer::startRailcomTimer(byte brakePin) { // TODO: for intended operation see DCCTimerAVR.cpp (void) brakePin; } void DCCTimer::ackRailcomTimer() { // TODO: for intended operation see DCCTimerAVR.cpp } bool DCCTimer::isPWMPin(byte pin) { //TODO: STM32 whilst this call to digitalPinHasPWM will reveal which pins can do PWM, // there's no support yet for High Accuracy, so for now return false // return digitalPinHasPWM(pin); (void) pin; return false; } void DCCTimer::setPWM(byte pin, bool high) { // TODO: High Accuracy mode is not supported as yet, and may never need to be (void) pin; (void) high; } void DCCTimer::clearPWM() { return; } void DCCTimer::getSimulatedMacAddress(byte mac[6]) { volatile uint32_t *serno1 = (volatile uint32_t *)UID_BASE; volatile uint32_t *serno2 = (volatile uint32_t *)UID_BASE+4; // volatile uint32_t *serno3 = (volatile uint32_t *)UID_BASE+8; volatile uint32_t m1 = *serno1; volatile uint32_t m2 = *serno2; mac[0] = m1 >> 8; mac[1] = m1 >> 0; mac[2] = m2 >> 24; mac[3] = m2 >> 16; mac[4] = m2 >> 8; mac[5] = m2 >> 0; } volatile int DCCTimer::minimum_free_memory=__INT_MAX__; // Return low memory value... int DCCTimer::getMinimumFreeMemory() { noInterrupts(); // Disable interrupts to get volatile value int retval = freeMemory(); interrupts(); return retval; } extern "C" char* sbrk(int incr); int DCCTimer::freeMemory() { char top; return (int)(&top - reinterpret_cast(sbrk(0))); } void DCCTimer::reset() { __disable_irq(); NVIC_SystemReset(); while(true) {}; } void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) { if (f >= 16) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, f); else if (f == 7) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 62500); else if (f >= 4) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 32000); else if (f >= 3) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 16000); else if (f >= 2) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 3400); else if (f == 1) DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 480); else DCCTimer::DCCEXanalogWriteFrequencyInternal(pin, 131); } // TODO: rationalise the size of these... could really use sparse arrays etc. static HardwareTimer * pin_timer[100] = {0}; static uint32_t channel_frequency[100] = {0}; static uint32_t pin_channel[100] = {0}; // Using the HardwareTimer library API included in stm32duino core to handle PWM duties // TODO: in order to use the HA code above which Neil kindly wrote, we may have to do something more // sophisticated about detecting any clash between the timer we'd like to use for PWM and the ones // currently used for HA so they don't interfere with one another. For now we'll just make PWM // work well... then work backwards to integrate with HA mode if we can. void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t frequency) { if (pin_timer[pin] == NULL) { // Automatically retrieve TIM instance and channel associated to pin // This is used to be compatible with all STM32 series automatically. TIM_TypeDef *Instance = (TIM_TypeDef *)pinmap_peripheral(digitalPinToPinName(pin), PinMap_PWM); if (Instance == NULL) { // We shouldn't get here (famous last words) as it ought to have been caught by brakeCanPWM()! DIAG(F("DCCEXanalogWriteFrequency::Pin %d has no PWM function!"), pin); return; } pin_channel[pin] = STM_PIN_CHANNEL(pinmap_function(digitalPinToPinName(pin), PinMap_PWM)); // Instantiate HardwareTimer object. Thanks to 'new' instantiation, // HardwareTimer is not destructed when setup function is finished. pin_timer[pin] = new HardwareTimer(Instance); // Configure and start PWM // MyTim->setPWM(channel, pin, 5, 10, NULL, NULL); // No callback required, we can simplify the function call if (pin_timer[pin] != NULL) { pin_timer[pin]->setPWM(pin_channel[pin], pin, frequency, 0); // set frequency in Hertz, 0% dutycycle DIAG(F("DCCEXanalogWriteFrequency::Pin %d on Timer Channel %d, frequency %d"), pin, pin_channel[pin], frequency); } else DIAG(F("DCCEXanalogWriteFrequency::failed to allocate HardwareTimer instance!")); } else { // Frequency change request if (frequency != channel_frequency[pin]) { pinmap_pinout(digitalPinToPinName(pin), PinMap_TIM); // ensure the pin has been configured! pin_timer[pin]->setOverflow(frequency, HERTZ_FORMAT); // Just change the frequency if it's already running! DIAG(F("DCCEXanalogWriteFrequency::setting frequency to %d"), frequency); } } channel_frequency[pin] = frequency; return; } void DCCTimer::DCCEXanalogWrite(uint8_t pin, int value, bool invert) { if (invert) value = 255-value; // Calculate percentage duty cycle from value given uint32_t duty_cycle = (value * 100 / 256) + 1; if (pin_timer[pin] != NULL) { // if (duty_cycle == 100) // { // pin_timer[pin]->pauseChannel(pin_channel[pin]); // DIAG(F("DCCEXanalogWrite::Pausing timer channel on pin %d"), pin); // } // else // { pinmap_pinout(digitalPinToPinName(pin), PinMap_TIM); // ensure the pin has been configured! // pin_timer[pin]->resumeChannel(pin_channel[pin]); pin_timer[pin]->setCaptureCompare(pin_channel[pin], duty_cycle, PERCENT_COMPARE_FORMAT); // DCC_EX_PWM_FREQ Hertz, duty_cycle% dutycycle DIAG(F("DCCEXanalogWrite::Pin %d, value %d, duty cycle %d"), pin, value, duty_cycle); // } } else DIAG(F("DCCEXanalogWrite::Pin %d is not configured for PWM!"), pin); } // Now we can handle more ADCs, maybe this works! #define NUM_ADC_INPUTS NUM_ANALOG_INPUTS uint32_t ADCee::usedpins = 0; // Max of 32 ADC input channels! uint8_t ADCee::highestPin = 0; // Highest pin to scan int * ADCee::analogvals = NULL; // Array of analog values last captured uint32_t * ADCee::analogchans = NULL; // Array of channel numbers to be scanned // bool adc1configured = false; ADC_TypeDef * * ADCee::adcchans = NULL; // Array to capture which ADC is each input channel on int16_t ADCee::ADCmax() { return 4095; } int ADCee::init(uint8_t pin) { int value = 0; PinName stmpin = analogInputToPinName(pin); if (stmpin == NC) // do not continue if this is not an analog pin at all return -1024; // some silly value as error uint32_t stmgpio = STM_PORT(stmpin); // converts to the GPIO port (16-bits per port group on STM32) uint32_t adcchan = STM_PIN_CHANNEL(pinmap_function(stmpin, PinMap_ADC)); // find ADC input channel ADC_TypeDef *adc = (ADC_TypeDef *)pinmap_find_peripheral(stmpin, PinMap_ADC); // find which ADC this pin is on ADC1/2/3 etc. int adcnum = 1; // All variants have ADC1 if (adc == ADC1) DIAG(F("ADCee::init(): found pin %d on ADC1"), pin); // Checking for ADC2 and ADC3 being defined helps cater for more variants #if defined(ADC2) else if (adc == ADC2) { DIAG(F("ADCee::init(): found pin %d on ADC2"), pin); adcnum = 2; } #endif #if defined(ADC3) else if (adc == ADC3) { DIAG(F("ADCee::init(): found pin %d on ADC3"), pin); adcnum = 3; } #endif else DIAG(F("ADCee::init(): found pin %d on unknown ADC!"), pin); // Port config - find which port we're on and power it up GPIO_TypeDef *gpioBase; switch (stmgpio) { case 0x00: RCC->AHB1ENR |= RCC_AHB1ENR_GPIOAEN; //Power up PORTA gpioBase = GPIOA; break; case 0x01: RCC->AHB1ENR |= RCC_AHB1ENR_GPIOBEN; //Power up PORTB gpioBase = GPIOB; break; case 0x02: RCC->AHB1ENR |= RCC_AHB1ENR_GPIOCEN; //Power up PORTC gpioBase = GPIOC; break; case 0x03: RCC->AHB1ENR |= RCC_AHB1ENR_GPIODEN; //Power up PORTD gpioBase = GPIOD; break; case 0x04: RCC->AHB1ENR |= RCC_AHB1ENR_GPIOEEN; //Power up PORTE gpioBase = GPIOE; break; #if defined(GPIOF) case 0x05: RCC->AHB1ENR |= RCC_AHB1ENR_GPIOFEN; //Power up PORTF gpioBase = GPIOF; break; #endif #if defined(GPIOG) case 0x06: RCC->AHB1ENR |= RCC_AHB1ENR_GPIOGEN; //Power up PORTG gpioBase = GPIOG; break; #endif #if defined(GPIOH) case 0x07: RCC->AHB1ENR |= RCC_AHB1ENR_GPIOHEN; //Power up PORTH gpioBase = GPIOH; break; #endif default: return -1023; // some silly value as error } // Set pin mux mode to analog input, the 32 bit port mode register has 2 bits per pin gpioBase->MODER |= (0b011 << (STM_PIN(stmpin) << 1)); // Set pin mux to analog mode (binary 11) // Set the sampling rate for that analog input // This is F411x specific! Different on for example F334 // STM32F11xC/E Reference manual // 11.12.4 ADC sample time register 1 (ADC_SMPR1) (channels 10 to 18) // 11.12.5 ADC sample time register 2 (ADC_SMPR2) (channels 0 to 9) if (adcchan > 18) return -1022; // silly value as error if (adcchan < 10) adc->SMPR2 |= (0b111 << (adcchan * 3)); // Channel sampling rate 480 cycles else adc->SMPR1 |= (0b111 << ((adcchan - 10) * 3)); // Channel sampling rate 480 cycles // Read the inital ADC value for this analog input adc->SQR3 = adcchan; // 1st conversion in regular sequence adc->CR2 |= ADC_CR2_SWSTART; //(1 << 30); // Start 1st conversion SWSTART while(!(adc->SR & (1 << 1))); // Wait until conversion is complete value = adc->DR; // Read value from register uint8_t id = pin - PNUM_ANALOG_BASE; // if (id > 15) { // today we have not enough bits in the mask to support more // return -1021; // } if (analogvals == NULL) { // allocate analogvals, analogchans and adcchans if this is the first invocation of init analogvals = (int *)calloc(NUM_ADC_INPUTS+1, sizeof(int)); analogchans = (uint32_t *)calloc(NUM_ADC_INPUTS+1, sizeof(uint32_t)); adcchans = (ADC_TypeDef **)calloc(NUM_ADC_INPUTS+1, sizeof(ADC_TypeDef)); } analogvals[id] = value; // Store sampled value analogchans[id] = adcchan; // Keep track of which ADC channel is used for reading this pin adcchans[id] = adc; // Keep track of which ADC this channel is on usedpins |= (1 << id); // This pin is now ready if (id > highestPin) highestPin = id; // Store our highest pin in use DIAG(F("ADCee::init(): value=%d, ADC%d: channel=%d, id=%d"), value, adcnum, adcchan, id); return value; } /* * Read function ADCee::read(pin) to get value instead of analogRead(pin) */ int ADCee::read(uint8_t pin, bool fromISR) { uint8_t id = pin - PNUM_ANALOG_BASE; // Was this pin initialised yet? if ((usedpins & (1<SR & (1 << 1))) return; // no result, continue to wait // found value analogvals[id] = adc->DR; // advance at least one track #ifdef DEBUG_ADC if (id == 1) TrackManager::track[1]->setBrake(0); #endif waiting = false; id++; mask = mask << 1; if (id > highestPin) { // the 1 has been shifted out id = 0; mask = 1; } } if (!waiting) { if (usedpins == 0) // otherwise we would loop forever return; // look for a valid track to sample or until we are around while (true) { if (mask & usedpins) { // start new ADC aquire on id adc = adcchans[id]; adc->SQR3 = analogchans[id]; // 1st conversion in regular sequence adc->CR2 |= (1 << 30); // Start 1st conversion SWSTART #ifdef DEBUG_ADC if (id == 1) TrackManager::track[1]->setBrake(1); #endif waiting = true; return; } id++; mask = mask << 1; if (id > highestPin) { id = 0; mask = 1; } } } } #pragma GCC pop_options void ADCee::begin() { noInterrupts(); //ADC1 config sequence RCC->APB2ENR |= RCC_APB2ENR_ADC1EN; // Enable ADC1 clock // Set ADC prescaler - DIV8 ~ 40ms, DIV6 ~ 30ms, DIV4 ~ 20ms, DIV2 ~ 11ms ADC->CCR = (0 << 16); // Set prescaler 0=DIV2, 1=DIV4, 2=DIV6, 3=DIV8 ADC1->CR1 &= ~(1 << 8); //SCAN mode disabled (Bit8) ADC1->CR1 &= ~(3 << 24); //12bit resolution (Bit24,25 0b00) ADC1->SQR1 = (1 << 20); //Set number of conversions projected (L[3:0] 0b0001) -> 1 conversion // Disable the DMA controller for ADC1 ADC1->CR2 &= ~ADC_CR2_DMA; ADC1->CR2 &= ~(1 << 1); //Single conversion ADC1->CR2 &= ~(1 << 11); //Right alignment of data bits bit12....bit0 ADC1->SQR1 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register ADC1->SQR2 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register ADC1->SQR3 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register ADC1->CR2 |= (1 << 0); // Switch on ADC1 // Wait for ADC1 to become ready (calibration complete) while (!(ADC1->CR2 & ADC_CR2_ADON)) { } #if defined(ADC2) // Enable the ADC2 clock RCC->APB2ENR |= RCC_APB2ENR_ADC2EN; // Initialize ADC2 ADC2->CR1 = 0; // Disable all channels ADC2->CR2 = 0; // Clear CR2 register ADC2->CR1 &= ~(1 << 8); //SCAN mode disabled (Bit8) ADC2->CR1 &= ~(3 << 24); //12bit resolution (Bit24,25 0b00) ADC2->SQR1 = (1 << 20); //Set number of conversions projected (L[3:0] 0b0001) -> 1 conversion ADC2->CR2 &= ~ADC_CR2_DMA; // Disable the DMA controller for ADC3 ADC2->CR2 &= ~(1 << 1); //Single conversion ADC2->CR2 &= ~(1 << 11); //Right alignment of data bits bit12....bit0 ADC2->SQR1 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register ADC2->SQR2 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register ADC2->SQR3 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register // Enable the ADC ADC2->CR2 |= ADC_CR2_ADON; // Wait for ADC2 to become ready (calibration complete) while (!(ADC2->CR2 & ADC_CR2_ADON)) { } // Perform ADC3 calibration (optional) // ADC3->CR2 |= ADC_CR2_CAL; // while (ADC3->CR2 & ADC_CR2_CAL) { // } #endif #if defined(ADC3) // Enable the ADC3 clock RCC->APB2ENR |= RCC_APB2ENR_ADC3EN; // Initialize ADC3 ADC3->CR1 = 0; // Disable all channels ADC3->CR2 = 0; // Clear CR2 register ADC3->CR1 &= ~(1 << 8); //SCAN mode disabled (Bit8) ADC3->CR1 &= ~(3 << 24); //12bit resolution (Bit24,25 0b00) ADC3->SQR1 = (1 << 20); //Set number of conversions projected (L[3:0] 0b0001) -> 1 conversion ADC3->CR2 &= ~ADC_CR2_DMA; // Disable the DMA controller for ADC3 ADC3->CR2 &= ~(1 << 1); //Single conversion ADC3->CR2 &= ~(1 << 11); //Right alignment of data bits bit12....bit0 ADC3->SQR1 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register ADC3->SQR2 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register ADC3->SQR3 &= ~(0x3FFFFFFF); //Clear whole 1st 30bits in register // Enable the ADC ADC3->CR2 |= ADC_CR2_ADON; // Wait for ADC3 to become ready (calibration complete) while (!(ADC3->CR2 & ADC_CR2_ADON)) { } // Perform ADC3 calibration (optional) // ADC3->CR2 |= ADC_CR2_CAL; // while (ADC3->CR2 & ADC_CR2_CAL) { // } #endif interrupts(); } #endif ================================================ FILE: DCCTimerTEENSY.cpp ================================================ /* * © 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 . */ // ATTENTION: this file only compiles on a TEENSY // Please refer to DCCTimer.h for general comments about how this class works // This is to avoid repetition and duplication. #ifdef TEENSYDUINO #include "DCCTimer.h" INTERRUPT_CALLBACK interruptHandler=0; IntervalTimer myDCCTimer; void DCCTimer::begin(INTERRUPT_CALLBACK callback) { interruptHandler=callback; myDCCTimer.begin(interruptHandler, DCC_SIGNAL_TIME); } void DCCTimer::startRailcomTimer(byte brakePin) { // TODO: for intended operation see DCCTimerAVR.cpp (void) brakePin; } void DCCTimer::ackRailcomTimer() { // TODO: for intended operation see DCCTimerAVR.cpp } bool DCCTimer::isPWMPin(byte pin) { //Teensy: digitalPinHasPWM, todo (void) pin; return false; // TODO what are the relevant pins? } void DCCTimer::setPWM(byte pin, bool high) { // TODO what are the relevant pins? (void) pin; (void) high; } void DCCTimer::clearPWM() { // Do nothing unless we implent HA } #if defined(__IMXRT1062__) //Teensy 4.0 and Teensy 4.1 void DCCTimer::getSimulatedMacAddress(byte mac[6]) { uint32_t m1 = HW_OCOTP_MAC1; uint32_t m2 = HW_OCOTP_MAC0; mac[0] = m1 >> 8; mac[1] = m1 >> 0; mac[2] = m2 >> 24; mac[3] = m2 >> 16; mac[4] = m2 >> 8; mac[5] = m2 >> 0; } #else // http://forum.pjrc.com/threads/91-teensy-3-MAC-address void teensyRead(uint8_t word, uint8_t *mac, uint8_t offset) { FTFL_FCCOB0 = 0x41; // Selects the READONCE command FTFL_FCCOB1 = word; // read the given word of read once area // launch command and wait until complete FTFL_FSTAT = FTFL_FSTAT_CCIF; while(!(FTFL_FSTAT & FTFL_FSTAT_CCIF)); *(mac+offset) = FTFL_FCCOB5; // collect only the top three bytes, *(mac+offset+1) = FTFL_FCCOB6; // in the right orientation (big endian). *(mac+offset+2) = FTFL_FCCOB7; // Skip FTFL_FCCOB4 as it's always 0. } void DCCTimer::getSimulatedMacAddress(byte mac[6]) { teensyRead(0xe,mac,0); teensyRead(0xf,mac,3); } #endif volatile int DCCTimer::minimum_free_memory=__INT_MAX__; // Return low memory value... int DCCTimer::getMinimumFreeMemory() { noInterrupts(); // Disable interrupts to get volatile value int retval = freeMemory(); interrupts(); return retval; } extern "C" char* sbrk(int incr); #if !defined(__IMXRT1062__) int DCCTimer::freeMemory() { char top; return &top - reinterpret_cast(sbrk(0)); } #else #if defined(ARDUINO_TEENSY40) static const unsigned DTCM_START = 0x20000000UL; static const unsigned OCRAM_START = 0x20200000UL; static const unsigned OCRAM_SIZE = 512; static const unsigned FLASH_SIZE = 1984; #elif defined(ARDUINO_TEENSY41) static const unsigned DTCM_START = 0x20000000UL; static const unsigned OCRAM_START = 0x20200000UL; static const unsigned OCRAM_SIZE = 512; static const unsigned FLASH_SIZE = 7936; #if TEENSYDUINO>151 extern "C" uint8_t external_psram_size; #endif #endif int DCCTimer::freeMemory() { extern unsigned long _ebss; extern unsigned long _sdata; extern unsigned long _estack; const unsigned DTCM_START = 0x20000000UL; unsigned dtcm = (unsigned)&_estack - DTCM_START; unsigned stackinuse = (unsigned) &_estack - (unsigned) __builtin_frame_address(0); unsigned varsinuse = (unsigned)&_ebss - (unsigned)&_sdata; unsigned freemem = dtcm - (stackinuse + varsinuse); return freemem; } #endif void DCCTimer::reset() { // found at https://forum.pjrc.com/threads/59935-Reboot-Teensy-programmatically SCB_AIRCR = 0x05FA0004; } void DCCTimer::DCCEXanalogWriteFrequency(uint8_t pin, uint32_t f) { } void DCCTimer::DCCEXanalogWriteFrequencyInternal(uint8_t pin, uint32_t fbits) { } int16_t ADCee::ADCmax() { return 4095; } int ADCee::init(uint8_t pin) { return analogRead(pin); } /* * Read function ADCee::read(pin) to get value instead of analogRead(pin) */ int ADCee::read(uint8_t pin, bool fromISR) { int current; if (!fromISR) noInterrupts(); current = analogRead(pin); if (!fromISR) interrupts(); return current; } /* * Scan function that is called from interrupt */ void ADCee::scan() { } void ADCee::begin() { noInterrupts(); interrupts(); } #endif ================================================ FILE: DCCWaveform.cpp ================================================ /* * © 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 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 . */ #ifndef ARDUINO_ARCH_ESP32 // This code is replaced entirely on an ESP32 #include #include "DCCWaveform.h" #include "TrackManager.h" #include "DCCTimer.h" #include "DCCACK.h" #include "DIAG.h" #include "Railcom.h" bool DCCWaveform::cutoutNextTime=false; DCCWaveform DCCWaveform::mainTrack(PREAMBLE_BITS_MAIN, true); DCCWaveform DCCWaveform::progTrack(PREAMBLE_BITS_PROG, false); // 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() { // empty placemarker in case ESP32 needs something here } #pragma GCC push_options #pragma GCC optimize ("-O3") void DCCWaveform::interruptHandler() { // call the timer edge sensitive actions for progtrack and maintrack // member functions would be cleaner but have more overhead #if defined(HAS_ENOUGH_MEMORY) if (cutoutNextTime) { cutoutNextTime=false; Railcom::incCutout(); DCCTimer::startRailcomTimer(9); } #endif byte sigMain=signalTransform[mainTrack.state]; byte sigProg=TrackManager::progTrackSyncMain? sigMain : signalTransform[progTrack.state]; // Set the signal state for both tracks TrackManager::setDCCSignal(sigMain); TrackManager::setPROGSignal(sigProg); // Refresh the values in the ADCee object buffering the values of the ADC HW ADCee::scan(); // Move on in the state engine mainTrack.state=stateTransform[mainTrack.state]; progTrack.state=stateTransform[progTrack.state]; // WAVE_PENDING means we dont yet know what the next bit is if (mainTrack.state==WAVE_PENDING) mainTrack.interrupt2(); if (progTrack.state==WAVE_PENDING) progTrack.interrupt2(); else DCCACK::checkAck(progTrack.getResets()); } #pragma GCC pop_options // An instance of this class handles the DCC transmissions for one track. (main or prog) // Interrupts are marshalled via the statics. // A track has a current transmit buffer, and a pending buffer. // When the current buffer is exhausted, either the pending buffer (if there is one waiting) or an idle buffer. DCCWaveform::DCCWaveform( byte preambleBits, bool isMain) { isMainTrack = isMain; packetPending = false; reminderWindowOpen = false; memcpy(transmitPacket, idlePacket, sizeof(idlePacket)); state = WAVE_START; // The +1 below is to allow the preamble generator to create the stop bit // for the previous packet. requiredPreambles = preambleBits+1; bytes_sent = 0; bits_sent = 0; } bool DCCWaveform::railcomPossible=false; // High accuracy only volatile bool DCCWaveform::railcomActive=false; // switched on by user bool DCCWaveform::setRailcom(bool on) { if (on && railcomPossible) { railcomActive=true; } else { railcomActive=false; } return railcomActive; } #pragma GCC push_options #pragma GCC optimize ("-O3") void DCCWaveform::interrupt2() { // calculate the next bit to be sent: // set state WAVE_MID_1 for a 1=bit // or WAVE_HIGH_0 for a 0 bit. if (remainingPreambles > 0 ) { state=WAVE_MID_1; // switch state to trigger LOW on next interrupt remainingPreambles--; // As we get to the end of the preambles, open the reminder window. // This delays any reminder insertion until the last moment so // that the reminder doesn't block a more urgent packet. reminderWindowOpen=transmitRepeats==0 && remainingPreambles<12 && remainingPreambles>1; if (remainingPreambles==1) promotePendingPacket(); #if defined(HAS_ENOUGH_MEMORY) else if (isMainTrack && railcomActive) { if (remainingPreambles==(requiredPreambles-1)) { // First look if we need to start a railcom cutout on next interrupt cutoutNextTime= true; } else if (remainingPreambles==(requiredPreambles-12)) { // cutout has ended so its now possible to poll the railcom detectors // requiredPreambles is one higher that preamble length so // if preamble length is 16 then this evaluates to 5 } else if (remainingPreambles==(requiredPreambles-3)) { // cutout can be ended when read // see above for requiredPreambles DCCTimer::ackRailcomTimer(); } } #endif // 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. else DCCTimer::updateMinimumFreeMemoryISR(22); return; } // Wave has gone HIGH but what happens next depends on the bit to be transmitted // beware OF 9-BIT MASK generating a zero to start each byte state=(transmitPacket[bytes_sent] & bitMask[bits_sent])? WAVE_MID_1 : WAVE_HIGH_0; bits_sent++; // If this is the last bit of a byte, prepare for the next byte if (bits_sent == 9) { // zero followed by 8 bits of a byte //end of Byte bits_sent = 0; bytes_sent++; // if this is the last byte, prepere for next packet if (bytes_sent >= transmitLength) { // end of transmission buffer... repeat or switch to next message bytes_sent = 0; // preamble for next packet will start... remainingPreambles = requiredPreambles; } } } #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 while (packetPending); 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; packetPending = true; clearResets(); } bool DCCWaveform::isReminderWindowOpen() { return reminderWindowOpen && ! packetPending; } void DCCWaveform::promotePendingPacket() { // fill the transmission packet from the pending packet // Just keep going if repeating if (transmitRepeats > 0) { transmitRepeats--; return; } if (packetPending) { // Copy pending packet to transmit packet // a fixed length memcpy is faster than a variable length loop for these small lengths // for (int b = 0; b < pendingLength; b++) transmitPacket[b] = pendingPacket[b]; memcpy( transmitPacket, pendingPacket, sizeof(pendingPacket)); transmitLength = pendingLength; transmitRepeats = pendingRepeats; packetPending = false; clearResets(); return; } // nothing to do, just send idles or resets // Fortunately reset and idle packets are the same length memcpy( transmitPacket, isMainTrack ? idlePacket : resetPacket, sizeof(idlePacket)); transmitLength = sizeof(idlePacket); transmitRepeats = 0; if (getResets() < 250) sentResetsSincePacket++; // only place to increment (private!) } #endif ================================================ FILE: DCCWaveform.h ================================================ /* * © 2021 M Steve Todd * © 2021 Mike S * © 2021 Fred Decker * © 2020-2024 Harald Barth * © 2020-2025 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 . */ #ifndef DCCWaveform_h #define DCCWaveform_h #ifdef ARDUINO_ARCH_ESP32 #include "DCCRMT.h" #endif // Number of preamble bits. const byte PREAMBLE_BITS_MAIN = 16; const byte PREAMBLE_BITS_PROG = 22; const byte MAX_PACKET_SIZE = 5; // NMRA standard extended packets, payload size WITHOUT checksum. // The WAVE_STATE enum is deliberately numbered because a change of order would be catastrophic // to the transform array. enum WAVE_STATE : byte { WAVE_START=0, // wave going high at start of bit WAVE_MID_1=1, // middle of 1 bit WAVE_HIGH_0=2, // first part of 0 bit high WAVE_MID_0=3, // middle of 0 bit WAVE_LOW_0=4, // first part of 0 bit low WAVE_PENDING=5 // next bit not yet known }; // NOTE: static functions are used for the overall controller, then // one instance is created for each track. class DCCWaveform { public: DCCWaveform( byte preambleBits, bool isMain); static void begin(); static void loop(); static DCCWaveform mainTrack; static DCCWaveform progTrack; 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 isReminderWindowOpen(); void promotePendingPacket(); static bool setRailcom(bool on); inline static bool isRailcom() { return railcomActive; }; inline static bool isRailcomPossible() { return railcomPossible; }; inline static void setRailcomPossible(bool yes) { railcomPossible=yes; if (!yes) setRailcom(false); }; private: #ifndef ARDUINO_ARCH_ESP32 volatile bool packetPending; volatile bool reminderWindowOpen; volatile byte sentResetsSincePacket; #else volatile uint32_t resetPacketBase; #endif static void interruptHandler(); void interrupt2(); bool isMainTrack; // Transmission controller byte transmitPacket[MAX_PACKET_SIZE+1]; // +1 for checksum byte transmitLength; byte transmitRepeats; // remaining repeats of transmission byte remainingPreambles; byte requiredPreambles; byte bits_sent; // 0-8 (yes 9 bits) sent for current byte byte bytes_sent; // number of bytes sent from transmitPacket WAVE_STATE state; // wave generator state machine byte pendingPacket[MAX_PACKET_SIZE+1]; // +1 for checksum byte pendingLength; byte pendingRepeats; static bool railcomPossible; // High accuracy mode only static volatile bool railcomActive; // switched on by user static bool cutoutNextTime; // railcom #ifdef ARDUINO_ARCH_ESP32 static RMTChannel *rmtMainChannel; static RMTChannel *rmtProgChannel; #endif }; #endif ================================================ FILE: DCCWaveformRMT.cpp ================================================ /* * © 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 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 . */ // This code is ESP32 ONLY. #ifdef ARDUINO_ARCH_ESP32 #include "DCCWaveform.h" #include "DCCACK.h" #include "TrackManager.h" DCCWaveform DCCWaveform::mainTrack(PREAMBLE_BITS_MAIN, true); DCCWaveform DCCWaveform::progTrack(PREAMBLE_BITS_PROG, false); RMTChannel *DCCWaveform::rmtMainChannel = NULL; RMTChannel *DCCWaveform::rmtProgChannel = NULL; bool DCCWaveform::railcomPossible=false; // High accuracy only volatile bool DCCWaveform::railcomActive=false; // switched on by user DCCWaveform::DCCWaveform(byte preambleBits, bool isMain) { isMainTrack = isMain; requiredPreambles = preambleBits; } void DCCWaveform::begin() { for(const auto& md: TrackManager::getMainDrivers()) { pinpair p = md->getSignalPin(); if(rmtMainChannel) { //DIAG(F("added pins %d %d to MAIN channel"), p.pin, p.invpin); rmtMainChannel->addPin(p); // add pin to existing main channel } else { //DIAG(F("new MAIN channel with pins %d %d"), p.pin, p.invpin); rmtMainChannel = new RMTChannel(p, true); /* create new main channel */ } } MotorDriver *md = TrackManager::getProgDriver(); if (md) { pinpair p = md->getSignalPin(); if (rmtProgChannel) { //DIAG(F("added pins %d %d to PROG channel"), p.pin, p.invpin); rmtProgChannel->addPin(p); // add pin to existing prog channel } else { //DIAG(F("new PROGchannel with pins %d %d"), p.pin, p.invpin); rmtProgChannel = new RMTChannel(p, false); } } } void DCCWaveform::schedulePacket(const byte buffer[], byte byteCount, byte repeats) { if (byteCount > MAX_PACKET_SIZE) return; // allow for chksum RMTChannel *rmtchannel = (isMainTrack ? rmtMainChannel : rmtProgChannel); if (rmtchannel == NULL) return; // no idea to prepare packet if we can not send it anyway rmtchannel->waitForDataCopy(); // blocking wait so we can write into buffer byte checksum = 0; for (byte b = 0; b < byteCount; b++) { checksum ^= buffer[b]; pendingPacket[b] = buffer[b]; } // buffer is MAX_PACKET_SIZE but pendingPacket is one bigger pendingPacket[byteCount] = checksum; pendingLength = byteCount + 1; pendingRepeats = repeats; // DIAG repeated commands (accesories) // if (pendingRepeats > 0) // DIAG(F("Repeats=%d on %s track"), pendingRepeats, isMainTrack ? "MAIN" : "PROG"); // The resets will be zero not only now but as well repeats packets into the future clearResets(repeats+1); { int ret = 0; do { ret = rmtchannel->RMTfillData(pendingPacket, pendingLength, pendingRepeats); } while(ret > 0); } } bool DCCWaveform::isReminderWindowOpen() { if(isMainTrack) { if (rmtMainChannel == NULL) return false; return !rmtMainChannel->busy(); } else { if (rmtProgChannel == NULL) return false; return !rmtProgChannel->busy(); } } void IRAM_ATTR DCCWaveform::loop() { DCCACK::checkAck(progTrack.getResets()); } bool DCCWaveform::setRailcom(bool on) { // TODO... ESP32 railcom waveform return false; } #endif ================================================ FILE: DIAG.h ================================================ /* * © 2021 Fred Decker * © 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 . */ #ifndef DIAG_h #define DIAG_h #include "StringFormatter.h" #define DIAG StringFormatter::diag #define LCD StringFormatter::lcd #define SCREEN StringFormatter::lcd2 #endif ================================================ FILE: Display.cpp ================================================ /* * © 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 . */ // CAUTION: the device dependent parts of this class are created in the .ini // using LCD_Implementation.h /* The strategy for drawing the screen is as follows. * 1) There are up to eight rows of text to be displayed. * 2) Blank rows of text are ignored. * 3) If there are more non-blank rows than screen lines, * then all of the rows are displayed, with the rest of the * screen being blank. * 4) If there are fewer non-blank rows than screen lines, * then a scrolling strategy is adopted so that, on each screen * refresh, a different subset of the rows is presented. * 5) On each entry into loop2(), a single operation is sent to the * screen; this may be a position command or a character for * display. This spreads the onerous work of updating the screen * and ensures that other loop() functions in the application are * not held up significantly. The exception to this is when * the loop2() function is called with force=true, where * a screen update is executed to completion. This is normally * only done during start-up. * The scroll mode is selected by defining SCROLLMODE as 0, 1 or 2 * in the config.h. * #define SCROLLMODE 0 is scroll continuous (fill screen if poss), * #define SCROLLMODE 1 is by page (alternate between pages), * #define SCROLLMODE 2 is by row (move up 1 row at a time). */ #include "Display.h" // Constructor - allocates device driver. Display::Display(DisplayDevice *deviceDriver) { _deviceDriver = deviceDriver; // Get device dimensions in characters (e.g. 16x2). numScreenColumns = _deviceDriver->getNumCols(); numScreenRows = _deviceDriver->getNumRows(); for (uint8_t row = 0; row < MAX_CHARACTER_ROWS; row++) rowBuffer[row][0] = '\0'; addDisplay(0); // Add this display as display number 0 }; void Display::begin() { _deviceDriver->begin(); _deviceDriver->clearNative(); } void Display::_clear() { _deviceDriver->clearNative(); for (uint8_t row = 0; row < MAX_CHARACTER_ROWS; row++) rowBuffer[row][0] = '\0'; } void Display::_setRow(uint8_t line) { hotRow = line; hotCol = 0; rowBuffer[hotRow][0] = '\0'; // Clear existing text } size_t Display::_write(uint8_t b) { if (hotRow >= MAX_CHARACTER_ROWS || hotCol >= MAX_CHARACTER_COLS) return -1; rowBuffer[hotRow][hotCol] = b; hotCol++; rowBuffer[hotRow][hotCol] = '\0'; return 1; } // Refresh screen completely (will block until complete). Used // during start-up. void Display::_refresh() { loop2(true); } // On normal loop entries, loop will only make one output request on each // entry, to avoid blocking while waiting for the I2C. void Display::_displayLoop() { // If output device is busy, don't do anything on this loop // This avoids blocking while waiting for the device to complete. if (!_deviceDriver->isBusy()) loop2(false); } Display *Display::loop2(bool force) { unsigned long currentMillis = millis(); if (!force) { // See if we're in the time between updates if ((currentMillis - lastScrollTime) < DISPLAY_SCROLL_TIME) return NULL; } else { // force full screen update from the beginning. rowFirst = 0; rowCurrent = 0; bufferPointer = 0; noMoreRowsToDisplay = false; slot = 0; } do { if (bufferPointer == 0) { // Search for non-blank row while (!noMoreRowsToDisplay) { if (!isCurrentRowBlank()) break; moveToNextRow(); if (rowCurrent == rowFirst) noMoreRowsToDisplay = true; } if (noMoreRowsToDisplay) { // No non-blank lines left, so draw blank line buffer[0] = '\0'; } else { // Non-blank line found, so copy it (including terminator) for (uint8_t i = 0; i <= MAX_CHARACTER_COLS; i++) buffer[i] = rowBuffer[rowCurrent][i]; } _deviceDriver->setRowNative(slot); // Set position for display charIndex = 0; bufferPointer = &buffer[0]; } else { // Write next character, or a space to erase current position. char ch = *bufferPointer; if (ch) { _deviceDriver->writeNative(ch); bufferPointer++; } else { _deviceDriver->writeNative(' '); } if (++charIndex >= MAX_CHARACTER_COLS) { // Screen slot completed, move to next nonblank row bufferPointer = 0; for (;;) { moveToNextRow(); if (rowCurrent == rowFirst) { noMoreRowsToDisplay = true; break; } if (!isCurrentRowBlank()) break; } // Move to next screen slot, if available slot++; if (slot >= numScreenRows) { // Last slot on screen written, so get ready for next screen update. #if SCROLLMODE==0 // Scrollmode 0 scrolls continuously. If the rows fit on the screen, // then restart at row 0, but otherwise continue with the row // after the last one displayed. if (countNonBlankRows() <= numScreenRows) rowCurrent = 0; rowFirst = rowCurrent; #elif SCROLLMODE==1 // Scrollmode 1 scrolls by page, so if the last page has just completed then // next time restart with row 0. if (noMoreRowsToDisplay) rowFirst = rowCurrent = 0; #else // Scrollmode 2 scrolls by row. If the rows don't fit on the screen, // then start one row further on next time. If they do fit, then // show them in order and start next page at row 0. if (countNonBlankRows() <= numScreenRows) { rowFirst = rowCurrent = 0; } else { // Find first non-blank row after the previous first row rowCurrent = rowFirst; do { moveToNextRow(); } while (isCurrentRowBlank()); rowFirst = rowCurrent; } #endif noMoreRowsToDisplay = false; slot = 0; _deviceDriver->setRowNative(slot); // Set position for display lastScrollTime = currentMillis; return NULL; } } } } while (force); return NULL; } bool Display::isCurrentRowBlank() { return (rowBuffer[rowCurrent][0] == '\0'); } void Display::moveToNextRow() { // Skip blank rows if (++rowCurrent >= MAX_CHARACTER_ROWS) rowCurrent = 0; } uint8_t Display::countNonBlankRows() { uint8_t count = 0; for (uint8_t rowNumber=0; rowNumber. */ #ifndef Display_h #define Display_h #include #include "defines.h" #include "DisplayInterface.h" // Allow maximum message length to be overridden from config.h #if !defined(MAX_MSG_SIZE) #define MAX_MSG_SIZE 20 #endif // Set default scroll mode (overridable in config.h) #if !defined(SCROLLMODE) #define SCROLLMODE 1 #endif // This class is created in Display_Implementation.h class Display : public DisplayInterface { public: Display(DisplayDevice *deviceDriver); #if !defined (MAX_CHARACTER_ROWS) #if defined(ARDUINO_ARCH_ESP32) || defined(ARDUINO_ARCH_STM32) static const int MAX_CHARACTER_ROWS = 17; #else static const int MAX_CHARACTER_ROWS = 8; #endif #endif static const int MAX_CHARACTER_COLS = MAX_MSG_SIZE; static const long DISPLAY_SCROLL_TIME = 3000; // 3 seconds private: DisplayDevice *_deviceDriver; unsigned long lastScrollTime = 0; uint8_t hotRow = 0; uint8_t hotCol = 0; uint8_t slot = 0; uint8_t rowFirst = 0; uint8_t rowCurrent = 0; uint8_t charIndex = 0; char buffer[MAX_CHARACTER_COLS + 1]; char* bufferPointer = 0; bool noMoreRowsToDisplay = false; uint16_t numScreenRows; uint16_t numScreenColumns = MAX_CHARACTER_COLS; char rowBuffer[MAX_CHARACTER_ROWS][MAX_CHARACTER_COLS+1]; public: void begin() override; void _clear() override; void _setRow(uint8_t line) override; size_t _write(uint8_t b) override; void _refresh() override; void _displayLoop() override; Display *loop2(bool force); bool findNonBlankRow(); bool isCurrentRowBlank(); void moveToNextRow(); uint8_t countNonBlankRows(); }; #endif ================================================ FILE: DisplayInterface.cpp ================================================ /* * © 2021 Neil McKechnie * © 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 . */ #include "DisplayInterface.h" // Install null display driver initially - will be replaced if required. DisplayInterface *DisplayInterface::_displayHandler = new DisplayInterface(); uint8_t DisplayInterface::_selectedDisplayNo = 255; ================================================ FILE: DisplayInterface.h ================================================ /* * © 2021 Neil McKechnie * © 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 . */ #ifndef DisplayInterface_h #define DisplayInterface_h #include // Definition of base class for displays. The base class does nothing. class DisplayInterface : public Print { protected: static DisplayInterface *_displayHandler; static uint8_t _selectedDisplayNo; // Nothing selected. DisplayInterface *_nextHandler = NULL; uint8_t _displayNo = 0; 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() {} }; 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 ================================================ FILE: Display_Implementation.h ================================================ /* * © 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 . */ //////////////////////////////////////////////////////////////////////////////////// // This implementation is designed to be #included ONLY ONCE in the .ino // // It will create a driver implemntation and a shim class implementation. // This means that other classes can reference the shim without knowing // which library is involved. //////////////////////////////////////////////////////////////////////////////////// #ifndef LCD_Implementation_h #define LCD_Implementation_h #include "DisplayInterface.h" #include "SSD1306Ascii.h" #include "LiquidCrystal_I2C.h" // 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 DISPLAY_START(xxx) { \ DisplayInterface *t = new Display(new SSD1306AsciiWire(OLED_DRIVER)); \ t->begin(); \ xxx; \ t->refresh(); \ } #elif defined(LCD_DRIVER) #define DISPLAY_START(xxx) { \ DisplayInterface *t = new Display(new LiquidCrystal_I2C(LCD_DRIVER)); \ t->begin(); \ xxx; \ t->refresh();} #else #define DISPLAY_START(xxx) { \ xxx; \ } #endif #endif // LCD_Implementation_h ================================================ FILE: EEStore.cpp ================================================ /* * © 2021 Neil McKechnie * © 2021 Fred Decker * © 2020-2022 Harald Barth * © 2020-2021 Chris Harlow * © 2013-2016 Gregg E. Berman * 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 . */ #include "defines.h" #ifndef DISABLE_EEPROM #include "EEStore.h" #include "DIAG.h" #include "Outputs.h" #include "Sensors.h" #include "Turnouts.h" #if defined(ARDUINO_ARCH_SAMC) ExternalEEPROM EEPROM; #endif void EEStore::init() { #if defined(ARDUINO_ARCH_SAMC) EEPROM.begin(0x50); // Address for Microchip 24-series EEPROM with all three // A pins grounded (0b1010000 = 0x50) #endif eeStore = (EEStore *)calloc(1, sizeof(EEStore)); EEPROM.get(0, eeStore->data); // get eeStore data // check to see that eeStore contains valid DCC++ ID 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)+0); eeStore->data.nTurnouts = 0; eeStore->data.nSensors = 0; eeStore->data.nOutputs = 0; EEPROM.put(0, eeStore->data); } reset(); // set memory pointer to first free EEPROM space Turnout::load(); // load turnout definitions Sensor::load(); // load sensor definitions Output::load(); // load output definitions } /////////////////////////////////////////////////////////////////////////////// void EEStore::clear() { sprintf(eeStore->data.id, EESTORE_ID); // create blank eeStore structure (no turnouts, no // sensors) and save it back to EEPROM eeStore->data.nTurnouts = 0; eeStore->data.nSensors = 0; eeStore->data.nOutputs = 0; EEPROM.put(0, eeStore->data); } /////////////////////////////////////////////////////////////////////////////// void EEStore::store() { reset(); Turnout::store(); Sensor::store(); Output::store(); EEPROM.put(0, eeStore->data); DIAG(F("EEPROM used: %d/%d bytes"), EEStore::pointer(), EEPROM.length()); } /////////////////////////////////////////////////////////////////////////////// void EEStore::advance(int n) { eeAddress += n; } /////////////////////////////////////////////////////////////////////////////// void EEStore::reset() { eeAddress = sizeof(EEStore); } /////////////////////////////////////////////////////////////////////////////// int EEStore::pointer() { return (eeAddress); } /////////////////////////////////////////////////////////////////////////////// void EEStore::dump(int num) { byte b = 0; DIAG(F("Addr 0x char")); for (int n = 0; n < num; n++) { EEPROM.get(n, b); DIAG(F("%d %x %c"), n, b, isprint(b) ? b : ' '); } } /////////////////////////////////////////////////////////////////////////////// EEStore *EEStore::eeStore = NULL; int EEStore::eeAddress = 0; #endif ================================================ FILE: EEStore.h ================================================ /* * © 2021 Neil McKechnie * © 2021 Fred Decker * © 2020-2021 Harald Barth * © 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 . */ #ifndef DISABLE_EEPROM #ifndef EEStore_h #define EEStore_h #include #if defined(ARDUINO_ARCH_SAMC) #include extern ExternalEEPROM EEPROM; #else #include #endif #define EESTORE_ID "DCC++1" struct EEStoreData{ char id[sizeof(EESTORE_ID)]; uint16_t nTurnouts; uint16_t nSensors; uint16_t nOutputs; }; struct EEStore{ static EEStore *eeStore; EEStoreData data; static int eeAddress; static void init(); static void reset(); static int pointer(); static void advance(int); static void store(); static void clear(); static void dump(int); }; #endif #endif // DISABLE_EEPROM ================================================ FILE: EXRAIL.h ================================================ /* * © 2021 Fred Decker * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef EXRAIL_H #define EXRAIL_H #if defined(EXRAIL_ACTIVE) #include "EXRAIL2.h" class RMFT { public: static void inline begin() {RMFT2::begin();} static void inline loop() {RMFT2::loop();} }; #include "EXRAILMacros.h" #else // Dummy RMFT class RMFT { public: static void inline begin() {} static void inline loop() {} }; #endif #endif ================================================ FILE: EXRAIL2.cpp ================================================ /* * © 2024 Paul M. Antoine * © 2021 Neil McKechnie * © 2021-2023 Harald Barth * © 2020-2025 Chris Harlow * © 2022-2023 Colin Murdoch * © 2025 Morten Nielsen * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* EXRAILPlus planned FEATURE additions F1. [DONE] DCC accessory packet opcodes (short and long form) F2. [DONE] ONAccessory catchers F3. [DONE] Turnout descriptions for Withrottle F4. [DONE] Oled announcements (depends on HAL) F5. [DONE] Withrottle roster info F6. Multi-occupancy semaphore F7. [DONE see AUTOSTART] Self starting sequences F8. Park/unpark F9. [DONE] Analog drive F10. [DONE] Alias anywhere F11. [DONE]EXRAIL/ENDEXRAIL unnecessary F12. [DONE] Allow guarded code (as effect of ALIAS anywhere) F13. [DONE] IFGTE/IFLT function */ /* EXRAILPlus planned TRANSPARENT additions T1. [DONE] RAM based fast lookup for sequences ON* event catchers and signals. T2. Extend to >64k */ #include #include "defines.h" #include "EXRAIL2.h" #include "DCC.h" #include "DCCWaveform.h" #include "DIAG.h" #include "WiThrottle.h" #include "DCCEXParser.h" #include "Turnouts.h" #include "CommandDistributor.h" #include "TrackManager.h" #include "Turntables.h" #include "IODevice.h" #include "EXRAILSensor.h" #include "Stash.h" #include "DCCConsist.h" // 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 threads 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 prog track bool RMFT2::diag=false; // 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]; Print * RMFT2::LCCSerial=0; LookList * RMFT2::routeLookup=NULL; LookList * RMFT2::signalLookup=NULL; LookList * RMFT2::onThrowLookup=NULL; LookList * RMFT2::onCloseLookup=NULL; LookList * RMFT2::onActivateLookup=NULL; LookList * RMFT2::onDeactivateLookup=NULL; LookList * RMFT2::onRedLookup=NULL; LookList * RMFT2::onAmberLookup=NULL; LookList * RMFT2::onGreenLookup=NULL; LookList * RMFT2::onChangeLookup=NULL; LookList * RMFT2::onClockLookup=NULL; #ifndef IO_NO_HAL LookList * RMFT2::onRotateLookup=NULL; #endif LookList * RMFT2::onOverloadLookup=NULL; LookList * RMFT2::onBlockEnterLookup=NULL; LookList * RMFT2::onBlockExitLookup=NULL; #ifdef BOOSTER_INPUT LookList * RMFT2::onRailSyncOnLookup=NULL; LookList * RMFT2::onRailSyncOffLookup=NULL; #endif byte * RMFT2::routeStateArray=nullptr; const FSH * * RMFT2::routeCaptionArray=nullptr; // getOperand instance version, uses progCounter from instance. uint16_t RMFT2::getOperand(byte n) { return getOperand(progCounter,n); } // getOperand static version, must be provided prog counter from loop etc. uint16_t RMFT2::getOperand(int progCounter,byte n) { int offset=progCounter+1+(n*3); byte lsb=GETHIGHFLASH(RouteCode,offset); byte msb=GETHIGHFLASH(RouteCode,offset+1); return msb<<8|lsb; } LookList::LookList(int16_t size) { m_size=size; m_loaded=0; m_chain=nullptr; if (size) { m_lookupArray=new int16_t[size]; m_resultArray=new int16_t[size]; } } void LookList::add(int16_t lookup, int16_t result) { if (m_loaded==m_size) return; // and forget m_lookupArray[m_loaded]=lookup; m_resultArray[m_loaded]=result; m_loaded++; } int16_t LookList::find(int16_t value) { for (int16_t i=0;ifind(value) :-1; } void LookList::chain(LookList * chain) { m_chain=chain; } void LookList::handleEvent(const FSH* reason,int16_t id, int16_t loco) { // New feature... create multiple ONhandlers for (int i=0;iprint(" "); _stream->print(m_lookupArray[i]); } } int16_t LookList::findPosition(int16_t value) { for (int16_t i=0;iadd(getOperand(progCounter,0),progCounter); } return list; } /* static */ void RMFT2::begin() { //DIAG(F("EXRAIL RoutCode at =%P"),RouteCode); bool saved_diag=diag; diag=true; DCCEXParser::setRMFTFilter(RMFT2::ComandFilter); for (int f=0;fchain(LookListLoader(OPCODE_SEQUENCE)); if (compileFeatures && FEATURE_ROUTESTATE) { routeStateArray=(byte *)calloc(routeLookup->size(),sizeof(byte)); routeCaptionArray=(const FSH * *)calloc(routeLookup->size(),sizeof(const FSH *)); } onThrowLookup=LookListLoader(OPCODE_ONTHROW); onCloseLookup=LookListLoader(OPCODE_ONCLOSE); onActivateLookup=LookListLoader(OPCODE_ONACTIVATE); onDeactivateLookup=LookListLoader(OPCODE_ONDEACTIVATE); onChangeLookup=LookListLoader(OPCODE_ONCHANGE); onClockLookup=LookListLoader(OPCODE_ONTIME); #ifndef IO_NO_HAL onRotateLookup=LookListLoader(OPCODE_ONROTATE); #endif onOverloadLookup=LookListLoader(OPCODE_ONOVERLOAD); if (compileFeatures & FEATURE_BLOCK) { onBlockEnterLookup=LookListLoader(OPCODE_ONBLOCKENTER); onBlockExitLookup=LookListLoader(OPCODE_ONBLOCKEXIT); } #ifdef BOOSTER_INPUT onRailSyncOnLookup=LookListLoader(OPCODE_ONRAILSYNCON); onRailSyncOffLookup=LookListLoader(OPCODE_ONRAILSYNCOFF); #endif // onLCCLookup is not the same so not loaded here. // Second pass startup, define any turnouts or servos, set signals red // add sequences onRoutines to the lookups if (compileFeatures & FEATURE_SIGNAL) { onRedLookup=LookListLoader(OPCODE_ONRED); onAmberLookup=LookListLoader(OPCODE_ONAMBER); onGreenLookup=LookListLoader(OPCODE_ONGREEN); // Load the signal lookup with slot numbers in the signal table int signalCount=0; for (int16_t slot=0;;slot++) { SIGNAL_DEFINITION signal=getSignalSlot(slot); DIAG(F("Signal s=%d id=%d t=%d"),slot,signal.id,signal.type); if (signal.type==sigtypeNoMoreSignals) break; if (signal.type==sigtypeContinuation) continue; signalCount++; } signalLookup=new LookList(signalCount); for (int16_t slot=0;;slot++) { SIGNAL_DEFINITION signal=getSignalSlot(slot); if (signal.type==sigtypeNoMoreSignals) break; if (signal.type==sigtypeContinuation) continue; signalLookup->add(signal.id,slot); doSignal(signal.id, SIGNAL_RED); } } int progCounter; for (progCounter=0;; SKIPOP){ byte opcode=GET_OPCODE; if (opcode==OPCODE_ENDEXRAIL) break; VPIN operand=getOperand(progCounter,0); switch (opcode) { case OPCODE_AT: case OPCODE_ATTIMEOUT2: case OPCODE_AFTER: case OPCODE_IF: case OPCODE_IFNOT: { int16_t pin = (int16_t)operand; if (pin<0) pin = -pin; DIAG(F("EXRAIL input VPIN %u"),pin); IODevice::configureInput((VPIN)pin,true); break; } case OPCODE_ATGTE: case OPCODE_ATLT: case OPCODE_IFGTE: case OPCODE_IFLT: case OPCODE_IFBITMAP_ALL: case OPCODE_IFBITMAP_ANY: case OPCODE_DRIVE: { DIAG(F("EXRAIL analog input VPIN %u"),(VPIN)operand); IODevice::configureAnalogIn((VPIN)operand); break; } case OPCODE_ONSENSOR: if (compileFeatures & FEATURE_SENSOR) new EXRAILSensor(operand,progCounter+3,true ); break; case OPCODE_ONBITMAP: if (compileFeatures & FEATURE_SENSOR) new EXRAILSensor(operand,progCounter+3,true, true ); break; case OPCODE_ONBUTTON: if (compileFeatures & FEATURE_SENSOR) new EXRAILSensor(operand,progCounter+3,false ); break; case OPCODE_TURNOUT: { VPIN id=operand; int addr=getOperand(progCounter,1); byte subAddr=getOperand(progCounter,2); Turnout *t = DCCTurnout::create(id,addr,subAddr); if (t) setTurnoutHiddenState(t); break; } case OPCODE_SERVOTURNOUT: { VPIN id=operand; VPIN pin=getOperand(progCounter,1); int activeAngle=getOperand(progCounter,2); int inactiveAngle=getOperand(progCounter,3); int profile=getOperand(progCounter,4); Turnout *t = ServoTurnout::create(id,pin,activeAngle,inactiveAngle,profile); if (t) setTurnoutHiddenState(t); break; } case OPCODE_PINTURNOUT: { VPIN id=operand; VPIN pin=getOperand(progCounter,1); Turnout *t = VpinTurnout::create(id,pin); if (t) setTurnoutHiddenState(t); break; } #ifndef IO_NO_HAL case OPCODE_DCCTURNTABLE: { VPIN id=operand; int home=getOperand(progCounter,1); Turntable *tto = DCCTurntable::create(id); if (tto) { setTurntableHiddenState(tto); tto->addPosition(0,0,home); } break; } case OPCODE_EXTTTURNTABLE: { VPIN id=operand; VPIN pin=getOperand(progCounter,1); int home=getOperand(progCounter,2); Turntable *tto = EXTTTurntable::create(id,pin); if (tto) { setTurntableHiddenState(tto); tto->addPosition(0,0,home); } else { DIAG(F("Create EXTTTURNTABLE %d %d FAILED"), id, pin); } break; } case OPCODE_TTADDPOSITION: { VPIN id=operand; int position=getOperand(progCounter,1); int value=getOperand(progCounter,2); int angle=getOperand(progCounter,3); Turntable *tto=Turntable::get(id); if (tto) tto->addPosition(position,value,angle); break; } #endif case OPCODE_AUTOSTART: // automatically create a task from here at startup. // Removed if (progCounter>0) check 4.2.31 because // default start it top of file is now removed. . new RMFT2(progCounter); break; default: // Ignore break; } } SKIPOP; // include ENDROUTES opcode DIAG(F("EXRAIL %db, fl=%d"),progCounter,MAX_FLAGS); // Removed for 4.2.31 new RMFT2(0); // add the startup route diag=saved_diag; } void RMFT2::setTurnoutHiddenState(Turnout * t) { // turnout descriptions are in low flash F strings const FSH *desc = getTurnoutDescription(t->getId()); if (desc) t->setHidden(GETFLASH(desc)==0x01); } #ifndef IO_NO_HAL void RMFT2::setTurntableHiddenState(Turntable * tto) { const FSH *desc = getTurntableDescription(tto->getId()); if (desc) tto->setHidden(GETFLASH(desc)==0x01); } #endif char RMFT2::getRouteType(int16_t id) { int16_t progCounter=routeLookup->find(id); if (progCounter>=0) { byte type=GET_OPCODE; if (type==OPCODE_ROUTE) return 'R'; if (type==OPCODE_AUTOMATION) return 'A'; } return 'X'; } RMFT2::RMFT2(int progCtr, int16_t _loco, bool _invert) { progCounter=progCtr; // get an unused task id from the flags table taskId=255; // in case of overflow for (int f=0;fnext; loopTask->next=this; } } RMFT2::~RMFT2() { // estop my loco if this is not an ONevent // (prevents DONE stopping loco at the end of an // ONBLOCKENTER or ONBLOCKEXIT ) if (loco>0 && this->onEventStartPosition==-1) DCC::setThrottle(loco,1,DCC::getThrottleDirection(loco)); 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=routeLookup->find(route); if (pc<0) return; new RMFT2(pc,cab); } 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; } // This skips to the end of an if block, or to the ELSE within it. bool RMFT2::skipIfBlock() { // returns false if killed short nest = 1; while (nest > 0) { SKIPOP; byte opcode = GET_OPCODE; // all other IF type commands increase the nesting level if (opcode>IF_TYPE_OPCODES) nest++; else switch(opcode) { case OPCODE_ENDEXRAIL: kill(F("missing ENDIF"), nest); return false; case OPCODE_ENDIF: nest--; break; case OPCODE_ELSE: // if nest==1 then this is the ELSE for the IF we are skipping if (nest==1) nest=0; // cause loop exit and return after ELSE break; default: break; } } return true; } /* static */ void RMFT2::readLocoCallback(int16_t cv) { if (cv <= 0) { DIAG(F("CV read error")); progtrackLocoId = -1; return; } if (cv & LONG_ADDR_MARKER) { // maker bit indicates long addr progtrackLocoId = cv ^ LONG_ADDR_MARKER; // remove marker bit to get real long addr if (progtrackLocoId <= HIGHEST_SHORT_ADDR ) { // out of range for long addr DIAG(F("Long addr %d <= %d unsupported\n"), progtrackLocoId, HIGHEST_SHORT_ADDR); progtrackLocoId = -1; } } else { progtrackLocoId=cv; } } void RMFT2::pause() { if (loco) pauseSpeed=DCC::getThrottleSpeedByte(loco); } void RMFT2::resume() { if (loco) DCC::setThrottle(loco,pauseSpeed & 0x7f, pauseSpeed & 0x80); } void RMFT2::loop() { if (compileFeatures & FEATURE_SENSOR) EXRAILSensor::checkAll(); // Round Robin call to a RMFT task each time if (loopTask==NULL) return; loopTask=loopTask->next; if (pausingTask==NULL || pausingTask==loopTask) loopTask->loop2(); } bool RMFT2::skipIf; void RMFT2::loop2() { if (delayTime!=0 && millis()-delayStart < delayTime) return; // special stand alone blink task if (compileFeatures & FEATURE_BLINK) { if (blinkState==blink_low) { IODevice::write(blinkPin,HIGH); blinkState=blink_high; delayMe(getOperand(1)); return; } if (blinkState==blink_high) { IODevice::write(blinkPin,LOW); blinkState=blink_low; delayMe(getOperand(2)); return; } } // Normal progstep following tasks continue here. byte opcode = GET_OPCODE; int16_t operand = getOperand(0); // skipIf will get set to indicate a failing IF condition skipIf=false; // 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_TOGGLE_TURNOUT: Turnout::setClosed(operand, Turnout::isThrown(operand)); break; #ifndef IO_NO_HAL case OPCODE_ROTATE: uint8_t activity; activity=getOperand(2); Turntable::setPosition(operand,getOperand(1),activity); break; #endif case OPCODE_REV: if (loco) DCC::setThrottle(loco,operand,invert); break; case OPCODE_FWD: if (loco) DCC::setThrottle(loco,operand,!invert); break; case OPCODE_SPEED: if (loco) DCC::setThrottle(loco,operand,DCC::getThrottleDirection(loco)); break; case OPCODE_SAVE_SPEED: if (loco) DCC::saveSpeed(loco); break; case OPCODE_RESTORE_SPEED: if (loco) DCC::restoreSpeed(loco); break; case OPCODE_XSAVE_SPEED: DCC::saveSpeed(operand); break; case OPCODE_XRESTORE_SPEED: DCC::restoreSpeed(operand); break; case OPCODE_SPEEDUP: if (loco) { int8_t speed=DCC::getThrottleSpeed(loco); // do nothing if speed is 1 (emergency stop) or -1 (loco not found) if ((speed != 1) && (speed != -1)) { // handle overflow int16_t newspeed = static_cast(speed) + operand; if (newspeed > 127) { speed = 127; } else if (newspeed == 1) { speed = 2; // skip emergency stop } else { speed = static_cast(newspeed); } DCC::setThrottle(loco,speed,DCC::getThrottleDirection(loco)); } } break; case OPCODE_SPEED_REL: { if (!loco) break; auto speed=DCC::getThrottleSpeed(loco); // do nothing if speed is 0 (stop), 1 (emergency stop) or -1 (loco not found) if (speed<2) break; // cant // handle overflow auto newspeed = (speed * operand)/100; if (newspeed > 127) { speed = 127; } else if (newspeed == 1) { speed = 0; // skip emergency stop } else { speed = static_cast(newspeed); } DCC::setThrottle(loco,speed,DCC::getThrottleDirection(loco)); } break; case OPCODE_SLOWDOWN: if (loco) { int8_t speed=DCC::getThrottleSpeed(loco); // do nothing if speed is 1 (emergency stop) or -1 (loco not found) if ((speed != 1) && (speed != -1)) { // handle underflow int16_t newspeed = static_cast(speed) - operand; if (newspeed < 2) { speed = 0; // stop } else { speed = static_cast(newspeed); } DCC::setThrottle(loco,speed,DCC::getThrottleDirection(loco)); } } break; case OPCODE_MOMENTUM: DCC::setMomentum(loco,operand,getOperand(1)); break; case OPCODE_ESTOPALL: if(operand==0) DCC::estopAll(); // all locos stop else DCC::estopLock(operand==1); // stop and lock/unlock break; case OPCODE_FORGET: if (loco!=0) { DCC::forgetLoco(loco); loco=0; } break; case OPCODE_CONSIST: if (operand==0) DCCConsist::deleteAnyConsist(loco); else if (!DCCConsist::addLocoToConsist(loco, abs(operand), operand<0)) { DIAG(F("EXRAIL Failed to add Loco %d to consist %d"), abs(operand),loco); } break; case OPCODE_INVERT_DIRECTION: invert= !invert; break; case OPCODE_RESERVE: if (getFlag(operand,SECTION_FLAG)) { if (loco) DCC::setThrottle(loco,1,DCC::getThrottleDirection(loco)); delayMe(500); return; } setFlag(operand,SECTION_FLAG); break; case OPCODE_FREE: setFlag(operand,0,SECTION_FLAG); break; case OPCODE_FREEALL: for (int i=0;i= value blinkState=not_blink_task; if (IODevice::readAnalogue(operand) >= (int)(getOperand(1))) break; delayMe(50); return; case OPCODE_ATLT: // wait for analog sensor < value blinkState=not_blink_task; if (IODevice::readAnalogue(operand) < (int)(getOperand(1))) break; delayMe(50); return; case OPCODE_ATTIMEOUT1: // ATTIMEOUT(vpin,timeout) part 1 timeoutStart=millis(); blinkState=not_blink_task; break; case OPCODE_ATTIMEOUT2: if (readSensor(operand)) break; // success without timeout if (millis()-timeoutStart > 100*getOperand(1)) { blinkState=at_timeout; break; // and drop through } delayMe(50); return; case OPCODE_IFTIMEOUT: // do next operand if timeout flag set skipIf=blinkState!=at_timeout; break; case OPCODE_AFTER: // waits for sensor to hit and then remain off for x mS. // Note, this must come after an AT operation, which is // automatically inserted by the AFTER macro. if (readSensor(operand)) { // reset timer and keep waiting waitAfter=millis(); delayMe(50); return; } if (millis()-waitAfter < getOperand(1) ) return; break; case OPCODE_AFTEROVERLOAD: // waits for the power to be turned back on - either by power routine or button if (!TrackManager::isPowerOn(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: case OPCODE_RESET: { auto count=getOperand(1); for (uint16_t i=0;iblinkPin=operand; newtask->blinkState=blink_low; // will go high on first call } break; case OPCODE_PAUSE: DCC::estopAll(); // pause all locos on the track pausingTask=this; break; case OPCODE_POM: if (loco) DCC::writeCVByteMain(loco, operand, getOperand(1)); break; case OPCODE_XPOM: DCC::writeCVByteMain(operand, getOperand(1), getOperand(2)); break; case OPCODE_POWEROFF: TrackManager::setPower(POWERMODE::OFF); TrackManager::setJoin(false); break; case OPCODE_SET_POWER: // operand is TRACK_POWER , trackid //byte thistrack=getOperand(1); switch (operand) { case TRACK_POWER_0: TrackManager::setTrackPower(POWERMODE::OFF, getOperand(1)); break; case TRACK_POWER_1: TrackManager::setTrackPower(POWERMODE::ON, getOperand(1)); break; } break; case OPCODE_SET_TRACK: // operand is trackmode<<8 | track id // If DC/DCX use my loco for DC address { TRACK_MODE mode = (TRACK_MODE)(operand>>8); int16_t cab=(mode & TRACK_MODE_DC) ? loco : 0; TrackManager::setTrackMode(operand & 0x0F, mode, cab); } break; case OPCODE_SETFREQ: // Frequency is default 0, or 1, 2,3 DCC::setDCFreq(loco,operand); break; case OPCODE_RESUME: pausingTask=NULL; resume(); for (RMFT2 * t=next; t!=this;t=t->next) t->resume(); break; case OPCODE_IF: // do next operand if sensor set skipIf=!readSensor(operand); break; case OPCODE_ELSE: // skip to matching ENDIF skipIf=true; break; case OPCODE_IFGTE: // do next operand if sensor>= value skipIf=IODevice::readAnalogue(operand)<(int)(getOperand(1)); break; case OPCODE_IFLT: // do next operand if sensor< value skipIf=IODevice::readAnalogue(operand)>=(int)(getOperand(1)); break; case OPCODE_IFBITMAP_ALL: // do next operand if sensor & mask == mask skipIf=(IODevice::readAnalogue(operand) & getOperand(1)) != getOperand(1); break; case OPCODE_IFBITMAP_ANY: // do next operand if sensor & mask !=0 skipIf=(IODevice::readAnalogue(operand) & getOperand(1)) == 0; break; case OPCODE_IFNOT: // do next operand if sensor not set skipIf=readSensor(operand); break; case OPCODE_IFRE: // do next operand if rotary encoder != position skipIf=IODevice::readAnalogue(operand)!=(int)(getOperand(1)); break; case OPCODE_IFRANDOM: // do block on random percentage skipIf=(uint8_t)micros() >= operand * 255/100; break; case OPCODE_IFRESERVE: // do block if we successfully RERSERVE if (!getFlag(operand,SECTION_FLAG)) setFlag(operand,SECTION_FLAG); else skipIf=true; break; case OPCODE_IFRED: // do block if signal as expected skipIf=!isSignal(operand,SIGNAL_RED); break; case OPCODE_WAIT_WHILE_RED: // do block if signal as expected if (isSignal(operand,SIGNAL_RED)) { if (loco && (DCC::getLocoSpeedByte(loco) & 0x7f)>1) DCC::setThrottle(loco,0,DCC::getThrottleDirection(loco)); delayMe(500); return; } break; case OPCODE_IFAMBER: // do block if signal as expected skipIf=!isSignal(operand,SIGNAL_AMBER); break; case OPCODE_IFGREEN: // do block if signal as expected skipIf=!isSignal(operand,SIGNAL_GREEN); break; case OPCODE_IFTHROWN: skipIf=Turnout::isClosed(operand); break; case OPCODE_IFCLOSED: skipIf=Turnout::isThrown(operand); break; case OPCODE_IFSTASH: skipIf=Stash::get(operand)==0; break; case OPCODE_IFSTASHED_HERE: skipIf=(Stash::get(operand) & 0x7FFF)!=loco; break; #ifndef IO_NO_HAL case OPCODE_IFTTPOSITION: // do block if turntable at this position skipIf=Turntable::getPosition(operand)!=(int)getOperand(1); break; #endif case OPCODE_ENDIF: break; case OPCODE_DELAYMS: delayMe(operand); break; case OPCODE_DELAY: delayMe(operand*100L); break; case OPCODE_DELAYMINS: delayMe(operand*60L*1000L); break; case OPCODE_RANDWAIT: delayMe(operand==0 ? 0 : (micros()%operand) *100L); break; case OPCODE_RED: doSignal(operand,SIGNAL_RED); break; case OPCODE_AMBER: doSignal(operand,SIGNAL_AMBER); break; case OPCODE_GREEN: doSignal(operand,SIGNAL_GREEN); 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_FTOGGLE: if (loco) DCC::changeFn(loco,operand); break; case OPCODE_DRIVE: { // Non functional but reserved break; } case OPCODE_XFON: DCC::setFn(operand,getOperand(1),true); break; case OPCODE_XFOFF: DCC::setFn(operand,getOperand(1),false); break; case OPCODE_XFTOGGLE: DCC::changeFn(operand,getOperand(1)); break; case OPCODE_XFWD: DCC::setThrottle(operand,getOperand(1), true); break; case OPCODE_XREV: DCC::setThrottle(operand,getOperand(1), false); break; case OPCODE_DCCACTIVATE: { // operand is address<<3 | subaddr<<1 | active int16_t addr=operand>>3; int16_t subaddr=(operand>>1) & 0x03; bool active=operand & 0x01; DCC::setAccessory(addr,subaddr,active); break; } case OPCODE_ASPECT: { // operand is address<<5 | value int16_t address=operand>>5; byte aspect=operand & 0x1f; if (!signalAspectEvent(address,aspect)) DCC::setExtendedAccessory(address,aspect); break; } case OPCODE_FOLLOW: progCounter=routeLookup->find(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=routeLookup->find(operand); if (progCounter<0) kill(F("CALL unknown"),operand); return; case OPCODE_RANDOM_FOLLOW: // operand is number to choose from { auto newroute=getOperand(1+(millis()%operand)); progCounter=routeLookup->find(newroute); if (progCounter<0) kill(F("RANDOM_FOLLOW unknown"), newroute); } return; case OPCODE_RANDOM_CALL: // operand is number to choose from if (stackDepth==MAX_STACK_DEPTH) { kill(F("CALL stack"), stackDepth); return; } { auto newroute=getOperand(1+(millis()%operand)); // return position is after the RANDOM_CALL + all its operands callStack[stackDepth++]=progCounter+3*(operand+1); progCounter=routeLookup->find(newroute); if (progCounter<0) kill(F("CALL unknown"),newroute); } 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_KILLALL: while(loopTask) loopTask->kill(F("KILLALL")); return; #ifndef DISABLE_PROG case OPCODE_JOIN: TrackManager::setJoin(true); TrackManager::setMainPower(POWERMODE::ON); TrackManager::setProgPower(POWERMODE::ON); break; case OPCODE_UNJOIN: TrackManager::setJoin(false); break; case OPCODE_READ_LOCO1: // READ_LOCO is implemented as 2 separate opcodes progtrackLocoId=LOCO_ID_WAITING; // Nothing found yet DCC::getDriveawayLocoId(readLocoCallback); break; case OPCODE_READ_LOCO2: if (progtrackLocoId==LOCO_ID_WAITING) { delayMe(100); return; // still waiting for callback } // At failed read will result in loco == -1 // which is intended so it can be checked // from within EXRAIL loco=progtrackLocoId; invert=false; break; #endif case OPCODE_POWERON: TrackManager::setMainPower(POWERMODE::ON); TrackManager::setJoin(false); break; case OPCODE_START: { int newPc=routeLookup->find(operand); if (newPc<0) break; new RMFT2(newPc); } break; case OPCODE_START_SHARED: { int newPc=routeLookup->find(operand); if (newPc<0) break; new RMFT2(newPc,loco, invert); // create new task and share loco } break; case OPCODE_START_SEND: { int newPc=routeLookup->find(operand); if (newPc<0) break; new RMFT2(newPc,loco, invert); // create new task and send loco exclusive loco = 0; } break; case OPCODE_SENDLOCO: // cab, route { int newPc=routeLookup->find(getOperand(1)); if (newPc<0) break; new RMFT2(newPc,operand); // create new task } break; case OPCODE_SETLOCO: { loco=operand; invert=false; } break; case OPCODE_LCC: // short form LCC if ((compileFeatures & FEATURE_LCC) && LCCSerial) StringFormatter::send(LCCSerial,F(""),(uint16_t)operand); break; case OPCODE_ACON: // MERG adapter case OPCODE_ACOF: if ((compileFeatures & FEATURE_LCC) && LCCSerial) StringFormatter::send(LCCSerial,F(""), opcode==OPCODE_ACON?'0':'1', (uint16_t)operand,getOperand(progCounter,1)); break; case OPCODE_LCCX: // long form LCC if ((compileFeatures & FEATURE_LCC) && LCCSerial) StringFormatter::send(LCCSerial,F("\n"), getOperand(progCounter,1), getOperand(progCounter,2), getOperand(progCounter,3), getOperand(progCounter,0) ); break; case OPCODE_SERVO: // OPCODE_SERVO,V(vpin),OPCODE_PAD,V(position),OPCODE_PAD,V(profile),OPCODE_PAD,V(duration) IODevice::writeAnalogue(operand,getOperand(1),getOperand(2),getOperand(3)); break; case OPCODE_WAITFOR: // OPCODE_SERVO,V(pin) if (IODevice::isBusy(operand)) { delayMe(100); return; } break; #ifndef IO_NO_HAL case OPCODE_NEOPIXEL: // OPCODE_NEOPIXEL,V([-]vpin),OPCODE_PAD,V(colour_RG),OPCODE_PAD,V(colour_B),OPCODE_PAD,V(count) { VPIN vpin=operand>0?operand:-operand; auto count=getOperand(3); killBlinkOnVpin(vpin,count); IODevice::writeAnalogueRange(vpin,getOperand(1),operand>0,getOperand(2),count); } break; case OPCODE_WAITFORTT: // OPCODE_WAITFOR,V(turntable_id) if (Turntable::ttMoving(operand)) { delayMe(100); return; } break; #endif /* IFLOCO and PRINT use code generated in printMessage but IFLOCO is recognized as an IF when doing IF/ELSE/ENDINF skipping */ case OPCODE_IFLOCO: case OPCODE_PRINT: printMessage(operand); break; // Route state management case OPCODE_ROUTE_HIDDEN: manageRouteState(operand,2); break; case OPCODE_ROUTE_INACTIVE: manageRouteState(operand,0); break; case OPCODE_ROUTE_ACTIVE: manageRouteState(operand,1); break; case OPCODE_ROUTE_DISABLED: manageRouteState(operand,4); break; // Route state management case OPCODE_IF_ROUTE_HIDDEN: skipIf=!ifRouteState(operand,2); break; case OPCODE_IF_ROUTE_INACTIVE: skipIf=!ifRouteState(operand,0); break; case OPCODE_IF_ROUTE_ACTIVE: skipIf=!ifRouteState(operand,1); break; case OPCODE_IF_ROUTE_DISABLED: skipIf=!ifRouteState(operand,4); break; case OPCODE_STASH: Stash::set(operand,invert? -loco : loco); break; case OPCODE_CLEAR_STASH: Stash::clear(operand); break; case OPCODE_CLEAR_ALL_STASH: Stash::clearAll(); break; case OPCODE_CLEAR_ANY_STASH: if (loco) Stash::clearAny(loco); break; case OPCODE_PICKUP_STASH: { auto x=Stash::get(operand); if (x>=0) { loco=x; invert=false; } else { loco=-x; invert=true; } } break; case OPCODE_ROUTE: case OPCODE_AUTOMATION: case OPCODE_SEQUENCE: //if (diag) DIAG(F("EXRAIL begin(%d)"),operand); break; case OPCODE_BITMAP_INC: IODevice::writeAnalogue(operand,IODevice::readAnalogue(operand)+1); break; case OPCODE_BITMAP_DEC: { int newval=IODevice::readAnalogue(operand)-1; if (newval<0) newval=0; IODevice::writeAnalogue(operand,newval); } break; case OPCODE_BITMAP_AND: IODevice::writeAnalogue(operand,IODevice::readAnalogue(operand) & getOperand(1)); break; case OPCODE_BITMAP_OR: IODevice::writeAnalogue(operand,IODevice::readAnalogue(operand) | getOperand(1)); break; case OPCODE_BITMAP_XOR: IODevice::writeAnalogue(operand,IODevice::readAnalogue(operand) ^ getOperand(1)); break; case OPCODE_AUTOSTART: // Handled only during begin process case OPCODE_PAD: // Just a padding for previous opcode needing >1 operand byte. 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 catchers ignored here case OPCODE_ONLCC: // LCC event catchers ignored here case OPCODE_ONACON: // MERG event catchers ignored here case OPCODE_ONACOF: // MERG event catchers ignored here case OPCODE_ONTHROW: case OPCODE_ONACTIVATE: // Activate event catchers ignored here case OPCODE_ONDEACTIVATE: case OPCODE_ONRED: case OPCODE_ONAMBER: case OPCODE_ONGREEN: case OPCODE_ONCHANGE: case OPCODE_ONTIME: case OPCODE_ONBUTTON: case OPCODE_ONSENSOR: case OPCODE_ONBITMAP: #ifndef IO_NO_HAL case OPCODE_DCCTURNTABLE: // Turntable definition ignored at runtime case OPCODE_EXTTTURNTABLE: // Turntable definition ignored at runtime case OPCODE_TTADDPOSITION: // Turntable position definition ignored at runtime case OPCODE_ONROTATE: #endif case OPCODE_ONOVERLOAD: case OPCODE_ONBLOCKENTER: case OPCODE_ONBLOCKEXIT: #ifdef BOOSTER_INPUT case OPCODE_ONRAILSYNCON: case OPCODE_ONRAILSYNCOFF: #endif break; default: kill(F("INVOP"),operand); } // Falling out of the switch means move on to the next opcode // but if we are skipping a false IF or else if (skipIf) if (!skipIfBlock()) return; SKIPOP; } void RMFT2::delayMe(long delay) { delayTime=delay; delayStart=millis(); } bool RMFT2::setFlag(VPIN id,byte onMask, byte offMask) { if (FLAGOVERFLOW(id)) return false; // Outside range limit byte f=flags[id]; f &= ~offMask; f |= onMask; flags[id]=f; return true; } 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; } SIGNAL_DEFINITION RMFT2::getSignalSlot(int16_t slot) { SIGNAL_DEFINITION signal; COPYHIGHFLASH(&signal,SignalDefinitions,slot*sizeof(SIGNAL_DEFINITION),sizeof(SIGNAL_DEFINITION)); return signal; } /* static */ void RMFT2::doSignal(int16_t id,char rag) { if (!(compileFeatures & FEATURE_SIGNAL)) return; // dont compile code below //if (diag) DIAG(F(" doSignal %d %x"),id,rag); // Schedule any event handler for this signal change. // This will work even without a signal definition. if (rag==SIGNAL_RED) onRedLookup->handleEvent(F("RED"),id); else if (rag==SIGNAL_GREEN) onGreenLookup->handleEvent(F("GREEN"),id); else onAmberLookup->handleEvent(F("AMBER"),id); auto sigslot=signalLookup->find(id); if (sigslot<0) return; // keep track of signal state setFlag(sigslot,rag,SIGNAL_MASK); // Correct signal definition found, get the rag values auto signal=getSignalSlot(sigslot); switch (signal.type) { case sigtypeSERVO: { auto servopos = rag==SIGNAL_RED? signal.redpin: (rag==SIGNAL_GREEN? signal.greenpin : signal.amberpin); //if (diag) DIAG(F("sigA %d %d"),id,servopos); if (servopos!=0) IODevice::writeAnalogue(id,servopos,PCA9685::Bounce); return; } case sigtypeDCC: { // redpin,amberpin are the DCC addr,subaddr DCC::setAccessory(signal.redpin,signal.amberpin, rag!=SIGNAL_RED); return; } case sigtypeDCCX: { // redpin,amberpin,greenpin are the 3 aspects auto value=signal.redpin; if (rag==SIGNAL_AMBER) value=signal.amberpin; if (rag==SIGNAL_GREEN) value=signal.greenpin; DCC::setExtendedAccessory(id, value); return; } case sigtypeNEOPIXEL: { // redpin,amberpin,greenpin are the 3 RG values but with no blue permitted. . (code limitation hack) auto colour_RG=signal.redpin; if (rag==SIGNAL_AMBER) colour_RG=signal.amberpin; if (rag==SIGNAL_GREEN) colour_RG=signal.greenpin; // blue channel is in followng signal slot (a continuation) auto signal2=getSignalSlot(sigslot+1); auto colour_B=signal2.redpin; if (rag==SIGNAL_AMBER) colour_B=signal2.amberpin; if (rag==SIGNAL_GREEN) colour_B=signal2.greenpin; IODevice::writeAnalogue(id, colour_RG,true,colour_B); return; } case sigtypeSIGNAL: case sigtypeSIGNALH: { // LED or similar 3 pin signal, (all pins zero would be a virtual signal) // If amberpin is zero, synthesise amber from red+green const byte SIMAMBER=0x00; if (rag==SIGNAL_AMBER && (signal.amberpin==0)) rag=SIMAMBER; // special case this func only // Manage invert (HIGH on) pins bool aHigh=signal.type==sigtypeSIGNALH; // set the three pins if (signal.redpin) { bool redval=(rag==SIGNAL_RED || rag==SIMAMBER); if (!aHigh) redval=!redval; killBlinkOnVpin(signal.redpin); IODevice::write(signal.redpin,redval); } if (signal.amberpin) { bool amberval=(rag==SIGNAL_AMBER); if (!aHigh) amberval=!amberval; killBlinkOnVpin(signal.amberpin); IODevice::write(signal.amberpin,amberval); } if (signal.greenpin) { bool greenval=(rag==SIGNAL_GREEN || rag==SIMAMBER); if (!aHigh) greenval=!greenval; killBlinkOnVpin(signal.greenpin); IODevice::write(signal.greenpin,greenval); } } case sigtypeVIRTUAL: break; case sigtypeContinuation: break; case sigtypeNoMoreSignals: break; } } /* static */ bool RMFT2::isSignal(int16_t id,char rag) { if (!(compileFeatures & FEATURE_SIGNAL)) return false; int16_t sigslot=signalLookup->find(id); if (sigslot<0) return false; return (flags[sigslot] & SIGNAL_MASK) == rag; } // signalAspectEvent returns true if the aspect is destined // for a defined DCCX_SIGNAL which will handle all the RAG flags // and ON* handlers. // Otherwise false so the parser should send the command directly bool RMFT2::signalAspectEvent(int16_t address, byte aspect ) { if (!(compileFeatures & FEATURE_SIGNAL)) return false; auto sigslot=signalLookup->find(address); if (sigslot<0) return false; // this is not a defined signal auto signal=getSignalSlot(sigslot); if (signal.type!=sigtypeDCCX) return false; // not a DCCX signal // Turn an aspect change into a RED/AMBER/GREEN setting if (aspect==signal.redpin) { doSignal(address,SIGNAL_RED); return true; } if (aspect==signal.amberpin) { doSignal(address,SIGNAL_AMBER); return true; } if (aspect==signal.greenpin) { doSignal(address,SIGNAL_GREEN); return true; } return false; // aspect is not a defined one } void RMFT2::turnoutEvent(int16_t turnoutId, bool closed) { // Hunt for an ONTHROW/ONCLOSE for this turnout if (closed) onCloseLookup->handleEvent(F("CLOSE"),turnoutId); else onThrowLookup->handleEvent(F("THROW"),turnoutId); } void RMFT2::activateEvent(int16_t addr, bool activate) { // Hunt for an ONACTIVATE/ONDEACTIVATE for this accessory if (activate) onActivateLookup->handleEvent(F("ACTIVATE"),addr); else onDeactivateLookup->handleEvent(F("DEACTIVATE"),addr); } void RMFT2::blockEvent(int16_t block, int16_t loco, bool entering) { if (compileFeatures & FEATURE_BLOCK) { // Hunt for an ONBLOCKENTER/ONBLOCKEXIT for this accessory if (entering) onBlockEnterLookup->handleEvent(F("BLOCKENTER"),block,loco); else onBlockExitLookup->handleEvent(F("BLOCKEXIT"),block,loco); } } void RMFT2::changeEvent(int16_t vpin, bool change) { // Hunt for an ONCHANGE for this sensor if (change) onChangeLookup->handleEvent(F("CHANGE"),vpin); } #ifndef IO_NO_HAL void RMFT2::rotateEvent(int16_t turntableId, bool change) { // Hunt or an ONROTATE for this turntable if (change) onRotateLookup->handleEvent(F("ROTATE"),turntableId); } #endif void RMFT2::clockEvent(int16_t clocktime, bool change) { // Hunt for an ONTIME for this time if (Diag::CMD) DIAG(F("clockEvent at : %d"), clocktime); if (change) { onClockLookup->handleEvent(F("CLOCK"),clocktime); onClockLookup->handleEvent(F("CLOCK"),25*60+clocktime%60); } } void RMFT2::powerEvent(int16_t track, bool overload) { // Hunt for an ONOVERLOAD for this item if (Diag::CMD) DIAG(F("powerEvent : %c"), track + 'A'); if (overload) { onOverloadLookup->handleEvent(F("POWER"),track); } } #ifdef BOOSTER_INPUT void RMFT2::railsyncEvent(bool on) { if (Diag::CMD) DIAG(F("railsyncEvent : %d"), on); if (on) { if (onRailSyncOnLookup) onRailSyncOnLookup->handleEvent(F("RAILSYNCON"), 0); } else { if (onRailSyncOffLookup) onRailSyncOffLookup->handleEvent(F("RAILSYNCOFF"), 0); } } #endif // This function is used when setting pins so that a SET or RESET // will cause any blink task on that pin to terminate. // It will be compiled out of existence if no BLINK feature is used. void RMFT2::killBlinkOnVpin(VPIN pin, uint16_t count) { if (!(compileFeatures & FEATURE_BLINK)) return; RMFT2 * stoptask=loopTask; // stop when we get back to here RMFT2 * task=loopTask; VPIN lastPin=pin+count-1; while(task) { auto nextTask=task->next; if ( (task->blinkState==blink_high || task->blinkState==blink_low) && task->blinkPin>=pin && task->blinkPin<=lastPin ) { if (diag) DIAG(F("kill blink %d"),task->blinkPin,lastPin); task->kill(); } task=nextTask; if (task==stoptask) return; } } void RMFT2::startNonRecursiveTask(const FSH* reason, int16_t id,int pc, uint16_t loco) { // Check we dont already have a task running this handler RMFT2 * task=loopTask; while(task) { if (task->onEventStartPosition==pc && task->loco==loco) { DIAG(F("Recursive ON%S(%d)"),reason, id); return; } task=task->next; if (task==loopTask) break; } task=new RMFT2(pc,loco); // new task starts at this instruction task->onEventStartPosition=pc; // flag for recursion detector } void RMFT2::printMessage2(const FSH * msg) { DIAG(F("EXRAIL(%d) %S"),loco,msg); } static StringBuffer * buffer=NULL; /* thrungeString is used to stream a HIGHFLASH string to a suitable Serial and handle the oddities like LCD, BROADCAST and PARSE */ void RMFT2::thrungeString(uint32_t strfar, thrunger mode, byte id) { //DIAG(F("thrunge addr=%l mode=%d id=%d"), strfar,mode,id); Print * stream=NULL; // Find out where the string is going switch (mode) { case thrunge_print: StringFormatter::send(&USB_SERIAL,F("<* EXRAIL(%d) "),loco); stream=&USB_SERIAL; break; case thrunge_serial: stream=&USB_SERIAL; break; case thrunge_serial1: #ifdef SERIAL1_COMMANDS stream=&Serial1; #endif break; case thrunge_serial2: #ifdef SERIAL2_COMMANDS stream=&Serial2; #endif break; case thrunge_serial3: #ifdef SERIAL3_COMMANDS stream=&Serial3; #endif break; case thrunge_serial4: #ifdef SERIAL4_COMMANDS stream=&Serial4; #endif break; case thrunge_serial5: #ifdef SERIAL5_COMMANDS stream=&Serial5; #endif break; case thrunge_serial6: #ifdef SERIAL6_COMMANDS stream=&Serial6; #endif break; case thrunge_lcn: #if defined(LCN_SERIAL) stream=&LCN_SERIAL; #endif break; case thrunge_parse: case thrunge_broadcast: case thrunge_message: case thrunge_lcd: default: // thrunge_lcd+1, ... if (!buffer) buffer=new StringBuffer(); buffer->flush(); stream=buffer; break; } if (!stream) return; #if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560) // if mega stream it out for (;;strfar++) { char c=pgm_read_byte_far(strfar); if (c=='\0') break; stream->write(c); } #else // UNO/NANO CPUs dont have high memory // 32 bit cpus dont care anyway stream->print((FSH *)strfar); #endif // and decide what to do next switch (mode) { case thrunge_print: StringFormatter::send(&USB_SERIAL,F(" *>\n")); break; // TODO more serials for SAMx case thrunge_serial4: stream=&Serial4; break; case thrunge_parse: DCCEXParser::parseOne(&USB_SERIAL,(byte*)buffer->getString(),NULL); break; case thrunge_broadcast: CommandDistributor::broadcastRaw(CommandDistributor::COMMAND_TYPE,buffer->getString()); break; case thrunge_withrottle: CommandDistributor::broadcastRaw(CommandDistributor::WITHROTTLE_TYPE,buffer->getString()); break; case thrunge_message: CommandDistributor::broadcastMessage(buffer->getString()); break; case thrunge_lcd: LCD(id,F("%s"),buffer->getString()); break; default: // thrunge_lcd+1, ... if (mode > thrunge_lcd) SCREEN(mode-thrunge_lcd, id, F("%s"),buffer->getString()); // print to other display break; } } void RMFT2::manageRouteState(int16_t id, byte state) { if (compileFeatures && FEATURE_ROUTESTATE) { // Route state must be maintained for when new throttles connect. // locate route id in the Routes lookup int16_t position=routeLookup->findPosition(id); if (position<0) return; // set state beside it if (routeStateArray[position]==state) return; routeStateArray[position]=state; CommandDistributor::broadcastRouteState(id,state); } } bool RMFT2::ifRouteState(int16_t id, byte state) { if (compileFeatures && FEATURE_ROUTESTATE) { // Route state must be maintained for when new throttles connect. // locate route id in the Routes lookup int16_t position=routeLookup->findPosition(id); return position>=0 && routeStateArray[position]==state; } else return false; } void RMFT2::manageRouteCaption(int16_t id,const FSH* caption) { if (compileFeatures && FEATURE_ROUTESTATE) { // Route state must be maintained for when new throttles connect. // locate route id in the Routes lookup int16_t position=routeLookup->findPosition(id); if (position<0) return; // set state beside it if (routeCaptionArray[position]==caption) return; routeCaptionArray[position]=caption; CommandDistributor::broadcastRouteCaption(id,caption); } } void RMFT2::ifAnyFunc(const int16_t * vpinList, int16_t count) { // Sets skipIf if none found skipIf=false; for (int v=0;v0) return; } skipIf=true; // none found } void RMFT2::ifAllFunc(const int16_t * vpinList, int16_t count) { skipIf=true; // return skipping if any are wrong for (int v=0;v0) return; if (IODevice::read(vpin)==0) return; } skipIf=false; // no failures found } ================================================ FILE: EXRAIL2.h ================================================ /* * © 2021 Neil McKechnie * © 2020-2025 Chris Harlow * © 2022-2023 Colin Murdoch * © 2023 Harald Barth * © 2025 Morten Nielsen * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef EXRAIL2_H #define EXRAIL2_H #include "FSH.h" #include "IODevice.h" #include "Turnouts.h" #include "Turntables.h" // The following are the operation codes (or instructions) for a kind of virtual machine. // Each instruction is normally 3 bytes long with an operation code followed by a parameter. // In cases where more than one parameter is required, the first parameter is followed by one // or more OPCODE_PAD instructions with the subsequent parameters. This wastes a byte but makes // searching easier as a parameter can never be confused with an opcode. // enum OPCODE : byte {OPCODE_THROW,OPCODE_CLOSE,OPCODE_TOGGLE_TURNOUT, OPCODE_FWD,OPCODE_REV,OPCODE_SPEED, OPCODE_SPEEDUP,OPCODE_SLOWDOWN,OPCODE_SPEED_REL,OPCODE_INVERT_DIRECTION, OPCODE_MOMENTUM, OPCODE_RESERVE,OPCODE_FREE, OPCODE_AT,OPCODE_AFTER, OPCODE_AFTEROVERLOAD,OPCODE_AUTOSTART, OPCODE_ATGTE,OPCODE_ATLT, OPCODE_ATTIMEOUT1,OPCODE_ATTIMEOUT2, OPCODE_LATCH,OPCODE_UNLATCH,OPCODE_SET,OPCODE_RESET, OPCODE_BLINK, OPCODE_ENDIF,OPCODE_ELSE, OPCODE_DELAY,OPCODE_DELAYMINS,OPCODE_DELAYMS,OPCODE_RANDWAIT, OPCODE_FON,OPCODE_FOFF,OPCODE_XFON,OPCODE_XFOFF, OPCODE_FTOGGLE,OPCODE_XFTOGGLE,OPCODE_XFWD,OPCODE_XREV, OPCODE_RED,OPCODE_GREEN,OPCODE_AMBER,OPCODE_DRIVE, OPCODE_SERVO,OPCODE_SIGNAL,OPCODE_TURNOUT,OPCODE_WAITFOR, OPCODE_PAD,OPCODE_FOLLOW,OPCODE_CALL,OPCODE_RETURN, #ifndef DISABLE_PROG OPCODE_JOIN,OPCODE_UNJOIN,OPCODE_READ_LOCO1,OPCODE_READ_LOCO2, #endif OPCODE_POM, OPCODE_START,OPCODE_START_SHARED,OPCODE_START_SEND,OPCODE_SETLOCO,OPCODE_SETFREQ,OPCODE_SENDLOCO,OPCODE_FORGET, OPCODE_PAUSE, OPCODE_RESUME,OPCODE_POWEROFF,OPCODE_POWERON, OPCODE_ONCLOSE, OPCODE_ONTHROW, OPCODE_SERVOTURNOUT, OPCODE_PINTURNOUT, OPCODE_PRINT,OPCODE_DCCACTIVATE,OPCODE_ASPECT, OPCODE_ONACTIVATE,OPCODE_ONDEACTIVATE, OPCODE_ROSTER,OPCODE_KILLALL, OPCODE_ROUTE,OPCODE_AUTOMATION,OPCODE_SEQUENCE, OPCODE_ENDTASK,OPCODE_ENDEXRAIL, OPCODE_SET_TRACK,OPCODE_SET_POWER, OPCODE_ONRED,OPCODE_ONAMBER,OPCODE_ONGREEN, OPCODE_ONCHANGE, OPCODE_ONCLOCKTIME, OPCODE_ONTIME, OPCODE_TTADDPOSITION,OPCODE_DCCTURNTABLE,OPCODE_EXTTTURNTABLE, OPCODE_ONROTATE,OPCODE_ROTATE,OPCODE_WAITFORTT, OPCODE_LCC,OPCODE_LCCX,OPCODE_ONLCC, OPCODE_ACON, OPCODE_ACOF, OPCODE_ONACON, OPCODE_ONACOF, OPCODE_ONOVERLOAD, OPCODE_ONRAILSYNCON,OPCODE_ONRAILSYNCOFF, OPCODE_ROUTE_ACTIVE,OPCODE_ROUTE_INACTIVE,OPCODE_ROUTE_HIDDEN, OPCODE_ROUTE_DISABLED, OPCODE_STASH,OPCODE_CLEAR_STASH,OPCODE_CLEAR_ALL_STASH,OPCODE_PICKUP_STASH, OPCODE_CLEAR_ANY_STASH, OPCODE_ONBUTTON,OPCODE_ONSENSOR,OPCODE_ONVP_SENSOR, OPCODE_NEOPIXEL, OPCODE_ONBLOCKENTER,OPCODE_ONBLOCKEXIT, OPCODE_ESTOPALL,OPCODE_XPOM, OPCODE_BITMAP_AND,OPCODE_BITMAP_OR,OPCODE_BITMAP_XOR,OPCODE_BITMAP_INC,OPCODE_BITMAP_DEC,OPCODE_ONBITMAP, OPCODE_FREEALL, OPCODE_WAIT_WHILE_RED, OPCODE_SAVE_SPEED,OPCODE_RESTORE_SPEED, OPCODE_XSAVE_SPEED,OPCODE_XRESTORE_SPEED, OPCODE_RANDOM_CALL,OPCODE_RANDOM_FOLLOW, OPCODE_CONSIST, // OPcodes below this point are skip-nesting IF operations // placed here so that they may be skipped as a group // see skipIfBlock() IF_TYPE_OPCODES, // do not move this... OPCODE_IFRED,OPCODE_IFAMBER,OPCODE_IFGREEN, OPCODE_IFGTE,OPCODE_IFLT, OPCODE_IFTIMEOUT, OPCODE_IF,OPCODE_IFNOT, OPCODE_IFRANDOM,OPCODE_IFRESERVE, OPCODE_IFCLOSED,OPCODE_IFTHROWN, OPCODE_IFRE, OPCODE_IFLOCO, OPCODE_IFTTPOSITION, OPCODE_IFSTASH, OPCODE_IFSTASHED_HERE, OPCODE_IFBITMAP_ALL,OPCODE_IFBITMAP_ANY, OPCODE_IF_ROUTE_ACTIVE,OPCODE_IF_ROUTE_INACTIVE, OPCODE_IF_ROUTE_HIDDEN,OPCODE_IF_ROUTE_DISABLED, }; // Ensure thrunge_lcd is put last as there may be more than one display, // sequentially numbered from thrunge_lcd. enum thrunger: byte { thrunge_print, thrunge_broadcast, thrunge_withrottle, thrunge_serial,thrunge_parse, thrunge_serial1, thrunge_serial2, thrunge_serial3, thrunge_serial4, thrunge_serial5, thrunge_serial6, thrunge_lcn,thrunge_message, thrunge_lcd, // Must be last!! }; enum BlinkState: byte { not_blink_task, blink_low, // blink task running with pin LOW blink_high, // blink task running with pin high at_timeout // ATTIMEOUT timed out flag }; enum SignalType { sigtypeVIRTUAL, sigtypeSIGNAL, sigtypeSIGNALH, sigtypeDCC, sigtypeDCCX, sigtypeSERVO, sigtypeNEOPIXEL, sigtypeContinuation, // neopixels require a second line sigtypeNoMoreSignals }; struct SIGNAL_DEFINITION { SignalType type; VPIN id; VPIN redpin,amberpin,greenpin; }; // Flag bits for compile time features. static const byte FEATURE_SIGNAL= 0x80; static const byte FEATURE_LCC = 0x40; static const byte FEATURE_ROSTER= 0x20; static const byte FEATURE_ROUTESTATE= 0x10; // spare = 0x08; static const byte FEATURE_BLINK = 0x04; static const byte FEATURE_SENSOR = 0x02; static const byte FEATURE_BLOCK = 0x01; // Flag bits for status of hardware and TPL static const byte SECTION_FLAG = 0x80; static const byte LATCH_FLAG = 0x40; static const byte TASK_FLAG = 0x20; static const byte SPARE_FLAG = 0x10; static const byte SIGNAL_MASK = 0x0C; static const byte SIGNAL_RED = 0x08; static const byte SIGNAL_AMBER = 0x0C; static const byte SIGNAL_GREEN = 0x04; static const byte MAX_STACK_DEPTH=4; static const short MAX_FLAGS=256; #define FLAGOVERFLOW(x) x>=MAX_FLAGS class LookList { public: LookList(int16_t size); void chain(LookList* chainTo); void add(int16_t lookup, int16_t result); int16_t find(int16_t value); // finds result value int16_t findPosition(int16_t value); // finds index int16_t size(); void stream(Print * _stream); void handleEvent(const FSH* reason,int16_t id, int16_t loco=0); private: int16_t m_size; int16_t m_loaded; int16_t * m_lookupArray; int16_t * m_resultArray; LookList* m_chain; }; class RMFT2 { public: static void begin(); static void loop(); RMFT2(int progCounter, int16_t cab=0, bool invert=false); ~RMFT2(); static void readLocoCallback(int16_t cv); static void createNewTask(int route, uint16_t cab); static void turnoutEvent(int16_t id, bool closed); static void activateEvent(int16_t addr, bool active); static void changeEvent(int16_t id, bool change); static void clockEvent(int16_t clocktime, bool change); static void rotateEvent(int16_t id, bool change); static void powerEvent(int16_t track, bool overload); #ifdef BOOSTER_INPUT static void railsyncEvent(bool on); #endif static void blockEvent(int16_t block, int16_t loco, bool entering); static bool signalAspectEvent(int16_t address, byte aspect ); // Throttle Info Access functions built by exrail macros static const byte rosterNameCount; static const int16_t HIGHFLASH routeIdList[]; static const int16_t HIGHFLASH automationIdList[]; static const int16_t HIGHFLASH rosterIdList[]; static const FSH * getRouteDescription(int16_t id); static char getRouteType(int16_t id); static const FSH * getTurnoutDescription(int16_t id); static const FSH * getRosterName(int16_t id); static const FSH * getRosterFunctions(int16_t id); static const FSH * getTurntableDescription(int16_t id); static const FSH * getTurntablePositionDescription(int16_t turntableId, uint8_t positionId); static void startNonRecursiveTask(const FSH* reason, int16_t id,int pc, uint16_t loco=0); static bool readSensor(uint16_t sensorId); static bool isSignal(int16_t id,char rag); static SIGNAL_DEFINITION getSignalSlot(int16_t slotno); private: static void ComandFilter(Print * stream, byte & opcode, byte & paramCount, int16_t p[]); static bool parseSlash(Print * stream, byte & paramCount, int16_t p[]) ; static void streamFlags(Print* stream); static bool setFlag(VPIN id,byte onMask, byte OffMask=0); static bool getFlag(VPIN id,byte mask); static int16_t progtrackLocoId; static void doSignal(int16_t id,char rag); static void setTurnoutHiddenState(Turnout * t); #ifndef IO_NO_HAL static void setTurntableHiddenState(Turntable * tto); #endif static LookList* LookListLoader(OPCODE op1, OPCODE op2=OPCODE_ENDEXRAIL,OPCODE op3=OPCODE_ENDEXRAIL); static uint16_t getOperand(int progCounter,byte n); static void killBlinkOnVpin(VPIN pin,uint16_t count=1); static void ifAllFunc(const int16_t * vpinList, int16_t count); static void ifAnyFunc(const int16_t * vpinList, int16_t count); static RMFT2 * loopTask; static RMFT2 * pausingTask; void delayMe(long millisecs); 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); void pause(); void resume(); static bool diag; static bool skipIf; static const HIGHFLASH3 byte RouteCode[]; static const HIGHFLASH SIGNAL_DEFINITION SignalDefinitions[]; static byte flags[MAX_FLAGS]; static Print * LCCSerial; static LookList * routeLookup; static LookList * signalLookup; static LookList * onThrowLookup; static LookList * onCloseLookup; static LookList * onActivateLookup; static LookList * onDeactivateLookup; static LookList * onRedLookup; static LookList * onAmberLookup; static LookList * onGreenLookup; static LookList * onChangeLookup; static LookList * onClockLookup; #ifndef IO_NO_HAL static LookList * onRotateLookup; #endif static LookList * onOverloadLookup; static LookList * onBlockEnterLookup; static LookList * onBlockExitLookup; #ifdef BOOSTER_INPUT static LookList * onRailSyncOnLookup; static LookList * onRailSyncOffLookup; #endif static const int countLCCLookup; static int onLCCLookup[]; static const byte compileFeatures; static void manageRouteState(int16_t id, byte state); static bool ifRouteState(int16_t id, byte state); static void manageRouteCaption(int16_t id, const FSH* caption); static byte * routeStateArray; static const FSH ** routeCaptionArray; static int16_t * stashArray; static int16_t maxStashId; // Local variables - exist for each instance/task RMFT2 *next; // loop chain int progCounter; // Byte offset of next route opcode in ROUTES table unsigned long delayStart; // Used by opcodes that must be recalled before completing unsigned long delayTime; union { unsigned long waitAfter; // Used by OPCODE_AFTER unsigned long timeoutStart; // Used by OPCODE_ATTIMEOUT VPIN blinkPin; // Used by blink tasks }; byte taskId; BlinkState blinkState; // includes AT_TIMEOUT flag. uint16_t loco; bool invert; byte pauseSpeed; int onEventStartPosition; byte stackDepth; int callStack[MAX_STACK_DEPTH]; }; #define GET_OPCODE GETHIGHFLASH(RMFT2::RouteCode,progCounter) #define SKIPOP progCounter+=3 #endif ================================================ FILE: EXRAIL2MacroBase.h ================================================ /* * © 2020-2025 Chris Harlow. All rights reserved. * © 2022-2023 Colin Murdoch * © 2023 Harald Barth * © 2025 Morten Nielsen * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see https://www.gnu.org/licenses/. */ /* This file creates dummy entries for all the EXRAIL macros to allow * the EXRAIL Macro files to be parsed multiple times during compilation. * The actual definitions are created in EXRAILMacros.h according to the * current pass. * * Triple / Comments in this file are intended for the EXRAIL end user and will * be extracted to create documentation. Please maintain formatting. */ #define ACTIVATE(addr,subaddr) ///brief Send DCC Accessory Activate packet (gate on then off) ///param addr DCC short address of accessory ///param subaddr DCC sub address #define ACTIVATEL(linearaddr) ///brief Send DCC Accessory Activate packet (gate on then off) ///param linearaddr DCC linear address of accessory #define AFTER(vpin,timer...) ///brief Wait for sensor activated, then deactivated for given time ///param vpin Virtual Pin number of sensor ///param timer... optional wait in ms, default 500 #define AFTEROVERLOAD(track_id) ///brief Wait for overload to be resolved ///param track_id A..H #define ALIAS(name,value...) ///brief defines a named numeric value. ///param name c++ variable name that can be used throughout the script ///param value... if omitted, a large negative value is created automatically #define AMBER(signal_id) ///brief Sets a signal to amber state ///see ONAMBER #define ANOUT(vpin,value,param1,param2) ///brief Writes to the HAL analog output interface of a device driver. ///param vpin Virtual pin number of device ///param value basic analog value ///param param1 device dependent ///param param2 device dependent #define AT(vpin) ///brief Wait until a sensor becomes active ///param vpin Virtual pin of sensor. Use negative value for sensors that are HIGH when activated #define ASPECT(address,value) ///brief Sends a DCC aspect value to an accessory address. May also change status of a signal defined using this aspect. ///param address Linear DCC address of device ///param value Aspect value (Device dependent) #define ATGTE(vpin,value) ///brief Wait for analog sensor to be greater than given value ///param vpin Analog pin number ///param value integer value to compare against #define ATLT(vpin,value) ///brief Wait for analog sensor value to be less than given value ///param vpin Analog pin number ///param value integer value to compare against #define ATTIMEOUT(vpin,timeout_ms) ///brief Wait for sensor active, with timeout. Use IFTIMEOUT to determine whether the AT was satisfied. ///see IFTIMEOUT ///param vpin Sensor pin number ///param timeout_ms Milliseconds to wait before timeout #define AUTOMATION(sequence_id,description) ///brief Defines starting point of a sequence that will be shown as an Automation by /// the throttles. Automations are started by the throttle handing over a loco id to be driven. ///param sequence_id Unique sequence id value ///param description (Quoted text) will be shown on throttle button #define AUTOSTART ///brief A new task will be created starting from this point at Command Station startup #define BLINK(vpin,onDuty,offDuty) ///brief Starts a blinking process for a vpin (typically a LED). Stop blink with SET or RESET. ///param vpin Pin to blink ///param onDuty Milliseconds with LED ON ///param offDuty Milliseconds with LED off #define BROADCAST(msg) ///brief Send raw message text to all throttles using the DCC-EX protocol ///see WITHROTTLE ///param msg Quoted message #define BUILD_CONSIST(loco_id) ///brief Adds a loco to follow the current loco in a consist ///param loco_id may be negative to indicate loco facing backwards #define BREAK_CONSIST ///brief Breaks up any consist involving the current loco #define CALL(sequence_id) ///brief transfer control to another sequence with expectation to return ///see RETURN ///param sequence_id SEQUENCE to jump processing to, must terminate or RETURN #define CLEAR_STASH(stash_id) ///brief Clears loco value stored in stash ///param stash_id which stash to clear. #define CLEAR_ALL_STASH ///brief Clears all stashed loco values #define CLEAR_ANY_STASH ///brief Clears loco value from all stash entries #define CLOSE(turnout_id) ///brief Close turnout by id ///see THROW #define CONFIGURE_SERVO(vpin,pos1,pos2,profile) ///brief Set up servo movement parameters for non-turnout ///param vpin must refer to a servo capable pin ///param pos1 SET position of servo ///param pos2 RESET position of servo ///param profile Movement profile (Instant, Fast, Medium, Slow, Bounce) #define DCC_SIGNAL(signal_id,addr,subaddr) ///brief Define a DCC accessory signal with short address ///param signal_id Id used for all signal manipulation commands ///param addr DCC address ///param subaddr DCC subaddress #define DCCX_SIGNAL(signal_id,redAspect,amberAspect,greenAspect) ///brief Define advanced DCC accessory signal with aspects ///param signal_id DCC Linear address AND Id used for all signal manipulation commands #define DCC_TURNTABLE(turntable_id,home,description...) ///brief defines a Turntable device ///param homeAngle the angle of the home position, valid angles are 0 - 3600 ///param description... Quoted text description of turntable #define DEACTIVATE(addr,subaddr) ///brief Sends DCC Deactivate packet (gate on, gate off) ///param addr DCC accessory address ///param subaddr DCC accessory subaddress #define DEACTIVATEL(addr) ///brief Sends DCC Deactivate packet (gate on, gate off) ///param addr DCC Linear accessory address #define DELAY(delay_ms) ///brief Waits for given milliseconds delay (This is not blocking) ///param delay_mS Delay time in milliseconds #define DELAYMINS(delay_minutes) ///brief Waits for given minutes delay (This is not blocking) #define DELAYRANDOM(mindelay,maxdelay) ///brief Waits for random delay between min and max milliseconds (This is not blocking) ///param mindelay minimum delay in ms ///param maxdelay maximum delay in ms #define DONE ///brief Stops task loco (if any) and terminates current task #define DRIVE(analogpin) ///brief RESERVED do not use #define ELSE ///brief introduces alternate processing path after any kind of IF ///see IF #define ENDEXRAIL ///brief obsolete.. no longer needed. Does nothing. #define ENDIF ///brief determines end of IF(any type) block. /// IF something ENDIF, or /// IF something ELSE something ENDIF ///see IF #define ENDTASK ///brief same as DONE ///see DONE #define ESTOP ///brief Performs emergency stop on current task loco #define ESTOPALL ///brief Performs emergency stop on all locos #define ESTOP_PAUSE ///brief Emergency stop, and preventing all movement until resumed #define ESTOP_RESUME ///brief Resumes loco speeds after ESTOP_PAUSE #define EXRAIL ///brief obsolete.. no longer needed. Does nothing. #define EXTT_TURNTABLE(id,vpin,home,description...) ///brief Defines the EX‑Turntable turntable/traverser object only, so you will need a separate HAL() statement for an EX‑Turntable device driver. ///param homeAngle the angle of the home position, valid angles are 0 - 3600 ///param quoted description... #define FADE(vpin,value,ms) ///brief Modifies analog value slowly taking a given time ///param vpin Servo virtual pin number ///param value new target value ///param ms time to reach value #define FOFF(func) ///brief Turns off current loco function ///see FON #define FOLLOW(sequence_id) ///brief Task processing follows given route or sequence (Effectively a GoTo) #define FON(func) ///brief Turn on current loco function ///see FOFF #define FORGET ///brief Removes current loco from task and DCC reminders table. #define FREE(token_id) ///brief Frees logical token ///see RESERVE ///param token_id 0..255 #define FREEALL ///brief Frees all logical tokens ///see RESERVE #define FTOGGLE(func) ///brief Toggles function for current loco #define FWD(speed) ///brief Instructs current loco to set DCC speed ///param speed 0..127 (1=ESTOP) #define GREEN(signal_id) ///brief Sets signal to green state #define HAL(haltype,params...) ///brief Defines VPIN mapping for specific hardware drivers ///param haltype driver name, normally device type ///param params... depend on driver. #define HAL_IGNORE_DEFAULTS ///brief System will ignore default HAL device mappings #define IF(vpin) ///brief Checks sensor state, If false jumps to matching nested ELSE or ENDIF ///param vpin VPIN of sensor. Negative VPIN will invert sensor state. #define IF_ALL(vpinList...) ///brief Checks sensor state, If any are false, it jumps to matching nested ELSE or ENDIF ///param vpinlist comma separated list of VPINs of sensors. Negative VPIN will invert sensor state. #define IF_ANY(vpinList...) ///brief Checks sensor state, If all are false jumps to matching nested ELSE or ENDIF ///param vpinlist comma separated list of VPINs of sensors. Negative VPIN will invert sensor state. #define IFAMBER(signal_id) ///brief Checks if signal is in AMBER state. ///see IF #define IFCLOSED(turnout_id) ///brief Checks if given turnout is in close state ///see IF #define IFGREEN(signal_id) ///brief Checks if given signal is in GREEN state ///see IF #define IFGTE(vpin,value) ///brief Checks if analog vpin sensor >= value ///see IF #define IFLOCO(loco_id_list...) ///brief Checks if current task loco is in the list of loco ids. List may be comma separated values ///see IF #define IFLT(vpin,value) ///brief Checks if analog sensor < value ///see IF ///param vpin Analog vpin of sensor #define IFNOT(vpin) ///brief Inverse of IF ///see IF #define IFRANDOM(percent) ///brief randomly satisfied IF at given percent probability ///see IF #define IFRED(signal_id) ///brief Checks if given signal is in RED state ///see IF #define IFSTASH(stash_id) ///brief Checks if given stash entry has a non-zero value ///see IF #define IFSTASHED_HERE(stash_id) ///brief Checks if given stash entry has the current loco ///see IF #define IFTHROWN(turnout_id) ///brief Checks if given turnout is in THROWN state ///see IF #define IFRESERVE(token_id) ///brief Attempts to reserve token and if satisfiled the token remains reserved. ///see IF RESERVE FREE #define IFTIMEOUT ///brief Checks TIMEOUT state after an AT/AFTER request with timeout value. ///see IF AT AFTER #define IFTTPOSITION(turntable_id,position) ///brief Checks if Turntable is in given position ///see IF #define IFRE(vpin,value) ///brief Checks external rotary encoder value ///param vpin of device driver for rotary encoder #define IFBITMAP_ALL(vpin,mask) ///brief Checks if (vpin pseudo-analog value & mask) == mask. ///see IF ///param mask Binary mask applied to vpin value #define IFBITMAP_ANY(vpin,mask) ///brief Checks if vpin pseudo-analog value & mask is non-zero ///see IF ///param mask Binary mask applied to vpin value #define IFROUTE_ACTIVE(sequence_id) ///brief Checks if route is active ///see IF #define IFROUTE_INACTIVE(sequence_id) ///brief Checks if route is inactive ///see IF #define IFROUTE_HIDDEN(sequence_id) ///brief Checks if route is hidden ///see IF #define IFROUTE_DISABLED(sequence_id) ///brief Checks if route is disabled ///see IF #define INVERT_DIRECTION ///brief Marks current task so that FWD and REV commands are inverted. #define JMRI_SENSOR(vpin,count...) ///brief Defines multiple JMRI `` type sensor feedback definitions each with id matching vpin and INPUT_PULLUP ///param vpin first vpin number ///param count... Number of consecutive VPINS for which to create JMRI sensor feedbacks. Default 1. #define JMRI_SENSOR_NOPULLUP(vpin,count...) ///brief Defines multiple JMRI `` type sensor feedback definitions each with id matching vpin ///param vpin first vpin number ///param count... Number of consecutive VPINS for which to create JMRI sensor feedbacks. Default 1. #define JOIN ///brief Switches PROG track to receive MAIN track DCC packets. (Drive on PROG track) #define KILLALL ///brief Terminates all running EXRAIL tasks #define LATCH(vpin) ///brief Make all AT/AFTER/IF see vpin as HIGH without checking hardware ///param vpin Must only be for VPINS 0..255 #define LCC(eventid) ///brief Issue event to LCC #define LCCX(senderid,eventid) ///brief Issue LCC event while impersonating another sender #define LCD(row,msg) ///brief Write message on row of default configured LCD/OLED ///see SCREEN ///param msg Quoted text #define MOMENTUM(accel,decel...) ///brief sets momentum in ms per DCC 127 step for current loco. ///param accel Acceleration momentum ///param decel... Braking momentum. (=Acceleration if not given) #define SCREEN(display,row,msg) ///brief Send message to external display handlers ///param display number, 0=local display, others are handled by external /// displays which may have different display numbers on different devices. ///param msg Quoted text #define LCN(msg) ///brief Reserved for LCN communication. Refer to their documentation. #define MESSAGE(msg) ///brief Send a human readable message to all throttle users ///param msg Quoted text #define MOVETT(turntable_id,steps,activity) ///brief Move Turntable to specific position ///see ROTATE ///param steps position to move to ///param activity see ROTATE #define NEOPIXEL(vpin,r,g,b,count...) ///brief Set a NEOPIXEL vpin to a given red/green/blue colour ///param vpin VPIN of a pixel ///param r red component 0-255 ///param g green component 0-255 ///param b blue component 0-255 ///param count... Number of consecutive pixels to set, Default 1. #define NEOPIXEL_SIGNAL(vpin,redcolour,ambercolour,greencolour) ///brief Define a signal that uses a single multi colour pixel ///see NEORGB ///param vpin unique signal_id ///param redcolour RGB colour use NEORGB(red,green,blue) to create values. #define ACON(eventid) ///brief Send MERG CBUS ACON to Adapter #define ACOF(eventid) ///brief Send MERG CBUS ACOF to Adapter #define ONACON(eventid) ///brief Start task here when ACON for event received from MERG CBUS #define ONACOF(eventid) ///brief Start task here when ACOF for event received from MERG CBUS #define ONACTIVATE(addr,subaddr) ///brief Start task here when DCC Activate sent for short address #define ONACTIVATEL(linear) ///brief Start task here when DCC Activate sent for linear address #define ONAMBER(signal_id) ///brief Start task here when signal set to AMBER state #define ONBLOCKENTER(block_id) ///brief Start task here when a loco enters a railcom block ///param block_id vpin associated to block by HAL(I2CRailcom..) #define ONBLOCKEXIT(block_id) ///brief Start task here when a loco leaves a railcom block ///param block_id vpin associated to block by HAL(I2CRailcom..) #define ONTIME(minute_in_day) ///brief Start task here when fastclock matches ///param minute_in_day (0..1439) #define ONCLOCKTIME(hours,mins) ///brief Start task here when fastclock matches time #define ONCLOCKMINS(mins) ///brief Start task here hourly when fastclock minutes matches #define ONOVERLOAD(track_id) ///brief Start task here when given track goes into overload ///param track_id A..H #define ONRAILSYNCON ///brief Start task here when the railsync (booster) input port get a valid DCC signal #define ONRAILSYNCOFF ///brief Start task here when the railsync (booster) input port does not get a valid DCC signal any more #define ONDEACTIVATE(addr,subaddr) ///brief Start task here when DCC deactivate packet sent #define ONDEACTIVATEL(linear) ///brief Start task here when DCC deactivate sent to linear address #define ONCLOSE(turnout_id) ///brief Start task here when turnout closed #define ONLCC(sender,event) ///brief Start task here when LCC event arrives from sender #define ONGREEN(signal_id) ///brief Start task here when signal set to GREEN state #define ONRED(signal_id) ///brief Start task here when signal set to RED state #define ONROTATE(turntable_id) ///brief Start task here when turntable is rotated #define ONTHROW(turnout_id) ///brief Start task here when turnout is Thrown #define ONCHANGE(vpin) ///brief Rotary encoder change starts task here (This is obscurely different from ONSENSOR which will be merged in a later release.) #define ONSENSOR(vpin) ///brief Start task here when sensor changes state (debounced) #define ONBITMAP(vpin) ///brief Start task here when bitmap sensor changes state (debounced) #define ONBUTTON(vpin) ///brief Start task here when sensor changes HIGH to LOW. #define PAUSE ///brief Pauses all EXRAIL tasks except the current one. /// Other tasks ESTOP their locos until RESUME issued #define PIN_TURNOUT(id,vpin,description...) ///brief Defines a turnout which operates on a single pin ///param description... Quoted text (shown to throttles) or HIDDEN #define PRINT(msg) ///brief prints diagnostic message on USB serial ///param msg Quoted text #define PARSE(msg) ///brief Executes `<>` command as if entered from serial ///param msg Quoted text, preferably including `<>` #define PICKUP_STASH(stash_id) ///see STASH ///brief Loads stashed value into current task loco ///param stash_id position in stash where a loco id was previously saved. #define PLAY_EQ(vpin,eqname) ///brief Sets EQ setting on DFPlayer module ///param eqname One of: NORMAL,POP,ROCK,JAZZ,CLASSIC,BASS #define PLAY_FOLDER(vpin,folder) ///brief Sets DFPlayer folder to use for tracks ///param folder number #define PLAY_PAUSE(vpin) ///brief Pauses sound play ///see PLAY_RESUME #define PLAY_REPEAT(vpin,track,volume...) ///brief Plays a track on a DFPlayer module on repoeat ///param track number ///param volume... optional volume 0-30 or use default set below #define PLAY_RESET(vpin) ///brief Resets DFPlayer #define PLAY_RESUME(vpin) ///brief Resumes playing sound ///see PLAY_PAUSE #define PLAY_STOP(vpin) ///brief Stops DFPlayer #define PLAY_TRACK(vpin,track,volume...) ///brief Plays a track on a DFPlayer module ///param track number ///param volume... optional volume 0-30 or use default set below #define PLAY_VOLUME(vpin,volume) ///brief Sets default volume on a DFPlayer module ///param volume... volume 0-30 #define POM(cv,value) ///brief Write value to cv on current tasks loco (Program on Main) #define POWEROFF ///brief Powers off all tracks #define POWERON ///brief Powers ON all tracks #define RANDOM_CALL(sequence_id...) ///brief CALL to another sequence randomly chosen from list ///see CALL ///param sequence_id.. list of SEQUENCE that may be called, each must terminate or RETURN #define RANDOM_FOLLOW(sequence_id...) ///brief jump to another sequence randomly chosen from list ///see FOLLOW ///param sequence_id.. list of SEQUENCE that may be followed #define READ_LOCO ///brief Reads loco Id from prog track and sets currenmt task loco id. #define RED(signal_id) ///brief sets signal to RED state #define RESERVE(token_id) ///brief Waits for token for block. If not available immediately, current task loco is stopped. #define RESET(vpin,count...) ///brief Sets output pin LOW ///see SET ///param count... Number of consecutive pins, default 1 #define RESTORE_SPEED ///brief Resumes locos saved speed ///see SAVE_SPEED #define RESUME ///brief Resumes PAUSEd tasks ///see PAUSE #define RETURN ///brief Returns to CALL ///see CALL #define REV(speed) ///brief Issues DCC speed packet for current loco in reverse. ///see FWD ///param speed (0..127, 1=ESTOP) #define ROTATE(turntable_id,position,activity) ///brief Rotates an EX-Turntable to a given position ///param activity .. One of: /// - **Turn**: Rotate turntable, maintain phase /// - **Turn_PInvert**: Rotate turntable, invert phase /// - **Home**: Initiate homing /// - **Calibrate**: Initiate calibration sequence /// - **LED_On**: Turn LED on /// - **LED_Slow**: Set LED to a slow blink /// - **LED_Fast**: Set LED to a fast blink /// - **LED_Off**: Turn LED off /// - **Acc_On**: Turn accessory pin on /// - **Acc_Off**: Turn accessory pin off #define ROTATE_DCC(turntable_id,position_id) ///brief Rotates turntable to a given position using DCC commands #define ROSTER(cab,name,funcmap...) ///brief Describes a loco roster entry visible to throttles ///param cab loco DCC address or 0 for default entry ///param name Quoted text ///param funcmap... Quoted text, optional list of function names separated by / character with momentary function names prefixed with an *. #define ROUTE(sequence_id,description) ///brief Defines starting point of a sequence that will appear as a route on throttle buttons. ///param description Quoted text, throttle button caption. #define ROUTE_ACTIVE(sequence_id) ///brief Tells throttle to display the route button as active ///param sequence_id of ROUTE/AUTOMATION #define ROUTE_INACTIVE(sequence_id) ///brief Tells throttle to display the route button as inactive ///param sequence_id of ROUTE/AUTOMATION #define ROUTE_HIDDEN(sequence_id) ///brief Tells throttle to hide the route button ///param sequence_id of ROUTE/AUTOMATION #define ROUTE_DISABLED(sequence_id) ///brief Tells throttle to display the route button as disabled ///param sequence_id of ROUTE/AUTOMATION #define ROUTE_CAPTION(sequence_id,caption) ///brief Tells throttle to change thr route button caption ///param sequence_id of ROUTE/AUTOMATION #define SAVE_SPEED ///brief Saves loco speed for later restore ///see RESTORE_SPEED #define SENDLOCO(cab,sequence_id) ///brief Start a new task to drive the loco ///param cab loco to be driven ///param route sequence_id of route, automation or sequence to drive #define SEQUENCE(sequence_id) ///brief Provides a unique label that can be used to call, follow or start. ///see CALL ///see FOLLOW ///see START #define SERIAL(msg) ///brief Write direct to Serial output ///param msg Quoted text #define SERIAL1(msg) ///brief Write direct to Serial1 output ///param msg Quoted text #define SERIAL2(msg) ///brief Write direct to Serial2 output ///param msg Quoted text #define SERIAL3(msg) ///brief Write direct to Serial3 output ///param msg Quoted text #define SERIAL4(msg) ///brief Write direct to Serial4 output ///param msg Quoted text #define SERIAL5(msg) ///brief Write direct to Serial5 output ///param msg Quoted text #define SERIAL6(msg) ///brief Write direct to Serial6 output ///param msg Quoted text #define SERVO(vpin,position,profile) ///brief Move servo to given position ///param vpin of servo ///param position servo position (values are hardware dependent) ///param profile movement profile (Instant, Fast, Medium, Slow, Bounce) #define SERVO2(vpin,position,duration) ///brief Move servo to given position taking time ///param vpin of servo ///param position servo position (values are hardware dependent) ///param duration mS #define SERVO_SIGNAL(vpin,redpos,amberpos,greenpos) ///brief Dedfine a servo based signal with 3 servo positions ///param vpin of servo, acts as signal_id ///param redpos servo position (values are hardware dependent) ///param amberpos servo position (values are hardware dependent) ///param greenpos servo position (values are hardware dependent) #define SERVO_TURNOUT(turnout_id,vpin,activeAngle,inactiveAngle,profile,description...) ///brief Define a servo driven turnout ///param turnout_id used by THROW/CLOSE ///param vpin for servo ///param activeAngle servo position (values are hardware dependent) ///param inactiveAngle servo position (values are hardware dependent) ///param profile movement profile (Instant, Fast, Medium, Slow, Bounce) ///param description... Quoted text shown to throttles or HIDDEN keyword to hide turnout button #define SET(vpin,count...) ///brief Set pin HIGH ///see RESET ///param count... Number of sequential vpins to set. Default 1. #define SET_TRACK(track,mode) ///brief Set output track type ///param track A..H ///param mode NONE, MAIN, PROG, DC, EXT, BOOST, BOOST_INV, BOOST_AUTO, MAIN_INV, MAIN_AUTO, DC_INV, DCX #define SET_POWER(track,onoff) ///brief Set track power mode ///param track A..H ///param onoff ON or OFF #define SETLOCO(loco) ///brief Sets the loco being handled by the current task #define SETFREQ(freq) ///brief Sets the DC track PWM frequency ///param freq Frequency is default 0, or 1..3 #define SIGNAL(redpin,amberpin,greenpin) ///brief Define a Signal with LOW=on leds ///see SIGNALH ///param redpin vpin for RED state, also acts as signal_id #define SIGNALH(redpin,amberpin,greenpin) ///brief define a signal with HIGH=ON leds ///param redpin vpin for RED state, also acts as signal_id #define SPEED(speed) ///brief Changes current tasks loco speed without changing direction ///param speed 0..127 (1=ESTOP) #define SPEEDUP(speedstep) ///brief Increases current tasks loco speed by given amount ///param speedstep 0..127 #define SLOWDOWN(speedstep) ///brief Decreases current tasks loco speed by given amount ///param speedstep 0..127 #define SPEED_REL(percent) ///brief Sets current tasks loco speed to percentage of current speed ///param percent 1..500 #define START(sequence_id) ///brief Starts a new task at the given route/animation/sequence #define START_SHARED(sequence_id) ///brief Starts a new task at the given route/animation/sequence and share current loco with it #define START_SEND(sequence_id) ///brief Starts a new task at the given route/animation/sequence and send current loco to it. Remove loco from current task. #define STASH(stash_id) ///brief saves current task's loco id in the stash array ///param stash_id position in stash array to save loco id #define STEALTH(code...) ///brief Allows for embedding raw C++ code in context of current task. ///param code... c++ code to be executed. This requires intimate understanding of the product architecture. #define STEALTH_GLOBAL(code...) ///brief Allows for embedding raw c++ code out of context. ///param code... c++ code to be defined. This requires intimate understanding of the product architecture. #define STOP ///brief Same as SPEED(0) #define THROW(turnout_id) ///brief Throws given turnout ///see CLOSE #define TOGGLE_TURNOUT(turnout_id) ///brief Toggles given turnout #define TT_ADDPOSITION(turntable_id,position_id,value,angle,description...) ///brief Defines a turntable track position ///param position_id each position is given an id ///param address DCC accessory address ///param angle Used only for throttles that may draw a visual representation of the turntable ///param description... quoted text or HIDDEN #define TURNOUT(turnout_id,addr,subaddr,description...) ///brief Defines a DCC accessory turnout with legacy address ///param turnout_id to be used in THROW/CLOSE etc ///param addr DCC accessory address ///param subaddr DCC accessory subaddress ///param description... Quoted text or HIDDEN, appears on throttle buttons #define TURNOUTL(turnout_id,addr,description...) ///brief Defines a DCC accessory turnout with linear address ///see TURNOUT ///param turnout_id to be used in THROW/CLOSE etc ///param addr DCC accessory linear address ///param description... Quoted text or HIDDEN, appears on throttle buttons #define UNJOIN ///brief Disconnects PROG track from MAIN ///see JOIN #define UNLATCH(vpin) ///brief removes latched on flag ///see LATCH ///param vpin (limited to 0..255) #define VIRTUAL_SIGNAL(signal_id) ///brief Defines a virtual (no hardware) signal, use ONhandlers to simulate hardware ///see SIGNAL ONRED ONAMBER ONGREEN #define VIRTUAL_TURNOUT(id,description...) ///brief Defines a virtual (no hardware) turnout, use ONhandlers to simulate hardware ///see TURNOUT ONCLOSE ONTHROW ///param description... quoted text or HIDDEN #define BITMAP_AND(vpin1,mask) ///brief Performs a bitwise AND operation on the given vpin analog value and mask. ///param mask Binary mask to be ANDed with vpin1 value #define BITMAP_INC(vpin) ///brief Increments pseudo analog value by 1 #define BITMAP_DEC(vpin) ///brief Decrements pseudo analog value by 1 (to zero) #define BITMAP_OR(vpin1,mask) ///brief Performs a bitwise OR operation on the given vpin analog value and mask. ///param mask Binary mask to be ORed with vpin1 value #define BITMAP_SET(vpin1,value) ///brief Sets the given vpin analog value ///param value Value to be set #define BITMAP_XOR(vpin1,mask) ///brief Performs a bitwise XOR operation on the given vpin analog value and mask. ///param mask Binary mask to be XORed with vpin1 value #define WAITFOR(pin) ///brief Waits for completion of servo movement #ifndef IO_NO_HAL #define WAITFORTT(turntable_id) ///brief waits for completion of turntable movement #endif #define WAIT_WHILE_RED(signal_id) ///brief Keeps loco at speed 0 while signal is RED #define WITHROTTLE(msg) ///brief Broadcasts a string in Withrottle protocol format to all throttles using this protocol. ///param msg quoted string #define XFOFF(cab,func) ///brief Turns function off for given loco ///param func function number #define XFON(cab,func) ///brief Turns function ON for given loco #define XFTOGGLE(cab,func) ///brief Toggles function state for given loco #define XFWD(cab,speed) ///brief Sends DCC speed to loco in forward direction ///param speed (0..127, 1=ESTOP) #define XREV(cab,speed) ///brief Sends DCC speed to loco in reverse direction ///param speed (0..127, 1=ESTOP) #define XPOM(cab,cv,value) ///brief updates a cv on a loco using Program on Main. ///param cab loco id ///param cv to be updated ///param value to be written to cv #define XRESTORE_SPEED(cab) ///brief Resumes locos saved speed ///param cab loco id ///see XSAVE_SPEED #define XSAVE_SPEED(cab) ///brief Saves loco speed for later restore ///param cab loco id ///see XRESTORE_SPEED #define ZTEST(command,testcode...) ///brief Developer Unit testing. Do not use. #define ZTEST2(command,reply) ///brief Developer Unit testing. Do not use. #define ZTEST3(command,reply,testcode...) ///brief Developer Unit testing. Do not use. ================================================ FILE: EXRAIL2MacroReset.h ================================================ /* * © 2020-2025 Chris Harlow. All rights reserved. * © 2022-2023 Colin Murdoch * © 2023 Harald Barth * © 2025 Morten Nielsen * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see https://www.gnu.org/licenses/. */ // This file cleans and resets the EXRAIL Macros. // It is used between passes to reduce complexity in EXRAILMacros.h // DO NOT add an include guard to this file. // Undefine all RMFT macros #undef ACTIVATE #undef ACTIVATEL #undef AFTER #undef AFTEROVERLOAD #undef ALIAS #undef AMBER #undef ANOUT #undef ASPECT #undef AT #undef ATGTE #undef ATLT #undef ATTIMEOUT #undef AUTOMATION #undef AUTOSTART #undef BLINK #undef BUILD_CONSIST #undef BREAK_CONSIST #undef BROADCAST #undef CALL #undef CLEAR_STASH #undef CLEAR_ALL_STASH #undef CLEAR_ANY_STASH #undef CLOSE #undef CONFIGURE_SERVO #undef DCC_SIGNAL #undef DCCX_SIGNAL #undef DCC_TURNTABLE #undef DEACTIVATE #undef DEACTIVATEL #undef DELAY #undef DELAYMINS #undef DELAYRANDOM #undef DONE #undef DRIVE #undef ELSE #undef ENDEXRAIL #undef ENDIF #undef ENDTASK #undef ESTOP #undef ESTOPALL #undef ESTOP_PAUSE #undef ESTOP_RESUME #undef EXRAIL #undef EXTT_TURNTABLE #undef FADE #undef FOFF #undef FOLLOW #undef FON #undef FORGET #undef FTOGGLE #undef FREE #undef FREEALL #undef FWD #undef GREEN #undef HAL #undef HAL_IGNORE_DEFAULTS #undef IF #undef IF_ALL #undef IF_ANY #undef IFAMBER #undef IFCLOSED #undef IFGREEN #undef IFGTE #undef IFLOCO #undef IFLT #undef IFNOT #undef IFRANDOM #undef IFRED #undef IFRESERVE #undef IFSTASH #undef IFSTASHED_HERE #undef IFTHROWN #undef IFTIMEOUT #undef IFTTPOSITION #undef IFRE #undef IFROUTE_ACTIVE #undef IFROUTE_INACTIVE #undef IFROUTE_HIDDEN #undef IFROUTE_DISABLED #undef IFBITMAP_ALL #undef IFBITMAP_ANY #undef INVERT_DIRECTION #undef JMRI_SENSOR #undef JMRI_SENSOR_NOPULLUP #undef JOIN #undef KILLALL #undef LATCH #undef LCD #undef SCREEN #undef LCC #undef LCCX #undef LCN #undef MOMENTUM #undef MOVETT #undef NEOPIXEL #undef NEOPIXEL_OFF #undef NEOPIXEL_SIGNAL #undef ACON #undef ACOF #undef ONACON #undef ONACOF #undef MESSAGE #undef ONACTIVATE #undef ONACTIVATEL #undef ONAMBER #undef ONBLOCKENTER #undef ONBLOCKEXIT #undef ONDEACTIVATE #undef ONDEACTIVATEL #undef ONCLOSE #undef ONLCC #undef ONTIME #undef ONCLOCKTIME #undef ONCLOCKMINS #undef ONOVERLOAD #undef ONRAILSYNCON #undef ONRAILSYNCOFF #undef ONGREEN #undef ONRED #undef ONROTATE #undef ONBUTTON #undef ONSENSOR #undef ONTHROW #undef ONBITMAP #undef ONCHANGE #undef PARSE #undef PAUSE #undef PICKUP_STASH #undef PIN_TURNOUT #undef PLAY_EQ #undef PLAY_FOLDER #undef PLAY_PAUSE #undef PLAY_REPEAT #undef PLAY_RESET #undef PLAY_RESUME #undef PLAY_STOP #undef PLAY_TRACK #undef PLAY_VOLUME #undef PRINT #undef POM #undef POWEROFF #undef POWERON #undef RANDOM_CALL #undef RANDOM_FOLLOW #undef READ_LOCO #undef RED #undef RESERVE #undef RESET #undef RESTORE_SPEED #undef RESUME #undef RETURN #undef REV #undef ROSTER #undef ROTATE #undef ROTATE_DCC #undef ROUTE #undef ROUTE_ACTIVE #undef ROUTE_INACTIVE #undef ROUTE_HIDDEN #undef ROUTE_DISABLED #undef ROUTE_CAPTION #undef SAVE_SPEED #undef SENDLOCO #undef SEQUENCE #undef SERIAL #undef SERIAL1 #undef SERIAL2 #undef SERIAL3 #undef SERIAL4 #undef SERIAL5 #undef SERIAL6 #undef SERVO #undef SERVO2 #undef SERVO_TURNOUT #undef SERVO_SIGNAL #undef SET #undef SET_TRACK #undef SET_POWER #undef SETLOCO #undef SETFREQ #undef SIGNAL #undef SIGNALH #undef SPEED #undef SPEEDUP #undef SPEED_REL #undef SLOWDOWN #undef START #undef START_SHARED #undef START_SEND #undef STASH #undef STEALTH #undef STEALTH_GLOBAL #undef STOP #undef THROW #undef TOGGLE_TURNOUT #undef TT_ADDPOSITION #undef TURNOUT #undef TURNOUTL #undef UNJOIN #undef UNLATCH #undef VIRTUAL_SIGNAL #undef VIRTUAL_TURNOUT #undef WAITFOR #undef WAIT_WHILE_RED #ifndef IO_NO_HAL #undef BITMAP_AND #undef BITMAP_OR #undef BITMAP_SET #undef BITMAP_XOR #undef BITMAP_INC #undef BITMAP_DEC #undef WAITFORTT #endif #undef WITHROTTLE #undef XFOFF #undef XFON #undef XFTOGGLE #undef XPOM #undef XREV #undef XFWD #undef XSAVE_SPEED #undef XRESTORE_SPEED #undef ZTEST #undef ZTEST2 #undef ZTEST3 #ifndef RMFT2_UNDEF_ONLY #include "EXRAIL2MacroBase.h" #endif ================================================ FILE: EXRAIL2Parser.cpp ================================================ /* * © 2021 Neil McKechnie * © 2021-2023 Harald Barth * © 2020-2025 Chris Harlow * © 2022-2023 Colin Murdoch * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ // THIS file is an extension of the RMFT2 class // normally found in EXRAIL2.cpp #include #include "defines.h" #include "EXRAIL2.h" #include "DCC.h" #include "KeywordHasher.h" // This filter intercepts <> commands to do the following: // - Implement RMFT specific commands/diagnostics // - Reject/modify JMRI commands that would interfere with RMFT processing void RMFT2::ComandFilter(Print * stream, byte & opcode, byte & paramCount, int16_t p[]) { (void)stream; // avoid compiler warning if we don't access this parameter switch(opcode) { case 'D': if (p[0]=="EXRAIL"_hk) { // diag = paramCount==2 && (p[1]=="ON"_hk || p[1]==1); opcode=0; } break; case '/': // New EXRAIL command if (parseSlash(stream,paramCount,p)) opcode=0; break; case 'A': // if (paramCount!=2) break; // Ask exrail if this is just changing the aspect on a // predefined DCCX_SIGNAL. Because this will handle all // the IFRED and ONRED type issues at the same time. if (signalAspectEvent(p[0],p[1])) opcode=0; // all done break; case 'L': // This entire code block is compiled out if LLC macros not used if (!(compileFeatures & FEATURE_LCC)) return; static int lccProgCounter=0; static int lccEventIndex=0; if (paramCount==0) { // LCC adapter introducing self LCCSerial=stream; // now we know where to send events we raise opcode=0; // flag command as intercepted // loop through all possible sent/waited events for (int progCounter=lccProgCounter;; SKIPOP) { byte exrailOpcode=GET_OPCODE; switch (exrailOpcode) { case OPCODE_ENDEXRAIL: stream->print(F("\n")); // ready to roll lccProgCounter=0; // allow a second pass lccEventIndex=0; return; case OPCODE_LCC: StringFormatter::send(stream,F("\n"),getOperand(progCounter,0)); SKIPOP; lccProgCounter=progCounter; return; case OPCODE_LCCX: // long form LCC StringFormatter::send(stream,F("\n"), getOperand(progCounter,1), getOperand(progCounter,2), getOperand(progCounter,3), getOperand(progCounter,0) ); SKIPOP;SKIPOP;SKIPOP;SKIPOP; lccProgCounter=progCounter; return; case OPCODE_ACON: // CBUS ACON case OPCODE_ACOF: // CBUS ACOF StringFormatter::send(stream,F("\n"), exrailOpcode==OPCODE_ACOF?'1':'0', getOperand(progCounter,0),getOperand(progCounter,1)); SKIPOP;SKIPOP; lccProgCounter=progCounter; return; // we stream the hex events we wish to listen to // and at the same time build the event index looku. case OPCODE_ONLCC: StringFormatter::send(stream,F("\n"), lccEventIndex, getOperand(progCounter,1), getOperand(progCounter,2), getOperand(progCounter,3), getOperand(progCounter,0) ); SKIPOP;SKIPOP;SKIPOP;SKIPOP; // start on handler at next onLCCLookup[lccEventIndex]=progCounter; lccEventIndex++; lccProgCounter=progCounter; return; case OPCODE_ONACON: case OPCODE_ONACOF: StringFormatter::send(stream,F("\n"), lccEventIndex, exrailOpcode==OPCODE_ONACOF?'1':'0', getOperand(progCounter,0),getOperand(progCounter,1) ); SKIPOP;SKIPOP; // start on handler at next onLCCLookup[lccEventIndex]=progCounter; lccEventIndex++; lccProgCounter=progCounter; return; default: break; } } } if (paramCount==1) { // LCC event arrived from adapter int16_t eventid=p[0]; bool reject = eventid<0 || eventid>=countLCCLookup; if (!reject) { startNonRecursiveTask(F("LCC"),eventid,onLCCLookup[eventid]); opcode=0; } } break; case 'J': // throttle info commands if (paramCount<1) return; switch(p[0]) { case "A"_hk: // returns automations/routes if (paramCount==1) {// StringFormatter::send(stream, F("stream(stream); StringFormatter::send(stream, F(">\n")); opcode=0; return; } if (paramCount==2) { // int16_t id=p[1]; StringFormatter::send(stream,F("\n"), id, getRouteType(id), getRouteDescription(id)); if (compileFeatures & FEATURE_ROUTESTATE) { // Send any non-default button states or captions int16_t statePos=routeLookup->findPosition(id); if (statePos>=0) { if (routeStateArray[statePos]) StringFormatter::send(stream,F("\n"), id, routeStateArray[statePos]); if (routeCaptionArray[statePos]) StringFormatter::send(stream,F("\n"), id,routeCaptionArray[statePos]); } } opcode=0; return; } break; case 'K': // Block enter case 'k': // Block exit if (paramCount!=2) break; blockEvent(p[0],p[1],opcode=='K'); opcode=0; break; default: // other commands pass through break; } } } bool RMFT2::parseSlash(Print * stream, byte & paramCount, int16_t p[]) { if (paramCount==0) { // STATUS StringFormatter::send(stream, F("<* EXRAIL STATUS")); RMFT2 * task=loopTask; while(task) { if ((compileFeatures & FEATURE_BLINK) && (task->blinkState==blink_high || task->blinkState==blink_low)) { StringFormatter::send(stream,F("\nID=%d,PC=%d,BLINK=%d"), (int)(task->taskId),task->progCounter,task->blinkPin ); } else { StringFormatter::send(stream,F("\nID=%d,PC=%d,LOCO=%d %c"), (int)(task->taskId),task->progCounter,task->loco, task->invert?'I':' ' ); auto progCounter=task->progCounter; // name to satisfy macros below auto operand=task->getOperand(progCounter,0); switch(GET_OPCODE) { case OPCODE_RESERVE: StringFormatter::send(stream,F(" WAIT RESERVE %d"),operand); break; case OPCODE_AT: case OPCODE_ATTIMEOUT2: case OPCODE_AFTER: case OPCODE_ATGTE: case OPCODE_ATLT: StringFormatter::send(stream,F(" WAIT AT/AFTER %d"),(int16_t)operand); break; case OPCODE_WAIT_WHILE_RED: StringFormatter::send(stream,F(" WAIT WHILE RED %d"),operand); break; case OPCODE_DELAY: case OPCODE_DELAYMINS: case OPCODE_DELAYMS: case OPCODE_RANDWAIT: StringFormatter::send(stream,F(" WAIT DELAY")); break; default: break; } } task=task->next; if (task==loopTask) break; } // Now stream the flags for (int id=0;id\n")); return true; } switch (p[0]) { case "PAUSE"_hk: // if (paramCount!=1) return false; { // pause all tasks RMFT2 * task=loopTask; while(task) { task->pause(); task=task->next; if (task==loopTask) break; } } DCC::estopAll(); // pause all locos on the track pausingTask=(RMFT2 *)1; // Impossible task address return true; case "RESUME"_hk: // if (paramCount!=1) return false; pausingTask=NULL; { // resume all tasks RMFT2 * task=loopTask; while(task) { task->resume(); task=task->next; if (task==loopTask) break; } } return true; case "FREEALL"_hk: // force free all if (paramCount!=1) return false; for (int i=0;i if (paramCount<2 || paramCount>3) return false; { int route=(paramCount==2) ? p[1] : p[2]; uint16_t cab=(paramCount==2)? 0 : p[1]; int pc=routeLookup->find(route); if (pc<0) return false; new RMFT2(pc,cab); } return true; default: break; } // check KILL ALL here, otherwise the next validation confuses ALL with a flag if (p[0]=="KILL"_hk && p[1]=="ALL"_hk) { while (loopTask) loopTask->kill(F("KILL ALL")); // destructor changes loopTask return true; } // all other / commands take 1 parameter if (paramCount!=2 ) return false; switch (p[0]) { case "KILL"_hk: // Kill taskid|ALL { if ( p[1]<0 || p[1]>=MAX_FLAGS) return false; RMFT2 * task=loopTask; while(task) { if (task->taskId==p[1]) { task->kill(F("KILL")); return true; } task=task->next; if (task==loopTask) break; } } return false; case "RESERVE"_hk: // force reserve a section return setFlag(p[1],SECTION_FLAG); case "FREE"_hk: // force free a section return setFlag(p[1],0,SECTION_FLAG); case "LATCH"_hk: return setFlag(p[1], LATCH_FLAG); case "UNLATCH"_hk: return setFlag(p[1], 0, LATCH_FLAG); case "RED"_hk: doSignal(p[1],SIGNAL_RED); return true; case "AMBER"_hk: doSignal(p[1],SIGNAL_AMBER); return true; case "GREEN"_hk: doSignal(p[1],SIGNAL_GREEN); return true; default: return false; } } ================================================ FILE: EXRAILAsserts.h ================================================ /* * © 2025 Paul M. Antoine * © 2020-2025 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 . */ // This file checks the myAutomation for errors by generating a list of compile time asserts. // Assert Pass 1 Collect sequence numbers. #include "EXRAIL2MacroReset.h" #undef AUTOMATION #define AUTOMATION(id, description) id, #undef ROUTE #define ROUTE(id, description) id, #undef SEQUENCE #define SEQUENCE(id) id, constexpr int16_t compileTimeSequenceList[]={ #include "myAutomation.h" 0 }; constexpr int16_t stuffSize=sizeof(compileTimeSequenceList)/sizeof(int16_t) - 1; // Compile time function to check for sequence number duplication constexpr int16_t seqCount(const int16_t value, const int16_t pos=0, const int16_t count=0 ) { return pos>=stuffSize? count : seqCount(value,pos+1,count+((compileTimeSequenceList[pos]==value)?1:0)); } // Build a compile time blacklist of pin numbers. // Includes those defined in defaults.h for the cpu (PIN_BLACKLIST) // and cheats in the motor shield pins from config.h (MOTOR_SHIELD_TYPE) // for reference the MotorDriver constructor 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); // create capture macros to reinterpret MOTOR_SHIELD_TYPE from configuration #define new #define MotorDriver(power_pin,signal_pin,signal_pin2, \ brake_pin,current_pin,senseFactor,tripMilliamps,faultPin) \ abs(power_pin),abs(signal_pin),abs(signal_pin2),abs(brake_pin),abs(current_pin),abs(faultPin) #ifndef PIN_BLACKLIST #define PIN_BLACKLIST UNUSED_PIN #endif #define MDFURKLE(stuff) MDFURKLE2(stuff) #define MDFURKLE2(description,...) REMOVE_TRAILING_COMMA(__VA_ARGS__) #define REMOVE_TRAILING_COMMA(...) __VA_ARGS__ constexpr int16_t compileTimePinBlackList[]={ PIN_BLACKLIST, MDFURKLE(MOTOR_SHIELD_TYPE) }; constexpr int16_t pbSize=sizeof(compileTimePinBlackList)/sizeof(int16_t); // remove capture macros #undef new #undef MotorDriver // Compile time function to check for dangerous pins. constexpr bool unsafePin(const int16_t value, const int16_t pos=0 ) { return pos>=pbSize? false : compileTimePinBlackList[pos]==value || unsafePin(value,pos+1); } //pass 2 apply static asserts: // check call and follows etc for existing sequence numbers // check sequence numbers for duplicates // check range on LATCH/UNLATCH // check range on RESERVE/FREE // check range on SPEED/FWD/REV // check range on SET/RESET (pins that are not safe to use in EXRAIL) // // This pass generates no runtime data or code #include "EXRAIL2MacroReset.h" #undef ASPECT #define ASPECT(address,value) static_assert(address <=2044, "invalid Address"); \ static_assert(address>=-3, "Invalid value"); // check references to sequences/routes/automations #undef CALL #define CALL(id) static_assert(seqCount(id)>0,"Sequence not found"); #undef FOLLOW #define FOLLOW(id) static_assert(seqCount(id)>0,"Sequence not found"); // random call and follow will generate CALL macros here which // will check for invalid sequences #undef RANDOM_CALL #define RANDOM_CALL(...) \ ZCRIP(FOR_EACH_NARG(__VA_ARGS__))(__VA_ARGS__) #undef RANDOM_FOLLOW #define RANDOM_FOLLOW(...) \ ZCRIP(FOR_EACH_NARG(__VA_ARGS__))(__VA_ARGS__) #undef START #define START(id) static_assert(seqCount(id)>0,"Sequence not found"); #undef START_SHARED #define START_SHARED(id) static_assert(seqCount(id)>0,"Sequence not found"); #undef START_SEND #define START_SEND(id) static_assert(seqCount(id)>0,"Sequence not found"); #undef SENDLOCO #define SENDLOCO(cab,id) static_assert(seqCount(id)>0,"Sequence not found"); #undef ROUTE_ACTIVE #define ROUTE_ACTIVE(id) static_assert(seqCount(id)>0,"Route not found"); #undef ROUTE_INACTIVE #define ROUTE_INACTIVE(id) static_assert(seqCount(id)>0,"Route not found"); #undef ROUTE_HIDDEN #define ROUTE_HIDDEN(id) static_assert(seqCount(id)>0,"Route not found"); #undef ROUTE_DISABLED #define ROUTE_DISABLED(id) static_assert(seqCount(id)>0,"Route not found"); #undef ROUTE_CAPTION #define ROUTE_CAPTION(id,caption) static_assert(seqCount(id)>0,"Route not found"); #undef LATCH #define LATCH(id) static_assert(id>=0 && id=0 && id=0 && id=0 && id=0 && id=0 && speed<128,"\n\nUSER ERROR: Speed out of valid range 0-127\n"); #undef FWD #define FWD(speed) static_assert(speed>=0 && speed<128,"\n\nUSER ERROR: Speed out of valid range 0-127\n"); #undef REV #define REV(speed) static_assert(speed>=0 && speed<128,"\n\nUSER ERROR: Speed out of valid range 0-127\n"); #undef SPEEDUP #define SPEEDUP(speedstep) static_assert(speedstep>=0 && speedstep<128,"\n\nUSER ERROR: Speed step out of valid range 0-127\n"); #undef SPEED_REL #define SPEED_REL(percent) static_assert(percent>0 && percent<=500,"\n\nUSER ERROR: Speed out of valid range 1-500 %\n"); #undef SLOWDOWN #define SLOWDOWN(speedstep) static_assert(speedstep>=0 && speedstep<128,"\n\nUSER ERROR: Speed step out of valid range 0-127\n"); // check duplicate sequences #undef SEQUENCE #define SEQUENCE(id) static_assert(seqCount(id)==1,"\n\nUSER ERROR: Duplicate ROUTE/AUTOMATION/SEQUENCE(" #id ")\n"); #undef AUTOMATION #define AUTOMATION(id,description) static_assert(seqCount(id)==1,"\n\nUSER ERROR: Duplicate ROUTE/AUTOMATION/SEQUENCE(" #id ")\n"); #undef ROUTE #define ROUTE(id,description) static_assert(seqCount(id)==1,"\n\nUSER ERROR: Duplicate ROUTE/AUTOMATION/SEQUENCE(" #id ")\n"); // check dangerous pins #define _PIN_RESERVED_ "\n\nUSER ERROR: Pin is used by Motor Shield or other critical function.\n" #undef SET #define SET(vpin, ...) static_assert(!unsafePin(vpin),"SET(" #vpin ")" _PIN_RESERVED_); #undef RESET #define RESET(vpin,...) static_assert(!unsafePin(vpin),"RESET(" #vpin ")" _PIN_RESERVED_); #undef BLINK #define BLINK(vpin,onDuty,offDuty) static_assert(!unsafePin(vpin),"BLINK(" #vpin ")" _PIN_RESERVED_); #undef SIGNAL #define SIGNAL(redpin,amberpin,greenpin) \ static_assert(!unsafePin(redpin),"Red pin " #redpin _PIN_RESERVED_); \ static_assert(amberpin==0 ||!unsafePin(amberpin),"Amber pin " #amberpin _PIN_RESERVED_); \ static_assert(!unsafePin(greenpin),"Green pin " #greenpin _PIN_RESERVED_); #undef SIGNALH #define SIGNALH(redpin,amberpin,greenpin) \ static_assert(!unsafePin(redpin),"Red pin " #redpin _PIN_RESERVED_); \ static_assert(amberpin==0 ||!unsafePin(amberpin),"Amber pin " #amberpin _PIN_RESERVED_); \ static_assert(!unsafePin(greenpin),"Green pin " #greenpin _PIN_RESERVED_); // and run the assert pass. #include "myAutomation.h" ================================================ FILE: EXRAILMacros.h ================================================ /* * © 2021 Neil McKechnie * © 2020-2025 Chris Harlow * © 2022-2023 Colin Murdoch * © 2023 Harald Barth * © 2025 Morten Nielsen * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef EXRAILMacros_H #define EXRAILMacros_H #include "IODeviceList.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. (also now IFLOCO). // CAUTION: The macros below are multiple passed over myAutomation.h // helper macro for turnout descriptions, creates NULL for missing description #define O_DESC(id, desc) case id: return ("" desc)[0]?F("" desc):NULL; // helper macro for turntable descriptions, creates NULL for missing description #define T_DESC(tid,pid,desc) if(turntableId==tid && positionId==pid) return ("" desc)[0]?F("" desc):NULL; // helper macro for turnout description as HIDDEN #define HIDDEN "\x01" // PLAYSOUND is deprecated and appears here temporarily so it does not get // extracted into the documentation. #define PLAYSOUND(vpin,v1,v2,code) ANOUT(vpin,v1,v2,DFPLayerBase::code) // SEG7 is a helper to create ANOUT from a 7-segment request #define SEG7(vpin,value,format) \ ANOUT(vpin,(value & 0xFFFF),TM1638::DF_##format,((uint32_t)value)>>16) // helper macro to strip leading zeros off time inputs // (10#mins)%100) #define STRIP_ZERO(value) 10##value%100 // These constants help EXRAIL macros convert Track Power e.g. SET_POWER(A ON|OFF). //const byte TRACK_POWER_0=0, TRACK_POWER_OFF=0; //const byte TRACK_POWER_1=1, TRACK_POWER_ON=1; // NEOPIXEL RG generator for NEOPIXEL_SIGNAL #define NeoRGB(red,green,blue) (((uint32_t)(red & 0xff)<<16) | ((uint32_t)(green & 0xff)<<8) | (uint32_t)(blue & 0xff)) // Collection of macros to assist variadic exrail macros // in particular RANDOMCALL and RANDOMFOLLOW // Count the number of arguments #define FOR_EACH_NARG(...) FOR_EACH_NARG_HELPER(__VA_ARGS__,8,7, 6,5,4, 3, 2, 1, 0) #define FOR_EACH_NARG_HELPER(_1, _2, _3, _4, _5, _6, _7, _8, N, ...) N // Force proper expansion (extra indirection to resolve `##`) #define _CONCAT_(a, b) a##b #define _EXPAND_(a) a #define ZC0() #define ZC1(_1) CALL(_1) #define ZC2(_1,_2) CALL(_1) CALL(_2) #define ZC3(_1,_2,_3) CALL(_1) CALL(_2) CALL(_3) #define ZC4(_1,_2,_3,_4) CALL(_1) CALL(_2) CALL(_3) CALL(_4) #define ZC5(_1,_2,_3,_4,_5) CALL(_1) CALL(_2) CALL(_3) CALL(_4) CALL(_5) #define ZC6(_1,_2,_3,_4,_5,_6) CALL(_1) CALL(_2) CALL(_3) CALL(_4) CALL(_5) CALL(_6) #define ZC7(_1,_2,_3,_4,_5,_6,_7) CALL(_1) CALL(_2) CALL(_3) CALL(_4) CALL(_5) CALL(_6) CALL(_7) #define ZC8(_1,_2,_3,_4,_5,_6,_7,_8) CALL(_1) CALL(_2) CALL(_3) CALL(_4) CALL(_5) CALL(_6) CALL(_7) CALL(_8) #define ZCRIP(count) _EXPAND_(_CONCAT_(ZC,count)) // Pass 1 Implements aliases #include "EXRAIL2MacroReset.h" #undef ALIAS #define ALIAS(name,value...) const int name= #value[0] ? value+0: -__COUNTER__ ; #include "myAutomation.h" // Perform compile time asserts to check the script for errors #include "EXRAILAsserts.h" // Pass 1g Implants STEALTH_GLOBAL in correct place #include "EXRAIL2MacroReset.h" #undef STEALTH_GLOBAL #define STEALTH_GLOBAL(code...) code #include "myAutomation.h" // Pass 1h Implements HAL macro by creating exrailHalSetup1 function // Also allows creating EXTurntable object #include "EXRAIL2MacroReset.h" #undef HAL #define HAL(haltype,params...) haltype::create(params); #undef HAL_IGNORE_DEFAULTS #define HAL_IGNORE_DEFAULTS ignore_defaults=true; bool exrailHalSetup1() { bool ignore_defaults=false; #include "myAutomation.h" return ignore_defaults; } // Pass 1s Implements servos by creating exrailHalSetup2 // TODO Turnout and turntable creation should be moved to here instead of // the first pass from the opcode table. #include "EXRAIL2MacroReset.h" #undef JMRI_SENSOR #define JMRI_SENSOR(vpin,count...) \ { \ const int npins=#count[0]? count+0:1; \ static byte state_map[(npins+7)/8]; \ SensorGroup::doSensorGroup(vpin,npins,state_map,action,stream,true); \ } #undef JMRI_SENSOR_NOPULLUP #define JMRI_SENSOR_NOPULLUP(vpin,count...) \ { \ const int npins=#count[0]? count+0:1; \ static byte state_map[(npins+7)/8]; \ SensorGroup::doSensorGroup(vpin,npins,state_map,action,stream,false); \ } void SensorGroup::doExrailSensorGroup(GroupProcess action, Print * stream) { (void) action; // suppress unused warnings if no groups (void) stream; #include "myAutomation.h" } // Pass 1s Implements servos by creating exrailHalSetup2 // TODO Turnout and turntable creation should be moved to here instead of // the first pass from the opcode table. #include "EXRAIL2MacroReset.h" #undef CONFIGURE_SERVO #define CONFIGURE_SERVO(vpin,pos1,pos2,profile) IODevice::configureServo(vpin,pos1,pos2,PCA9685::profile); void exrailHalSetup2() { #include "myAutomation.h" // pullup any group sensors SensorGroup::prepareAll(); } // Pass 1c detect compile time featurtes #include "EXRAIL2MacroReset.h" #undef SIGNAL #define SIGNAL(redpin,amberpin,greenpin) | FEATURE_SIGNAL #undef SIGNALH #define SIGNALH(redpin,amberpin,greenpin) | FEATURE_SIGNAL #undef SERVO_SIGNAL #define SERVO_SIGNAL(vpin,redval,amberval,greenval) | FEATURE_SIGNAL #undef DCC_SIGNAL #define DCC_SIGNAL(id,addr,subaddr) | FEATURE_SIGNAL #undef DCCX_SIGNAL #define DCCX_SIGNAL(id,redAspect,amberAspect,greenAspect) | FEATURE_SIGNAL #undef NEOPIXEL_SIGNAL #define NEOPIXEL_SIGNAL(sigid,redcolour,ambercolour,greencolour) | FEATURE_SIGNAL #undef VIRTUAL_SIGNAL #define VIRTUAL_SIGNAL(id) | FEATURE_SIGNAL #undef LCC #define LCC(eventid) | FEATURE_LCC #undef LCCX #define LCCX(senderid,eventid) | FEATURE_LCC #undef ONLCC #define ONLCC(senderid,eventid) | FEATURE_LCC #undef ACON #define ACON(eventid) | FEATURE_LCC #undef ACOF #define ACOF(eventid) | FEATURE_LCC #undef ONACON #define ONACON(eventid) | FEATURE_LCC #undef ONACOF #define ONACOF(eventid) | FEATURE_LCC #undef ROUTE_ACTIVE #define ROUTE_ACTIVE(id) | FEATURE_ROUTESTATE #undef ROUTE_INACTIVE #define ROUTE_INACTIVE(id) | FEATURE_ROUTESTATE #undef ROUTE_HIDDEN #define ROUTE_HIDDEN(id) | FEATURE_ROUTESTATE #undef ROUTE_DISABLED #define ROUTE_DISABLED(id) | FEATURE_ROUTESTATE #undef ROUTE_CAPTION #define ROUTE_CAPTION(id,caption) | FEATURE_ROUTESTATE #undef IFROUTE_ACTIVE #define IFROUTE_ACTIVE(id) | FEATURE_ROUTESTATE #undef IFROUTE_INACTIVE #define IFROUTE_INACTIVE(id) | FEATURE_ROUTESTATE #undef IFROUTE_HIDDEN #define IFROUTE_HIDDEN(id) | FEATURE_ROUTESTATE #undef IFROUTE_DISABLED #define IFROUTE_DISABLED(id) | FEATURE_ROUTESTATE #undef BLINK #define BLINK(vpin,onDuty,offDuty) | FEATURE_BLINK #undef ONBUTTON #define ONBUTTON(vpin) | FEATURE_SENSOR #undef ONSENSOR #define ONSENSOR(vpin) | FEATURE_SENSOR #undef ONBITMAP #define ONBITMAP(vpin) | FEATURE_SENSOR #undef ONBLOCKENTER #define ONBLOCKENTER(blockid) | FEATURE_BLOCK #undef ONBLOCKEXIT #define ONBLOCKEXIT(blockid) | FEATURE_BLOCK const byte RMFT2::compileFeatures = 0 #include "myAutomation.h" ; // Pass 2 create throttle route list #include "EXRAIL2MacroReset.h" #undef ROUTE #define ROUTE(id, description) id, const int16_t HIGHFLASH RMFT2::routeIdList[]= { #include "myAutomation.h" INT16_MAX}; // Pass 2a create throttle automation list #include "EXRAIL2MacroReset.h" #undef AUTOMATION #define AUTOMATION(id, description) id, const int16_t HIGHFLASH RMFT2::automationIdList[]= { #include "myAutomation.h" INT16_MAX}; // Pass 3 Create route descriptions: #undef ROUTE #define ROUTE(id, description) case id: return F(description); #undef AUTOMATION #define AUTOMATION(id, description) case id: return F(description); const FSH * RMFT2::getRouteDescription(int16_t id) { switch(id) { #include "myAutomation.h" default: break; } return F(""); } // Pass 4... Create Text sending functions #include "EXRAIL2MacroReset.h" const int StringMacroTracker1=__COUNTER__; #define THRUNGE(msg,mode) \ case (__COUNTER__ - StringMacroTracker1) : {\ static const char HIGHFLASH thrunge[]=msg;\ strfar=(uint32_t)GETFARPTR(thrunge);\ tmode=mode;\ break;\ } #undef BROADCAST #define BROADCAST(msg) THRUNGE(msg,thrunge_broadcast) #undef PARSE #define PARSE(msg) THRUNGE(msg,thrunge_parse) #undef PRINT #define PRINT(msg) THRUNGE(msg,thrunge_print) #undef LCN #define LCN(msg) THRUNGE(msg,thrunge_lcn) #undef MESSAGE #define MESSAGE(msg) THRUNGE(msg,thrunge_message) #undef ROUTE_CAPTION #define ROUTE_CAPTION(id,caption) \ case (__COUNTER__ - StringMacroTracker1) : {\ manageRouteCaption(id,F(caption));\ return;\ } #undef SERIAL #define SERIAL(msg) THRUNGE(msg,thrunge_serial) #undef SERIAL1 #define SERIAL1(msg) THRUNGE(msg,thrunge_serial1) #undef SERIAL2 #define SERIAL2(msg) THRUNGE(msg,thrunge_serial2) #undef SERIAL3 #define SERIAL3(msg) THRUNGE(msg,thrunge_serial3) #undef SERIAL4 #define SERIAL4(msg) THRUNGE(msg,thrunge_serial4) #undef SERIAL5 #define SERIAL5(msg) THRUNGE(msg,thrunge_serial5) #undef SERIAL6 #define SERIAL6(msg) THRUNGE(msg,thrunge_serial6) #undef IFLOCO #define IFLOCO(locolist...) \ case (__COUNTER__ - StringMacroTracker1) : \ { \ const int16_t temp[]={locolist}; \ skipIf=true; \ for (size_t i=0; i bool { return (code);}); \ return; #undef ZTEST2 #define ZTEST2(command,response) case (__COUNTER__ - StringMacroTracker1) : \ Ztest::parse(F(command),F(response),nullptr); \ return; #undef ZTEST3 #define ZTEST3(command,response,code...) case (__COUNTER__ - StringMacroTracker1) : \ Ztest::parse(F(command),F(response),[]() -> bool { return (code);}); \ return; #include "Ztest.h" void RMFT2::printMessage(uint16_t id) { thrunger tmode; uint32_t strfar=0; byte lcdid=0; switch(id) { #include "myAutomation.h" default: break ; } if (strfar) thrungeString(strfar,tmode,lcdid); } // Pass 5: Turnout descriptions (optional) #include "EXRAIL2MacroReset.h" #undef TURNOUT #define TURNOUT(id,addr,subaddr,description...) O_DESC(id,description) #undef TURNOUTL #define TURNOUTL(id,addr,description...) O_DESC(id,description) #undef PIN_TURNOUT #define PIN_TURNOUT(id,pin,description...) O_DESC(id,description) #undef SERVO_TURNOUT #define SERVO_TURNOUT(id,pin,activeAngle,inactiveAngle,profile,description...) O_DESC(id,description) #undef VIRTUAL_TURNOUT #define VIRTUAL_TURNOUT(id,description...) O_DESC(id,description) const FSH * RMFT2::getTurnoutDescription(int16_t turnoutid) { switch (turnoutid) { #include "myAutomation.h" default:break; } return NULL; } // Pass to get turntable descriptions (optional) #include "EXRAIL2MacroReset.h" #undef DCC_TURNTABLE #define DCC_TURNTABLE(id,home,description...) O_DESC(id,description) #undef EXTT_TURNTABLE #define EXTT_TURNTABLE(id,vpin,home,description...) O_DESC(id,description) const FSH * RMFT2::getTurntableDescription(int16_t turntableId) { switch (turntableId) { #include "myAutomation.h" default:break; } return NULL; } // Pass to get turntable position descriptions (optional) #include "EXRAIL2MacroReset.h" #undef TT_ADDPOSITION #define TT_ADDPOSITION(turntable_id,position,value,home,description...) T_DESC(turntable_id,position,description) const FSH * RMFT2::getTurntablePositionDescription(int16_t turntableId, uint8_t positionId) { (void)turntableId; (void)positionId; #include "myAutomation.h" return NULL; } // Pass 6: Roster IDs (count) #include "EXRAIL2MacroReset.h" #undef ROSTER #define ROSTER(cabid,name,funcmap...) +(cabid <= 0 ? 0 : 1) const byte RMFT2::rosterNameCount=0 #include "myAutomation.h" ; // Pass 6: Roster IDs #include "EXRAIL2MacroReset.h" #undef ROSTER #define ROSTER(cabid,name,funcmap...) cabid, const int16_t HIGHFLASH RMFT2::rosterIdList[]={ #include "myAutomation.h" INT16_MAX}; // Pass 7: Roster names getter #include "EXRAIL2MacroReset.h" #undef ROSTER #define ROSTER(cabid,name,funcmap...) case cabid: return F(name); const FSH * RMFT2::getRosterName(int16_t id) { switch(id) { #include "myAutomation.h" default: break; } return F(""); } // Pass to get roster functions #undef ROSTER #define ROSTER(cabid,name,funcmap...) case cabid: return F("" funcmap); const FSH * RMFT2::getRosterFunctions(int16_t id) { switch(id) { #include "myAutomation.h" default: break; } return NULL; } // Pass 8 Signal definitions #include "EXRAIL2MacroReset.h" #undef SIGNAL #define SIGNAL(redpin,amberpin,greenpin) {sigtypeSIGNAL,redpin,redpin,amberpin,greenpin}, #undef SIGNALH #define SIGNALH(redpin,amberpin,greenpin) {sigtypeSIGNALH,redpin,redpin,amberpin,greenpin}, #undef SERVO_SIGNAL #define SERVO_SIGNAL(vpin,redval,amberval,greenval) {sigtypeSERVO,vpin,redval,amberval,greenval}, #undef DCC_SIGNAL #define DCC_SIGNAL(id,addr,subaddr) {sigtypeDCC,id,addr,subaddr,0}, #undef DCCX_SIGNAL #define DCCX_SIGNAL(id,redAspect,amberAspect,greenAspect) {sigtypeDCCX,id,redAspect,amberAspect,greenAspect}, #undef NEOPIXEL_SIGNAL #define NEOPIXEL_SIGNAL(id,redRGB,amberRGB,greenRGB) \ {sigtypeNEOPIXEL,id,((VPIN)((redRGB)>>8)), ((VPIN)((amberRGB)>>8)), ((VPIN)((greenRGB)>>8))},\ {sigtypeContinuation,id,((VPIN)((redRGB) & 0xff)), ((VPIN)((amberRGB) & 0xFF)), ((VPIN)((greenRGB) & 0xFF))}, #undef VIRTUAL_SIGNAL #define VIRTUAL_SIGNAL(id) {sigtypeVIRTUAL,id,0,0,0}, const HIGHFLASH SIGNAL_DEFINITION RMFT2::SignalDefinitions[] = { #include "myAutomation.h" {sigtypeNoMoreSignals,0,0,0,0} }; // Pass 9 ONLCC/ ONMERG counter and lookup array #include "EXRAIL2MacroReset.h" #undef ONLCC #define ONLCC(sender,event) +1 #undef ONACON #define ONACON(event) +1 #undef ONACOF #define ONACOF(event) +1 const int RMFT2::countLCCLookup=0 #include "myAutomation.h" ; int RMFT2::onLCCLookup[RMFT2::countLCCLookup]; // Last Pass : create main routes table // Only undef the macros, not dummy them. #define RMFT2_UNDEF_ONLY #include "EXRAIL2MacroReset.h" // Define internal helper macros. // Everything we generate here has to be compile-time evaluated to // a constant. #define V(val) (byte)(((int16_t)(val))&0x00FF),(byte)(((int16_t)(val)>>8)&0x00FF) // Define macros for route code creation #define ACTIVATE(addr,subaddr) OPCODE_DCCACTIVATE,V(addr<<3 | subaddr<<1 | 1), #define ACTIVATEL(addr) OPCODE_DCCACTIVATE,V((addr+3)<<1 | 1), #define AFTER(sensor_id,timer...) OPCODE_AT,V(sensor_id),OPCODE_AFTER,V(sensor_id),OPCODE_PAD,V(#timer[0]?timer+0:500), #define AFTEROVERLOAD(track_id) OPCODE_AFTEROVERLOAD,V(TRACK_NUMBER_##track_id), #define ALIAS(name,value...) #define AMBER(signal_id) OPCODE_AMBER,V(signal_id), #define ANOUT(vpin,value,param1,param2) OPCODE_SERVO,V(vpin),OPCODE_PAD,V(value),OPCODE_PAD,V(param1),OPCODE_PAD,V(param2), #define ASPECT(address,value) OPCODE_ASPECT,V((address<<5) | (value & 0x1F)), #define AT(sensor_id) OPCODE_AT,V(sensor_id), #define ATGTE(sensor_id,value) OPCODE_ATGTE,V(sensor_id),OPCODE_PAD,V(value), #define ATLT(sensor_id,value) OPCODE_ATLT,V(sensor_id),OPCODE_PAD,V(value), #define ATTIMEOUT(sensor_id,timeout) OPCODE_ATTIMEOUT1,0,0,OPCODE_ATTIMEOUT2,V(sensor_id),OPCODE_PAD,V(timeout/100L), #define AUTOMATION(id, description) OPCODE_AUTOMATION, V(id), #define AUTOSTART OPCODE_AUTOSTART,0,0, #define BLINK(vpin,onDuty,offDuty) OPCODE_BLINK,V(vpin),OPCODE_PAD,V(onDuty),OPCODE_PAD,V(offDuty), #define BUILD_CONSIST(addloco) OPCODE_CONSIST,V(addloco), #define BREAK_CONSIST OPCODE_CONSIST,V(0), #define BROADCAST(msg) PRINT(msg) #define CALL(route) OPCODE_CALL,V(route), #define CLEAR_STASH(id) OPCODE_CLEAR_STASH,V(id), #define CLEAR_ALL_STASH OPCODE_CLEAR_ALL_STASH,V(0), #define CLEAR_ANY_STASH OPCODE_CLEAR_ANY_STASH,V(0), #define CLOSE(id) OPCODE_CLOSE,V(id), #define CONFIGURE_SERVO(vpin,pos1,pos2,profile) #ifndef IO_NO_HAL #define DCC_TURNTABLE(id,home,description...) OPCODE_DCCTURNTABLE,V(id),OPCODE_PAD,V(home), #endif #define DEACTIVATE(addr,subaddr) OPCODE_DCCACTIVATE,V(addr<<3 | subaddr<<1), #define DEACTIVATEL(addr) OPCODE_DCCACTIVATE,V((addr+3)<<1), #define DELAY(ms) ms<30000?OPCODE_DELAYMS:OPCODE_DELAY,V(ms/(ms<30000?1L:100L)), #define DELAYMINS(mindelay) OPCODE_DELAYMINS,V(mindelay), #define DELAYRANDOM(mindelay,maxdelay) DELAY(mindelay) OPCODE_RANDWAIT,V((maxdelay-mindelay)/100L), #define DCC_SIGNAL(id,add,subaddr) #define DCCX_SIGNAL(id,redAspect,amberAspect,greenAspect) #define DONE OPCODE_ENDTASK,0,0, #define DRIVE(analogpin) OPCODE_DRIVE,V(analogpin), #define ELSE OPCODE_ELSE,0,0, #define ENDEXRAIL #define ENDIF OPCODE_ENDIF,0,0, #define ENDTASK OPCODE_ENDTASK,0,0, #define ESTOP OPCODE_SPEED,V(1), #define ESTOPALL OPCODE_ESTOPALL,V(0), #define ESTOP_PAUSE OPCODE_ESTOPALL,V(1), #define ESTOP_RESUME OPCODE_ESTOPALL,V(2), #define EXRAIL #ifndef IO_NO_HAL #define EXTT_TURNTABLE(id,vpin,home,description...) OPCODE_EXTTTURNTABLE,V(id),OPCODE_PAD,V(vpin),OPCODE_PAD,V(home), #endif #define FADE(pin,value,ms) OPCODE_SERVO,V(pin),OPCODE_PAD,V(value),OPCODE_PAD,V((int16_t)PCA9685::ProfileType::UseDuration|(int16_t)PCA9685::ProfileType::NoPowerOff),OPCODE_PAD,V(ms/100L), #define FOFF(func) OPCODE_FOFF,V(func), #define FOLLOW(route) OPCODE_FOLLOW,V(route), #define FON(func) OPCODE_FON,V(func), #define FORGET OPCODE_FORGET,0,0, #define FREE(blockid) OPCODE_FREE,V(blockid), #define FREEALL OPCODE_FREEALL,0,0, #define FTOGGLE(func) OPCODE_FTOGGLE,V(func), #define FWD(speed) OPCODE_FWD,V(speed), #define GREEN(signal_id) OPCODE_GREEN,V(signal_id), #define HAL(haltype,params...) #define HAL_IGNORE_DEFAULTS #define IF(sensor_id) OPCODE_IF,V(sensor_id), #define IFAMBER(signal_id) OPCODE_IFAMBER,V(signal_id), #define IFCLOSED(turnout_id) OPCODE_IFCLOSED,V(turnout_id), #define IFGREEN(signal_id) OPCODE_IFGREEN,V(signal_id), #define IFGTE(sensor_id,value) OPCODE_IFGTE,V(sensor_id),OPCODE_PAD,V(value), #define IFLOCO(loco_list...) OPCODE_IFLOCO,V(__COUNTER__ - StringMacroTracker2), #define IF_ALL(vpinlist...) OPCODE_IFLOCO,V(__COUNTER__ - StringMacroTracker2), #define IF_ANY(vpinlist...) OPCODE_IFLOCO,V(__COUNTER__ - StringMacroTracker2), #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 IFROUTE_ACTIVE(sequence_id) OPCODE_IF_ROUTE_ACTIVE,V(sequence_id), #define IFROUTE_INACTIVE(sequence_id) OPCODE_IF_ROUTE_INACTIVE,V(sequence_id), #define IFROUTE_HIDDEN(sequence_id) OPCODE_IF_ROUTE_HIDDEN,V(sequence_id), #define IFROUTE_DISABLED(sequence_id) OPCODE_IF_ROUTE_DISABLED,V(sequence_id), #define IFSTASH(stash_id) OPCODE_IFSTASH,V(stash_id), #define IFSTASHED_HERE(stash_id) OPCODE_IFSTASHED_HERE,V(stash_id), #define IFTHROWN(turnout_id) OPCODE_IFTHROWN,V(turnout_id), #define IFTIMEOUT OPCODE_IFTIMEOUT,0,0, #ifndef IO_NO_HAL #define IFTTPOSITION(id,position) OPCODE_IFTTPOSITION,V(id),OPCODE_PAD,V(position), #endif #define IFRE(sensor_id,value) OPCODE_IFRE,V(sensor_id),OPCODE_PAD,V(value), #define IFBITMAP_ALL(vpin,mask) OPCODE_IFBITMAP_ALL,V(vpin),OPCODE_PAD,V(mask), #define IFBITMAP_ANY(vpin,mask) OPCODE_IFBITMAP_ANY,V(vpin),OPCODE_PAD,V(mask), #define INVERT_DIRECTION OPCODE_INVERT_DIRECTION,0,0, #define JMRI_SENSOR(vpin,count...) #define JMRI_SENSOR_NOPULLUP(vpin,count...) #define JOIN OPCODE_JOIN,0,0, #define KILLALL OPCODE_KILLALL,0,0, #define LATCH(sensor_id) OPCODE_LATCH,V(sensor_id), #define LCC(eventid) OPCODE_LCC,V(eventid), #define LCCX(sender,event) OPCODE_LCCX,V(event),\ OPCODE_PAD,V((((uint64_t)sender)>>32)&0xFFFF),\ OPCODE_PAD,V((((uint64_t)sender)>>16)&0xFFFF),\ OPCODE_PAD,V((((uint64_t)sender)>>0)&0xFFFF), #define ACON(eventid) OPCODE_ACON,V(((uint32_t)eventid >>16) & 0xFFFF),OPCODE_PAD,V(eventid & 0xFFFF), #define ACOF(eventid) OPCODE_ACOF,V(((uint32_t)eventid >>16) & 0xFFFF),OPCODE_PAD,V(eventid & 0xFFFF), #define ONACON(eventid) OPCODE_ONACON,V((uint32_t)(eventid) >>16),OPCODE_PAD,V(eventid & 0xFFFF), #define ONACOF(eventid) OPCODE_ONACOF,V((uint32_t)(eventid) >>16),OPCODE_PAD,V(eventid & 0xFFFF), #define LCD(id,msg) PRINT(msg) #define SCREEN(display,id,msg) PRINT(msg) #define STEALTH(code...) PRINT(dummy) #define STEALTH_GLOBAL(code...) #define LCN(msg) PRINT(msg) #define MESSAGE(msg) PRINT(msg) #define MOMENTUM(accel,decel...) OPCODE_MOMENTUM,V(accel),OPCODE_PAD,V(#decel[0]?decel+0:accel), #define MOVETT(id,steps,activity) OPCODE_SERVO,V(id),OPCODE_PAD,V(steps),OPCODE_PAD,V(EXTurntable::activity),OPCODE_PAD,V(0), #define NEOPIXEL(id,r,g,b,count...) OPCODE_NEOPIXEL,V(id),\ OPCODE_PAD,V(((r & 0xff)<<8) | (g & 0xff)),\ OPCODE_PAD,V((b & 0xff)),\ OPCODE_PAD,V(#count[0]?(count+0):1), #define NEOPIXEL_SIGNAL(sigid,redcolour,ambercolour,greencolour) #define ONACTIVATE(addr,subaddr) OPCODE_ONACTIVATE,V(addr<<2|subaddr), #define ONACTIVATEL(linear) OPCODE_ONACTIVATE,V(linear+3), #define ONAMBER(signal_id) OPCODE_ONAMBER,V(signal_id), #define ONBLOCKENTER(block_id) OPCODE_ONBLOCKENTER,V(block_id), #define ONBLOCKEXIT(block_id) OPCODE_ONBLOCKEXIT,V(block_id), #define ONCLOSE(turnout_id) OPCODE_ONCLOSE,V(turnout_id), #define ONLCC(sender,event) OPCODE_ONLCC,V(event),\ OPCODE_PAD,V((((uint64_t)sender)>>32)&0xFFFF),\ OPCODE_PAD,V((((uint64_t)sender)>>16)&0xFFFF),\ OPCODE_PAD,V((((uint64_t)sender)>>0)&0xFFFF), #define ONTIME(value) OPCODE_ONTIME,V(value), #define ONCLOCKTIME(hours,mins) OPCODE_ONTIME,V((STRIP_ZERO(hours)*60)+STRIP_ZERO(mins)), #define ONCLOCKMINS(mins) ONCLOCKTIME(25,mins) #define ONOVERLOAD(track_id) OPCODE_ONOVERLOAD,V(TRACK_NUMBER_##track_id), #define ONRAILSYNCON OPCODE_ONRAILSYNCON,0,0, #define ONRAILSYNCOFF OPCODE_ONRAILSYNCOFF,0,0, #define ONDEACTIVATE(addr,subaddr) OPCODE_ONDEACTIVATE,V(addr<<2|subaddr), #define ONDEACTIVATEL(linear) OPCODE_ONDEACTIVATE,V(linear+3), #define ONGREEN(signal_id) OPCODE_ONGREEN,V(signal_id), #define ONRED(signal_id) OPCODE_ONRED,V(signal_id), #ifndef IO_NO_HAL #define ONROTATE(id) OPCODE_ONROTATE,V(id), #endif #define ONTHROW(turnout_id) OPCODE_ONTHROW,V(turnout_id), #define ONCHANGE(sensor_id) OPCODE_ONCHANGE,V(sensor_id), #define ONSENSOR(sensor_id) OPCODE_ONSENSOR,V(sensor_id), #define ONBITMAP(sensor_id) OPCODE_ONBITMAP,V(sensor_id), #define ONBUTTON(sensor_id) OPCODE_ONBUTTON,V(sensor_id), #define PAUSE OPCODE_PAUSE,0,0, #define PICKUP_STASH(id) OPCODE_PICKUP_STASH,V(id), #define PIN_TURNOUT(id,pin,description...) OPCODE_PINTURNOUT,V(id),OPCODE_PAD,V(pin), #define PLAY_EQ(vpin,eqname) ANOUT(vpin,0,DFPlayerBase::DF_EQ_##eqname,DFPlayerBase::DF_EQ) #define PLAY_FOLDER(vpin,folder) ANOUT(vpin,0,folder,DFPlayerBase::DF_FOLDER) #define PLAY_PAUSE(vpin) ANOUT(vpin,0,0,DFPlayerBase::DF_PAUSE) #define PLAY_REPEAT(vpin,track,volume...) ANOUT(vpin,track,volume+0,DFPlayerBase::DF_REPEATPLAY) #define PLAY_RESET(vpin) ANOUT(vpin,0,0,DFPlayerBase::DF_RESET) #define PLAY_RESUME(vpin) ANOUT(vpin,0,0,DFPlayerBase::DF_RESUME) #define PLAY_STOP(vpin) ANOUT(vpin,0,0,DFPlayerBase::DF_STOPPLAY) #define PLAY_TRACK(vpin,track,volume...) ANOUT(vpin,track,volume+0,DFPlayerBase::DF_PLAY) #define PLAY_VOLUME(vpin,volume) ANOUT(vpin,0,volume,DFPlayerBase::DF_VOL) #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 RANDOM_CALL(...) \ OPCODE_RANDOM_CALL,V(FOR_EACH_NARG(__VA_ARGS__)), \ ZCRIP(FOR_EACH_NARG(__VA_ARGS__))(__VA_ARGS__) #define RANDOM_FOLLOW(...) \ OPCODE_RANDOM_FOLLOW,V(FOR_EACH_NARG(__VA_ARGS__)), \ ZCRIP(FOR_EACH_NARG(__VA_ARGS__))(__VA_ARGS__) #define READ_LOCO OPCODE_READ_LOCO1,0,0,OPCODE_READ_LOCO2,0,0, #define RED(signal_id) OPCODE_RED,V(signal_id), #define RESERVE(blockid) OPCODE_RESERVE,V(blockid), #define RESET(pin,count...) OPCODE_RESET,V(pin),OPCODE_PAD,V(#count[0] ? count+0: 1), #define RESUME OPCODE_RESUME,0,0, #define RETURN OPCODE_RETURN,0,0, #define REV(speed) OPCODE_REV,V(speed), #define ROSTER(cabid,name,funcmap...) #ifndef IO_NO_HAL #define ROTATE(id,position,activity) OPCODE_ROTATE,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(EXTurntable::activity), #define ROTATE_DCC(id,position) OPCODE_ROTATE,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(0), #endif #define ROUTE(id, description) OPCODE_ROUTE, V(id), #define ROUTE_ACTIVE(id) OPCODE_ROUTE_ACTIVE,V(id), #define ROUTE_INACTIVE(id) OPCODE_ROUTE_INACTIVE,V(id), #define ROUTE_HIDDEN(id) OPCODE_ROUTE_HIDDEN,V(id), #define ROUTE_DISABLED(id) OPCODE_ROUTE_DISABLED,V(id), #define ROUTE_CAPTION(id,caption) PRINT(caption) #define SAVE_SPEED OPCODE_SAVE_SPEED,V(0), #define RESTORE_SPEED OPCODE_RESTORE_SPEED,V(0), #define SENDLOCO(cab,route) OPCODE_SENDLOCO,V(cab),OPCODE_PAD,V(route), #define SEQUENCE(id) OPCODE_SEQUENCE, V(id), #define SERIAL(msg) PRINT(msg) #define SERIAL1(msg) PRINT(msg) #define SERIAL2(msg) PRINT(msg) #define SERIAL3(msg) PRINT(msg) #define SERIAL4(msg) PRINT(msg) #define SERIAL5(msg) PRINT(msg) #define SERIAL6(msg) PRINT(msg) #define SERVO(id,position,profile) OPCODE_SERVO,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(PCA9685::profile),OPCODE_PAD,V(0), #define SERVO2(id,position,ms) OPCODE_SERVO,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(PCA9685::Instant),OPCODE_PAD,V(ms/100L), #define SERVO_SIGNAL(vpin,redpos,amberpos,greenpos) #define SERVO_TURNOUT(id,pin,activeAngle,inactiveAngle,profile,description...) OPCODE_SERVOTURNOUT,V(id),OPCODE_PAD,V(pin),OPCODE_PAD,V(activeAngle),OPCODE_PAD,V(inactiveAngle),OPCODE_PAD,V(PCA9685::ProfileType::profile), #define SET(pin,count...) OPCODE_SET,V(pin),OPCODE_PAD,V(#count[0] ? count+0: 1), #define SET_TRACK(track,mode) OPCODE_SET_TRACK,V(TRACK_MODE_##mode <<8 | TRACK_NUMBER_##track), #define SET_POWER(track,onoff) OPCODE_SET_POWER,V(TRACK_POWER_##onoff),OPCODE_PAD, V(TRACK_NUMBER_##track), #define SETLOCO(loco) OPCODE_SETLOCO,V(loco), #define SETFREQ(freq) OPCODE_SETFREQ,V(freq), #define SIGNAL(redpin,amberpin,greenpin) #define SIGNALH(redpin,amberpin,greenpin) #define SPEED(speed) OPCODE_SPEED,V(speed), #define SPEEDUP(speedstep) OPCODE_SPEEDUP,V(speedstep), #define SPEED_REL(percent) OPCODE_SPEED_REL,V(percent), #define SLOWDOWN(speedstep) OPCODE_SLOWDOWN,V(speedstep), #define START(route) OPCODE_START,V(route), #define START_SHARED(route) OPCODE_START_SHARED,V(route), #define START_SEND(route) OPCODE_START_SEND,V(route), #define STASH(id) OPCODE_STASH,V(id), #define STOP OPCODE_SPEED,V(0), #define THROW(id) OPCODE_THROW,V(id), #define TOGGLE_TURNOUT(id) OPCODE_TOGGLE_TURNOUT,V(id), #ifndef IO_NO_HAL #define TT_ADDPOSITION(id,position,value,angle,description...) OPCODE_TTADDPOSITION,V(id),OPCODE_PAD,V(position),OPCODE_PAD,V(value),OPCODE_PAD,V(angle), #endif #define TURNOUT(id,addr,subaddr,description...) OPCODE_TURNOUT,V(id),OPCODE_PAD,V(addr),OPCODE_PAD,V(subaddr), #define TURNOUTL(id,addr,description...) TURNOUT(id,(addr-1)/4+1,(addr-1)%4, description) #define UNJOIN OPCODE_UNJOIN,0,0, #define UNLATCH(sensor_id) OPCODE_UNLATCH,V(sensor_id), #define VIRTUAL_SIGNAL(id) #define VIRTUAL_TURNOUT(id,description...) OPCODE_PINTURNOUT,V(id),OPCODE_PAD,V(0), #define BITMAP_AND(vpin,mask) OPCODE_BITMAP_AND,V(vpin),OPCODE_PAD,V(mask), #define BITMAP_INC(vpin) OPCODE_BITMAP_INC,V(vpin), #define BITMAP_DEC(vpin) OPCODE_BITMAP_DEC,V(vpin), #define BITMAP_OR(vpin,mask) OPCODE_BITMAP_OR,V(vpin),OPCODE_PAD,V(mask), #define BITMAP_SET(vpin,value) ANOUT(vpin,value,0,0) #define BITMAP_XOR(vpin,mask) OPCODE_BITMAP_XOR,V(vpin),OPCODE_PAD,V(mask), #define WITHROTTLE(msg) PRINT(msg) #define WAITFOR(pin) OPCODE_WAITFOR,V(pin), #ifndef IO_NO_HAL #define WAITFORTT(turntable_id) OPCODE_WAITFORTT,V(turntable_id), #endif #define WAIT_WHILE_RED(signal_id) OPCODE_WAIT_WHILE_RED,V(signal_id), #define XFOFF(cab,func) OPCODE_XFOFF,V(cab),OPCODE_PAD,V(func), #define XFON(cab,func) OPCODE_XFON,V(cab),OPCODE_PAD,V(func), #define XFTOGGLE(cab,func) OPCODE_XFTOGGLE,V(cab),OPCODE_PAD,V(func), #define XFWD(cab,speed) OPCODE_XFWD,V(cab),OPCODE_PAD,V(speed), #define XREV(cab,speed) OPCODE_XREV,V(cab),OPCODE_PAD,V(speed), #define XPOM(cab,cv,value) OPCODE_XPOM,V(cab),OPCODE_PAD,V(cv),OPCODE_PAD,V(value), #define XSAVE_SPEED(cab) OPCODE_XSAVE_SPEED,V(cab), #define XRESTORE_SPEED(cab) OPCODE_XRESTORE_SPEED,V(cab), #define ZTEST(command,code...) PRINT(dummy) #define ZTEST2(command,response) PRINT(dummy) #define ZTEST3(command,response,code...) PRINT(dummy) // Build RouteCode const int StringMacroTracker2=__COUNTER__; const HIGHFLASH3 byte RMFT2::RouteCode[] = { #include "myAutomation.h" OPCODE_ENDTASK,0,0,OPCODE_ENDEXRAIL,0,0 }; // Restore normal code LCD & SERIAL macro #undef LCD #define LCD StringFormatter::lcd #undef SCREEN #define SCREEN StringFormatter::lcd2 #undef SERIAL #define SERIAL 0x0 #endif ================================================ FILE: EXRAILSensor.cpp ================================================ /* * © 2024 Chris Harlow * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /********************************************************************** EXRAILSensor represents a sensor that should be monitored in order to call an exrail ONBUTTON or ONCHANGE handler. These are created at EXRAIL startup and thus need no delete or listing capability. The basic logic is similar to that found in the Sensor class except that on the relevant change an EXRAIL thread is started. **********************************************************************/ #include "EXRAILSensor.h" #include "EXRAIL2.h" void EXRAILSensor::checkAll() { if (firstSensor == NULL) return; // No sensors to be scanned if (readingSensor == NULL) { // Not currently scanning sensor list unsigned long thisTime = micros(); if (thisTime - lastReadCycle < cycleInterval) return; // Required time has elapsed since last read cycle started, // so initiate new scan through the sensor list readingSensor = firstSensor; lastReadCycle = thisTime; } // Loop until either end of list is encountered or we pause for some reason byte sensorCount = 0; while (readingSensor != NULL) { bool pause=readingSensor->check(); // Move to next sensor in list. readingSensor = readingSensor->nextSensor; // Currently process max of 16 sensors per entry. // Performance measurements taken during development indicate that, with 128 sensors configured // on 8x 16-pin MCP23017 GPIO expanders with polling (no change notification), all inputs can be read from the devices // within 1.4ms (400Mhz I2C bus speed), and a full cycle of checking 128 sensors for changes takes under a millisecond. if (pause || (++sensorCount)>=16) return; } } bool EXRAILSensor::check() { // check for debounced change in this sensor inputState = useAnalog?IODevice::readAnalogue(pin):RMFT2::readSensor(pin); // Check if changed since last time, and process changes. if (inputState == active) {// no change latchDelay = minReadCount; // Reset counter return false; // no change } // Change detected ... has it stayed changed for long enough if (latchDelay > 0) { latchDelay--; return false; } // change validated, act on it. active = inputState; latchDelay = minReadCount; // Reset debounce counter if (onChange || active) { new RMFT2(progCounter); return true; // Don't check any more sensors on this entry } return false; } EXRAILSensor::EXRAILSensor(VPIN _pin, int _progCounter, bool _onChange, bool _useAnalog) { nextSensor = firstSensor; firstSensor = this; pin=_pin; progCounter=_progCounter; onChange=_onChange; useAnalog=_useAnalog; IODevice::configureInput(pin, true); active = useAnalog?IODevice::readAnalogue(pin): IODevice::read(pin); inputState = active; latchDelay = minReadCount; } EXRAILSensor *EXRAILSensor::firstSensor=NULL; EXRAILSensor *EXRAILSensor::readingSensor=NULL; unsigned long EXRAILSensor::lastReadCycle=0; ================================================ FILE: EXRAILSensor.h ================================================ /* * © 2024 Chris Harlow * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef EXRAILSensor_h #define EXRAILSensor_h #include "IODevice.h" class EXRAILSensor { static EXRAILSensor * firstSensor; static EXRAILSensor * readingSensor; static unsigned long lastReadCycle; public: static void checkAll(); EXRAILSensor(VPIN _pin, int _progCounter, bool _onChange, bool _useAnalog=false); bool check(); private: static const unsigned int cycleInterval = 10000; // min time between consecutive reads of each sensor in microsecs. // should not be less than device scan cycle time. static const byte minReadCount = 4; // number of additional scans before acting on change // E.g. 1 means that a change is ignored for one scan and actioned on the next. // Max value is 63 EXRAILSensor* nextSensor; VPIN pin; int progCounter; uint16_t active; uint16_t inputState; bool onChange; bool useAnalog; byte latchDelay; }; #endif ================================================ FILE: EXRAILTest.h ================================================ // This file contains various EXRAIL tests. // It will need to be #included in a myAutomation.h to be executed. ROUTE(7000, "Route state tests") // Test route state management PRINT("Test 7001") ROUTE_ACTIVE(7000) IFROUTE_ACTIVE(7000) ELSE PRINT("7001a failed") ENDIF IFROUTE_INACTIVE(7000) PRINT("7001b failed") ENDIF ROUTE_INACTIVE(7000) IFROUTE_INACTIVE(7000) ELSE PRINT("7001c failed") ENDIF IFROUTE_ACTIVE(7000) PRINT("700d failed") ENDIF ROUTE_DISABLED(7000) IFROUTE_DISABLED(7000) ELSE PRINT("7001e failed") ENDIF IFROUTE_ACTIVE(7000) PRINT("700df failed") ENDIF IFROUTE_INACTIVE(7000) PRINT("700dg failed") ENDIF ROUTE_HIDDEN(7000) IFROUTE_HIDDEN(7000) ELSE PRINT("7001h failed") ENDIF ROUTE_INACTIVE(7000) DONE // Test WAIT_WHILE_RED VIRTUAL_SIGNAL(1) ROUTE(7100, "7100 WAIT_WHILE_RED test") SETLOCO(3) SPEED(10) RED(1) PRINT("7100 Waiting at signal 1") PRINT("7100 Tester please set signal 1 GREEN or AMBER to continue") WAIT_WHILE_RED(1) SPEED(10) PRINT("7100 Resumed at signal 1") DONE // TEST new FREEALL command ROUTE(7200,"7200 Test FREEALL") RESERVE(1) RESERVE(255) PARSE("") FREEALL PARSE("") IFRESERVE(1) PRINT("7200 FREEALL test worked") ELSE PRINT("7200 FREEALL test fail") ENDIF DONE // Test SEND_LOCO_X and SEND_LOCO_S ROUTE(7300,"7300 Test SEND_LOCO_ variants") SETLOCO(5) // Share loco and check we doidnt lose it START_SHARED(7301) IFLOCO(5) ELSE PRINT("7300 START_SHARED failed") ENDIF // transfer loco and check we do lose it START_SEND(7302) IFLOCO(0) ELSE PRINT("7300 START_SEND failed") ENDIF DONE SEQUENCE(7301) IFLOCO(5) PRINT("7301 START_SHARED received") ELSE PRINT("7301 START_SHARED failed") ENDIF DONE SEQUENCE(7302) IFLOCO(5) PRINT("7302 START_SEND received") ELSE PRINT("7302 START_SEND failed") ENDIF DONE SEQUENCE(7400) SETLOCO(3) SPEED(20) SAVE_SPEED SPEED(40) PRINT("7401 Speed changed to 40") RESTORE_SPEED PRINT("7401 Speed restored") XFWD(4,20) XSAVE_SPEED(4) XFWD(4,40) PRINT("7401 Speed 4 changed to 40") XRESTORE_SPEED(4) PRINT("7401 Speed 4 restored") DONE SEQUENCE(7500) PRINT("7500 Testing RANDOM_CALL and RANDOM_FOLLOW") RANDOM_CALL(7501, 7502, 7503) PRINT("7500 Returned from RANDOM_CALL") RANDOM_FOLLOW(7511, 7512, 7513) PRINT("7500 ERROR Returned from RANDOM_FOLLOW") DONE SEQUENCE(7501) PRINT("7501 RANDOM_CALL") RETURN SEQUENCE(7502) PRINT("7502 RANDOM_CALL") RETURN SEQUENCE(7503) PRINT("7503 RANDOM_CALL") RETURN SEQUENCE(7511) PRINT("7511 RANDOM_FOLLOW") DONE SEQUENCE(7512) PRINT("7512 RANDOM_FOLLOW") DONE SEQUENCE(7513) PRINT("7513 RANDOM_FOLLOW") DONE ROUTE(7600, "7600 Test CONSIST") PARSE("7600 Create 6 77 88 -99") SETLOCO(6) BUILD_CONSIST(77) BUILD_CONSIST(88) BUILD_CONSIST(-99) PARSE("<^>") // display consists PRINT("break up") BREAK_CONSIST PARSE("<^>") // display consists DONE HAL(Bitmap,870,10) ROUTE(7700,"Set 870 and wait") SET(870) AT(-870) PRINT("870 reset") DONE ROUTE(7701,"ResetS 870 and wait") RESET(870) AT(870) PRINT("870 set") DONE ROUTE(7702,"Bitmap Set 870") BITMAP_SET(870,1234) IFGTE(870,1234) IFLT(870,1235) PRINT("870 set correctly") DONE ENDIF ENDIF PRINT("870 not set correctly") DONE ROUTE(7800, "ZTESTS") PRINT("ZTESTS starting") ZTEST("",DCC::getLocoSpeedByte(3)==(128+6)) ZTEST("",DCC::getLocoSpeedByte(3)==(6)) ZTEST("<-3>",DCC::getLocoSpeedByte(3)==(128)) // speed up down and relative speed changes. SETLOCO(3) FWD(20) ZTEST("FWD(20)",DCC::getLocoSpeedByte(3)==(128+20)) SPEEDUP(10) ZTEST("SPEEDUP(10)",DCC::getLocoSpeedByte(3)==(128+30)) SPEED_REL(50) ZTEST("SPEED_REL(50)",DCC::getLocoSpeedByte(3)==(128+15)) SPEED_REL(300) ZTEST("SPEED_REL(300)",DCC::getLocoSpeedByte(3)==(128+45)) SLOWDOWN(5) ZTEST("SLOWDOWN(5)",DCC::getLocoSpeedByte(3)==(128+40)) DONE ROUTE(7900,"7900 Test IFSTASHED_HERE") SETLOCO(4) // set loco 4 STASH(200) // stash loco 4 in stash 2 // loco is 4 IFSTASHED_HERE(100) // should be false PRINT("FAIL Loco 4 in stash 100") ELSE PRINT("OK: loco 4 is not in stash 100") ENDIF SETLOCO(3) IFSTASHED_HERE(200) // should be false PRINT("FAIL Loco 3 in stash 200") ELSE PRINT("OK: loco 3 is not in stash 200") ENDIF IFSTASHED_HERE(100) // should be true PRINT("OK: Loco 3 is in stash 100") ELSE PRINT("FAIL: loco 3 not in stash 100") ENDIF DONE ROUTE(8000,"8000 ESTOP_PAUSE test") SETLOCO(3) // set loco 3 FWD(20) // ESTOP_PAUSE SETLOCO(0) // prevent DONE stopping it DONE ROUTE(8001,"8001 ESTOP_RESUME test") ESTOP_RESUME ZTEST("",DCC::getLocoSpeedByte(3)==(128+20)) DONE #define MYGROUP 1,2,3,4 ROUTE(1771,"1771 Test IFLOCO with multiple loco ids") SETLOCO(3) IFLOCO(MYGROUP) PRINT("IFLOCO 3 test passed") ELSE PRINT("IFLOCO 3 test failed") ENDIF IFLOCO(1,2,4, -1) PRINT("IFLOCO 1,2,4 test failed") ELSE PRINT("IFLOCO 1,2,4 test passed") ENDIF HAL(Bitmap,1700,10) SET(1702) SET(1703) SET(1704) IF_ANY(1700,1701,1702) PRINT("IF_ANY 0,1,2 test OK") ELSE PRINT("IF_ANY 0,1,2 test failed") ENDIF IF_ANY(1700,1701,1706) PRINT("IF_ANY 0,1,6 test failed") ELSE PRINT("IF_ANY 0,1,6 test passed") ENDIF IF_ALL(1702,1703,1704) PRINT("IF_ALL 2,3,4 test OK") ELSE PRINT("IF_ALL 2,3,4 test failed") ENDIF IF_ALL(1702,1703,1706) PRINT("IF_ALL 2,3,6 test failed") ELSE PRINT("IF_ALL 2,3,6 test passed") ENDIF IF_ANY(1701,-1706) PRINT("IF_ANY 1,-1706 test passed") ELSE PRINT("IF_ANY 1,-1706 test failed") ENDIF IF_ALL(1701,-1706) PRINT("IF_ALL 1,-1706 test failed") ELSE PRINT("IF_ALL 1,-1706 test passed") ENDIF DONE // Speedometer example // Track is =TS1===TS2===TS3= timing between S2 and S3. ALIAS(TS1,181) ALIAS(TS2,182) ALIAS(TS3,183) STEALTH_GLOBAL( byte testStartSpeed=2; byte testEndSpeed=100; byte testStep=10; byte testSpeed; unsigned long testStartTime; ) AUTOMATION(9000,"Run Speed Test") // speed test setup STEALTH(testSpeed=testStartSpeed;) PRINT("Starting speed test") REV(20) // reverse loco to start point SEQUENCE(9001) // make sure loco is at start point AT(TS1) ESTOP // drive loco fwd at testSpeed STEALTH(DCC::setThrottle(loco,testSpeed,true);) // At timing-start sensor(s2) record time AT(TS2) STEALTH(testStartTime=millis();) // at timing-end sensor(s3) stop and calculate and print speed AT(TS3) ESTOP STEALTH( StringFormatter::send(&USB_SERIAL, F("Speed %d Time %l\n"), testSpeed, millis()-testStartTime); testSpeed+=testStep; if (testSpeed>testEndSpeed) kill(); // test complete =DONE ) // Reverse back to start, and test again REV(127) FOLLOW(9001) ================================================ FILE: EXmDNS.cpp ================================================ /* * © 2024 Harald Barth * © 2024 Paul M. Antoine * 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 . */ #include #include "EthernetInterface.h" #ifdef DO_MDNS #include "EXmDNS.h" // fixed values for mDNS static IPAddress mdnsMulticastIPAddr = IPAddress(224, 0, 0, 251); #define MDNS_SERVER_PORT 5353 // dotToLen() // converts stings of form ".foo.barbar.x" to a string with the // dots replaced with lenght. So string above would result in // "\x03foo\x06barbar\x01x" in C notation. If not NULL, *substr // will point to the beginning of the last component, in this // example that would be "\x01x". // static void dotToLen(char *str, char **substr) { char *dotplace = NULL; char *s; byte charcount = 0; for (s = str;/*see break*/ ; s++) { if (*s == '.' || *s == '\0') { // take care of accumulated if (dotplace != NULL && charcount != 0) { *dotplace = charcount; } if (*s == '\0') break; if (substr && *s == '.') *substr = s; // set new values dotplace = s; charcount = 0; } else { charcount++; } } } MDNS::MDNS(EthernetUDP& udp) { _udp = &udp; } MDNS::~MDNS() { _udp->stop(); if (_name) free(_name); if (_serviceName) free(_serviceName); if (_serviceProto) free(_serviceProto); } int MDNS::begin(const IPAddress& ip, char* name) { // if we were called very soon after the board was booted, we need to give the // EthernetShield (WIZnet) some time to come up. Hence, we delay until millis() is at // least 3000. This is necessary, so that if we need to add a service record directly // after begin, the announce packet does not get lost in the bowels of the WIZnet chip. //while (millis() < 3000) // delay(100); _ipAddress = ip; _name = (char *)malloc(strlen(name)+2); byte n; for(n = 0; nbeginMulticast(mdnsMulticastIPAddr, MDNS_SERVER_PORT); } int MDNS::addServiceRecord(const char* name, uint16_t port, MDNSServiceProtocol_t proto) { // we ignore proto, assume TCP (void)proto; _serviceName = (char *)malloc(strlen(name) + 2); byte n; for(n = 0; n BROADCASTTIME * 1000UL)) { return; } lastrun = now; DNSHeader_t dnsHeader = {0, 0, 0, 0, 0, 0}; // DNSHeader_t dnsHeader = { 0 }; _udp->beginPacket(mdnsMulticastIPAddr, MDNS_SERVER_PORT); // dns header dnsHeader.flags = HTONS((uint16_t)0x8400); // Response, authorative dnsHeader.answerCount = HTONS(4 /*5 if TXT but we do not do that */); _udp->write((uint8_t*)&dnsHeader, sizeof(DNSHeader_t)); // rr #1, the PTR record from generic _services.x.local to service.x.local _udp->write((uint8_t*)dns_rr_services, sizeof(dns_rr_services)); byte buf[10]; buf[0] = 0x00; buf[1] = 0x0c; //PTR buf[2] = 0x00; buf[3] = 0x01; //IN *((uint32_t*)(buf+4)) = HTONL(120); //TTL in sec *((uint16_t*)(buf+8)) = HTONS( _serviceProto[0] + 1 + strlen(dns_rr_tcplocal) + 1); _udp->write(buf, 10); _udp->write(_serviceProto,_serviceProto[0]+1); _udp->write(dns_rr_tcplocal, strlen(dns_rr_tcplocal)+1); // rr #2, the PTR record from proto.x to name.proto.x _udp->write(_serviceProto,_serviceProto[0]+1); _udp->write(dns_rr_tcplocal, strlen(dns_rr_tcplocal)+1); *((uint16_t*)(buf+8)) = HTONS(strlen(_serviceName) + strlen(dns_rr_tcplocal) + 1); // recycle most of buf _udp->write(buf, 10); _udp->write(_serviceName, strlen(_serviceName)); _udp->write(dns_rr_tcplocal, strlen(dns_rr_tcplocal)+1); // rr #3, the SRV record for the service that points to local name _udp->write(_serviceName, strlen(_serviceName)); _udp->write(dns_rr_tcplocal, strlen(dns_rr_tcplocal)+1); buf[1] = 0x21; // recycle most of buf but here SRV buf[2] = 0x80; // cache flush *((uint16_t*)(buf+8)) = HTONS(strlen(_name) + strlen(dns_rr_local) + 1 + 6); _udp->write(buf, 10); byte srv[6]; // priority and weight srv[0] = srv[1] = srv[2] = srv[3] = 0; // port *((uint16_t*)(srv+4)) = HTONS(_servicePort); _udp->write(srv, 6); // target _udp->write(_name, _name[0]+1); _udp->write(dns_rr_local, strlen(dns_rr_local)+1); // rr #4, the A record for the name.local _udp->write(_name, _name[0]+1); _udp->write(dns_rr_local, strlen(dns_rr_local)+1); buf[1] = 0x01; // recycle most of buf but here A *((uint16_t*)(buf+8)) = HTONS(4); _udp->write(buf, 10); byte ip[4]; ip[0] = _ipAddress[0]; ip[1] = _ipAddress[1]; ip[2] = _ipAddress[2]; ip[3] = _ipAddress[3]; _udp->write(ip, 4); _udp->endPacket(); _udp->flush(); // } #endif //DO_MDNS ================================================ FILE: EXmDNS.h ================================================ /* * © 2024 Harald Barth * © 2024 Paul M. Antoine * 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 . */ #ifdef DO_MDNS #define BROADCASTTIME 15 //seconds // We do this ourselves because every library is different and/or broken... #define HTONS(x) ((uint16_t)(((x) << 8) | (((x) >> 8) & 0xFF))) #define HTONL(x) ( ((uint32_t)(x) << 24) | (((uint32_t)(x) << 8) & 0xFF0000) | \ (((uint32_t)(x) >> 8) & 0xFF00) | ((uint32_t)(x) >> 24) ) typedef enum _MDNSServiceProtocol_t { MDNSServiceTCP, MDNSServiceUDP } MDNSServiceProtocol_t; class MDNS { public: MDNS(EthernetUDP& udp); ~MDNS(); int begin(const IPAddress& ip, char* name); int addServiceRecord(const char* name, uint16_t port, MDNSServiceProtocol_t proto); void run(); private: EthernetUDP *_udp; IPAddress _ipAddress; char* _name; char* _serviceName; char* _serviceProto; int _servicePort; }; #endif //DO_MDNS ================================================ FILE: EthernetInterface.cpp ================================================ /* * © 2024 Morten "Doc" Nielsen * © 2023-2024 Paul M. Antoine * © 2022 Bruno Sanches * © 2021 Fred Decker * © 2020-2022 Harald Barth * © 2020-2024 Chris Harlow * © 2020 Gregor Baues * All rights reserved. * * This file is part of DCC-EX/CommandStation-EX * * 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 . * */ #include "defines.h" #if ETHERNET_ON == true #include "EthernetInterface.h" #include "DIAG.h" #include "CommandDistributor.h" #include "WiThrottle.h" #include "DCCTimer.h" #ifdef DO_MDNS #include "EXmDNS.h" EthernetUDP udp; MDNS mdns(udp); #endif //extern void looptimer(unsigned long timeout, const FSH* message); #define looptimer(a,b) bool EthernetInterface::connected=false; EthernetServer * EthernetInterface::server= nullptr; EthernetClient EthernetInterface::clients[MAX_SOCK_NUM]; // accept up to MAX_SOCK_NUM client connections at the same time; This depends on the chipset used on the Shield bool EthernetInterface::inUse[MAX_SOCK_NUM]; // accept up to MAX_SOCK_NUM client connections at the same time; This depends on the chipset used on the Shield uint8_t EthernetInterface::buffer[MAX_ETH_BUFFER+1]; // buffer used by TCP for the recv RingStream * EthernetInterface::outboundRing = nullptr; /** * @brief Setup Ethernet Connection * */ void EthernetInterface::setup() { DIAG(F("Ethernet starting" #ifdef DO_MDNS " (with mDNS)" #endif " Please be patient, especially if no cable is connected!" )); #ifdef STM32_ETHERNET // Set a HOSTNAME for the DHCP request - a nice to have, but hard it seems on LWIP for STM32 // The default is "lwip", which is **always** set in STM32Ethernet/src/utility/ethernetif.cpp // for some reason. One can edit it to instead read: // #if LWIP_NETIF_HOSTNAME // /* Initialize interface hostname */ // if (netif->hostname == NULL) // netif->hostname = "lwip"; // #endif /* LWIP_NETIF_HOSTNAME */ // Which seems more useful! We should propose the patch... so the following line actually works! netif_set_hostname(&gnetif, ETHERNET_HOSTNAME); // Should probably be passed in the contructor... #endif byte mac[6]; DCCTimer::getSimulatedMacAddress(mac); #ifdef IP_ADDRESS static IPAddress myIP(IP_ADDRESS); Ethernet.begin(mac,myIP); #else if (Ethernet.begin(mac)==0) { LCD(4,F("IP: No DHCP")); return; } #endif auto ip = Ethernet.localIP(); // look what IP was obtained (dynamic or static) if (!ip) { LCD(4,F("IP: None")); return; } server = new EthernetServer(IP_PORT); // Ethernet Server listening on default port IP_PORT server->begin(); // Arrange display of IP address and port #ifdef LCD_DRIVER const byte lcdData[]={LCD_DRIVER}; const bool wideDisplay=lcdData[1]>=24; // data[1] is cols. #else const bool wideDisplay=true; #endif if (wideDisplay) { // OLEDS or just usb diag is ok on one line. LCD(4,F("IP %d.%d.%d.%d:%d"), ip[0], ip[1], ip[2], ip[3], IP_PORT); } else { // LCDs generally too narrow, so take 2 lines LCD(4,F("IP %d.%d.%d.%d"), ip[0], ip[1], ip[2], ip[3]); LCD(5,F("Port %d"), IP_PORT); } outboundRing=new RingStream(OUTBOUND_RING_SIZE); #ifdef DO_MDNS if (!mdns.begin(Ethernet.localIP(), (char *)ETHERNET_HOSTNAME)) DIAG(F("mdns.begin fail")); // hostname mdns.addServiceRecord(ETHERNET_HOSTNAME "._withrottle", IP_PORT, MDNSServiceTCP); mdns.run(); // run it right away to get out info ASAP #endif connected=true; } #if defined (STM32_ETHERNET) void EthernetInterface::acceptClient() { // STM32 version auto client=server->available(); if (!client) return; // check for existing client for (byte socket = 0; socket < MAX_SOCK_NUM; socket++) if (inUse[socket] && client == clients[socket]) return; // new client for (byte socket = 0; socket < MAX_SOCK_NUM; socket++) { if (!inUse[socket]) { clients[socket] = client; inUse[socket]=true; if (Diag::ETHERNET) DIAG(F("Ethernet: New client socket %d"), socket); return; } } // reached here only if more than MAX_SOCK_NUM clients want to connect DIAG(F("Ethernet more than %d clients, not accepting new connection"), MAX_SOCK_NUM); client.stop(); } #else void EthernetInterface::acceptClient() { // non-STM32 version auto client=server->accept(); if (!client) return; auto socket=client.getSocketNumber(); clients[socket]=client; inUse[socket]=true; if (Diag::ETHERNET) DIAG(F("Ethernet: New client socket %d"), socket); } #endif void EthernetInterface::dropClient(byte socket) { clients[socket].stop(); inUse[socket]=false; CommandDistributor::forget(socket); if (Diag::ETHERNET) DIAG(F("Ethernet: Disconnect %d "), socket); } /** * @brief Main loop for the EthernetInterface * */ void EthernetInterface::loop() { if (!connected) return; looptimer(5000, F("E.loop")); static bool warnedAboutLink=false; if (Ethernet.linkStatus() == LinkOFF){ if (warnedAboutLink) return; DIAG(F("Ethernet link OFF")); warnedAboutLink=true; return; } looptimer(5000, F("E.loop warn")); // link status must be ok here if (warnedAboutLink) { DIAG(F("Ethernet link RESTORED")); warnedAboutLink=false; } #ifdef DO_MDNS // Always do this because we don't want traffic to intefere with being found! mdns.run(); looptimer(5000, F("E.mdns")); #endif // switch (Ethernet.maintain()) { case 1: //renewed fail DIAG(F("Ethernet Error: renewed fail")); connected=false; return; case 3: //rebind fail DIAG(F("Ethernet Error: rebind fail")); connected=false; return; default: //nothing happened //DIAG(F("maintained")); break; } looptimer(5000, F("E.maintain")); // get client from the server acceptClient(); // handle disconnected sockets because STM32 library doesnt // do the read==0 response. for (byte socket = 0; socket < MAX_SOCK_NUM; socket++) { if (inUse[socket] && !clients[socket].connected()) dropClient(socket); } // check for incoming data from all possible clients for (byte socket = 0; socket < MAX_SOCK_NUM; socket++) { if (!inUse[socket]) continue; // socket is not in use // read any bytes from this client auto count = clients[socket].read(buffer, MAX_ETH_BUFFER); if (count<0) continue; // -1 indicates nothing to read if (count > 0) { // we have incoming data buffer[count] = '\0'; // terminate the string properly if (Diag::ETHERNET) DIAG(F("Ethernet s=%d, c=%d b=:%e"), socket, count, buffer); // execute with data going directly back CommandDistributor::parse(socket,buffer,outboundRing); //looptimer(5000, F("Ethloop2 parse")); return; // limit the amount of processing that takes place within 1 loop() cycle. } // count=0 The client has disconnected dropClient(socket); } WiThrottle::loop(outboundRing); // handle at most 1 outbound transmission auto socketOut=outboundRing->read(); if (socketOut<0) return; // no outbound pending if (socketOut >= MAX_SOCK_NUM) { // This is a catastrophic code failure and unrecoverable. DIAG(F("Ethernet outboundRing s=%d error"), socketOut); connected=false; return; } auto count=outboundRing->count(); { char tmpbuf[count+1]; // one extra for '\0' for(int i=0;iread(); } tmpbuf[count]=0; if (inUse[socketOut]) { if (Diag::ETHERNET) DIAG(F("Ethernet reply s=%d, c=%d, b:%e"), socketOut,count,tmpbuf); clients[socketOut].write(tmpbuf,count); } } } #endif ================================================ FILE: EthernetInterface.h ================================================ /* * © 2023-2024 Paul M. Antoine * © 2021 Neil McKechnie * © 2021 Mike S * © 2021 Fred Decker * © 2020-2024 Harald Barth * © 2020-2024 Chris Harlow * © 2020 Gregor Baues * All rights reserved. * * This file is part of DCC-EX/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 . * * Ethernet Interface added by Gregor Baues */ #ifndef EthernetInterface_h #define EthernetInterface_h #include "defines.h" #if ETHERNET_ON == true #include "DCCEXParser.h" #include //#include #if defined (ARDUINO_TEENSY41) #include //TEENSY Ethernet Treiber #include #ifndef MAX_SOCK_NUM #define MAX_SOCK_NUM 4 #endif // can't use our MDNS because of a namespace clash with Teensy's NativeEthernet library! // #define DO_MDNS #elif defined (ARDUINO_NUCLEO_F429ZI) || defined (ARDUINO_NUCLEO_F439ZI) || defined (ARDUINO_NUCLEO_F4X9ZI) #include #include #include extern "C" struct netif gnetif; #define STM32_ETHERNET #define MAX_SOCK_NUM MAX_NUM_TCP_CLIENTS #define DO_MDNS #else #include "Ethernet.h" #define DO_MDNS #endif #include "RingStream.h" /** * @brief Network Configuration * */ #define MAX_ETH_BUFFER 128 #define OUTBOUND_RING_SIZE 2048 class EthernetInterface { public: static void setup(); static void loop(); private: static bool connected; static EthernetServer * server; static EthernetClient clients[MAX_SOCK_NUM]; // accept up to MAX_SOCK_NUM client connections at the same time; This depends on the chipset used on the Shield static bool inUse[MAX_SOCK_NUM]; // accept up to MAX_SOCK_NUM client connections at the same time; This depends on the chipset used on the Shield static uint8_t buffer[MAX_ETH_BUFFER+1]; // buffer used by TCP for the recv static RingStream * outboundRing; static void acceptClient(); static void dropClient(byte socketnum); }; #endif // ETHERNET_ON #endif ================================================ FILE: FSH.h ================================================ /* * © 2022 Paul M. Antoine * © 2021 Neil McKechnie * © 2021 Harald Barth * © 2021 Fred Decker * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef FSH_h #define FSH_h /* This is an architecture support file to manage the differences * between the nano/uno.mega and the later nanoEvery, unoWifiRev2 etc * * IMPORTANT: * To maintain portability the main code should NOT contain ANY references * to the following: * * __FlashStringHelper Use FSH instead. * 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 #ifdef ARDUINO_ARCH_AVR // AVR devices have flash memory mapped differently // progmem can be accessed by _near functions or _far typedef __FlashStringHelper FSH; #define FLASH PROGMEM #define GETFLASH(addr) pgm_read_byte_near(addr) #define STRCPY_P strcpy_P #define STRCMP_P strcmp_P #define STRNCPY_P strncpy_P #define STRNCMP_P strncmp_P #define STRLEN_P strlen_P #define STRCHR_P strchr_P #if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560) // AVR_MEGA memory deliberately placed at end of link may need _far functions #define HIGHFLASH __attribute__((section(".fini2"))) #define HIGHFLASH3 __attribute__((section(".fini3"))) #define GETFARPTR(data) pgm_get_far_address(data) #define GETHIGHFLASH(data,offset) pgm_read_byte_far(GETFARPTR(data)+offset) #define GETHIGHFLASHW(data,offset) pgm_read_word_far(GETFARPTR(data)+offset) #define COPYHIGHFLASH(target,base,offset,length) \ memcpy_PF(target,GETFARPTR(base) + offset,length) #else // AVR_UNO/NANO runtime does not support _far functions so just use _near equivalent // as there is no progmem above 32kb anyway. #define HIGHFLASH PROGMEM #define HIGHFLASH3 PROGMEM #define GETFARPTR(data) ((uint32_t)(data)) #define GETHIGHFLASH(data,offset) pgm_read_byte_near(GETFARPTR(data)+(offset)) #define GETHIGHFLASHW(data,offset) pgm_read_word_near(GETFARPTR(data)+(offset)) #define COPYHIGHFLASH(target,base,offset,length) \ memcpy_P(target,(byte *)base + offset,length) #endif #else // Non-AVR Flat-memory devices have no need of this support so can be remapped to normal memory access #ifdef F #undef F #endif #ifdef FLASH #undef FLASH #endif #define F(str) (str) typedef char FSH; #define FLASH #define HIGHFLASH #define HIGHFLASH3 #define GETFARPTR(data) ((uint32_t)(data)) #define GETFLASH(addr) (*(const byte *)(addr)) #define GETHIGHFLASH(data,offset) (*(const byte *)(GETFARPTR(data)+offset)) #define GETHIGHFLASHW(data,offset) (*(const uint16_t *)(GETFARPTR(data)+offset)) #define COPYHIGHFLASH(target,base,offset,length) \ memcpy(target,(byte *)&base + offset,length) #define STRCPY_P strcpy #define STRCMP_P strcmp #define STRNCPY_P strncpy #define STRNCMP_P strncmp #define STRLEN_P strlen #define STRCHR_P strchr #endif #endif ================================================ FILE: GITHUB_SHA.h ================================================ #define GITHUB_SHA "master-202605011818Z" ================================================ FILE: I2CManager.cpp ================================================ /* * © 2023, Neil McKechnie * © 2022 Paul M Antoine * 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 . */ #include #include "I2CManager.h" #include "DIAG.h" // Include target-specific portions of I2CManager class #if defined(I2C_USE_WIRE) #include "I2CManager_Wire.h" #elif defined(ARDUINO_ARCH_AVR) #include "I2CManager_NonBlocking.h" #include "I2CManager_AVR.h" // Uno/Nano/Mega2560 #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 >= 0x10 && address <= 0x17) return F("EX-SensorCAM"); if (address == 0x1A) // 0x09-0x18 selectable, but for now handle the default return F("Piicodev 865/915MHz Transceiver"); if (address == 0x1C) return F("QMC6310 Magnetometer"); if (address >= 0x20 && address <= 0x26) return F("GPIO Expander"); if (address == 0x27) return F("GPIO Expander or LCD Display"); if (address == 0x29) return F("Time-of-flight sensor"); if (address == 0x34) return F("TCA8418 keypad scanner"); if (address >= 0x3c && address <= 0x3d) // 0x3c can also be an HMC883L magnetometer return F("OLED Display or HMC583L Magnetometer"); if (address >= 0x48 && address <= 0x57) // SC16IS752x UART detection return F("SC16IS75x UART"); if (address >= 0x48 && address <= 0x4f) return F("Analogue Inputs or PWM"); if (address >= 0x40 && address <= 0x4f) return F("PWM"); if (address >= 0x50 && address <= 0x5f) return F("EEPROM"); if (address >= 0x60 && address < 0x68) return F("Adafruit NeoPixel Driver"); if (address == 0x68) return F("Real-time clock"); if (address >= 0x70 && address <= 0x77) return F("I2C Mux"); // Unknown type return F("?"); } // If not already initialised, initialise I2C void I2CManagerClass::begin(void) { 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(); scanForDevices(&USB_SERIAL); } } void I2CManagerClass::scanForDevices(Print* stream) { StringFormatter::send(stream, F("<* Scanning I2C bus for devices...\n")); #if defined(I2C_USE_WIRE) StringFormatter::send(stream,F(" I2CManager: Using Wire library\n")); #endif // Probe and list devices. Use standard mode // (clock speed 100kHz) for best device compatibility. _setClock(100000); uint32_t originalTimeout = _timeout; setTimeout(1000); // use 1ms timeout for probes #if defined(I2C_EXTENDED_ADDRESS) // First count the multiplexers and switch off all subbuses _muxCount = 0; for (uint8_t muxNo=I2CMux_0; muxNo <= I2CMux_7; muxNo++) { if (I2CManager.muxSelectSubBus({(I2CMux)muxNo, SubBus_None})==I2C_STATUS_OK) _muxCount++; } #endif // Enumerate devices that are visible bool found = false; for (uint8_t addr=0x08; addr<0x78; addr++) { if (exists(addr)) { found = true; StringFormatter::send(stream,F(" Device found at 0x%x, %S?\n"), 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; StringFormatter::send(stream,F(" Device found at {I2CMux_%d,SubBus_%d,0x%x}, %S?\n"), 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 StringFormatter::send(stream,found?F("*>\n"):F(" No I2C Devices found\n*>\n")); _setClock(_clockSpeed); setTimeout(originalTimeout); // set timeout back to original } // Set clock speed to the lowest requested one. If none requested, // the Wire default is 100kHz. 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. void I2CManagerClass::forceClock(uint32_t speed) { _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. // 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(I2CAddress address, uint8_t nBytes, ...) { uint8_t buffer[nBytes]; va_list args; va_start(args, nBytes); for (uint8_t i=0; iwait(); return status; } /*************************************************************************** * Get a message corresponding to the error status ***************************************************************************/ const FSH *I2CManagerClass::getErrorMessage(uint8_t status) { switch (status) { case I2C_STATUS_OK: return F("OK"); case I2C_STATUS_TRUNCATED: return F("Transmission truncated"); 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("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"); case I2C_STATUS_PENDING: return F("Request pending"); default: return F("Error code not recognised"); } } /*************************************************************************** * Declare singleton class instance. ***************************************************************************/ 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 to complete, and return completion status. * Timeout monitoring is performed in the I2CManager.loop() function. ***************************************************************************/ uint8_t I2CRB::wait() { while (status==I2C_STATUS_PENDING) { I2CManager.loop(); }; return status; } /*************************************************************************** * Check whether request is still in progress. * Timeout monitoring is performed in the I2CManager.loop() function. ***************************************************************************/ bool I2CRB::isBusy() { if (status==I2C_STATUS_PENDING) { I2CManager.loop(); return true; } else return false; } /*************************************************************************** * Helper functions to fill the I2CRequest structure with parameters. ***************************************************************************/ void I2CRB::setReadParams(I2CAddress i2cAddress, uint8_t *readBuffer, uint8_t readLen) { this->i2cAddress = i2cAddress; this->writeLen = 0; this->readBuffer = readBuffer; this->readLen = readLen; this->operation = OPERATION_READ; this->status = I2C_STATUS_OK; } void I2CRB::setRequestParams(I2CAddress i2cAddress, uint8_t *readBuffer, uint8_t readLen, const uint8_t *writeBuffer, uint8_t writeLen) { this->i2cAddress = i2cAddress; this->writeBuffer = writeBuffer; this->writeLen = writeLen; this->readBuffer = readBuffer; this->readLen = readLen; this->operation = OPERATION_REQUEST; this->status = I2C_STATUS_OK; } void I2CRB::setWriteParams(I2CAddress i2cAddress, const uint8_t *writeBuffer, uint8_t writeLen) { this->i2cAddress = i2cAddress; this->writeBuffer = writeBuffer; this->writeLen = writeLen; this->readLen = 0; this->operation = OPERATION_SEND; 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 ================================================ FILE: I2CManager.h ================================================ /* * © 2023, Neil McKechnie. All rights reserved. * © 2022 Paul M Antoine * * 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 . */ #ifndef I2CMANAGER_H #define I2CMANAGER_H #include #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 * entirely benign as it reinitialises). * * Also helps to avoid the Wire clock from being set, by another device * driver, to a speed which is higher than a device supports. * * Thirdly, it provides a convenient way to check whether there is a * device on a particular I2C address. * * Non-blocking requests are issued by creating an I2C Request Block * (I2CRB) which is then added to the I2C manager's queue. The * application refers to this block to check for completion of the * operation, and for reading completion status. * * Examples: * I2CRB rb; * uint8_t status = I2CManager.write(address, buffer, sizeof(buffer), &rb); * ... * if (!rb.isBusy()) { * status = rb.status; * // Repeat write * I2CManager.queueRequest(&rb); * ... * status = rb.wait(); // Wait for completion and read status * } * ... * I2CRB rb2; * outbuffer[0] = 12; // Register number in I2C device to be read * rb2.setRequestParams(address, inBuffer, 1, outBuffer, 1); * status = I2CManager.queueRequest(&rb2); * if (status == I2C_STATUS_OK) { * status = rb2.wait(); * if (status == I2C_STATUS_OK) { * registerValue = inBuffer[0]; * } * } * ... * * Synchronous (blocking) calls are also possible, e.g. * status = I2CManager.write(address, buffer, sizeof(buffer)); * * When using non-blocking requests, neither the I2CRB nor the input or output * buffers should be modified until the I2CRB is complete (not busy). * * 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. * */ /* * 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 * to are limited to 8 on a bus. By adding a multiplexer, the limit becomes 8 for each of the multiplexer's 8 sub-buses, i.e. 64. * And a single I2C bus can have up to 8 multiplexers, giving up to 64 sub-buses and, in theory, up to 512 I/O extenders; that's * as many as 8192 input/output pins! * Secondly, the capacitance of the bus is an electrical limiting factor of the length of the bus, speed and number of devices. * The multiplexer isolates each sub-bus from the others, and so reduces the capacitance of the bus. For example, with one * multiplexer and 64 GPIO extenders, only 9 devices are connected to the bus at any time (multiplexer plus 8 extenders). * 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. * * * Non-interrupting I2C: * * 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. * */ // 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 I2C_STATUS_OK=0, I2C_STATUS_TRUNCATED=1, I2C_STATUS_NEGATIVE_ACKNOWLEDGE=2, I2C_STATUS_TRANSMIT_ERROR=3, I2C_STATUS_TIMEOUT=5, // Code used by Wire only I2C_STATUS_OTHER_TWI_ERROR=4, // catch-all error // Codes used by native drivers only I2C_STATUS_ARBITRATION_LOST=6, I2C_STATUS_BUS_ERROR=7, I2C_STATUS_UNEXPECTED_ERROR=8, I2C_STATUS_PENDING=253, }; // Status codes for the state machine (not returned to caller). enum : uint8_t { I2C_STATE_ACTIVE=253, I2C_STATE_FREE=254, I2C_STATE_CLOSING=255, I2C_STATE_COMPLETED=252, }; typedef enum : uint8_t { OPERATION_READ = 1, 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; // Default I2C frequency #ifndef I2C_FREQ #define I2C_FREQ 400000L #endif // Class defining a request context for an I2C operation. class I2CRB { public: volatile uint8_t status; // Completion status, or pending flag (updated from IRC) volatile uint8_t nBytes; // Number of bytes read (updated from IRC) inline I2CRB() { status = I2C_STATUS_OK; }; uint8_t wait(); bool isBusy(); 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; I2CAddress i2cAddress; uint8_t *readBuffer; const uint8_t *writeBuffer; #if !defined(I2C_USE_WIRE) I2CRB *nextRequest; // Used by non-blocking devices for I2CRB queue management. #endif }; // I2C Manager class I2CManagerClass { public: // If not already initialised, initialise I2C (wire). void begin(void); // Set clock speed to the lowest requested one. 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(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(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(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(I2CAddress address, uint8_t nBytes, ...); // Write a command from an array in RAM and read response uint8_t read(I2CAddress address, uint8_t readBuffer[], uint8_t readSize, const uint8_t writeBuffer[]=NULL, uint8_t writeSize=0); 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(I2CAddress address, uint8_t readBuffer[], uint8_t readSize, uint8_t writeSize, ...); void queueRequest(I2CRB *req); // Function to abort long-running operations. void checkForTimeout(); // Loop method void loop(); // Expand error codes into text. Note that they are in flash so // need to be printed using FSH. static const FSH *getErrorMessage(uint8_t status); void scanForDevices(Print * stream); private: bool _beginCompleted = false; bool _clockSpeedFixed = false; uint8_t retryCounter; // Count of retries // Clock speed must be no higher than 400kHz on AVR. Higher is possible on 4809, SAMD // and STM32 but most popular I2C devices are 400kHz so in practice the higher speeds // will not be useful. The speed can be overridden by I2CManager::forceClock(). uint32_t _clockSpeed = I2C_FREQ; // Default timeout 100ms on I2C request block completion. // A full 32-byte transmission takes about 8ms at 100kHz, // so this value allows lots of headroom. // It can be modified by calling I2CManager.setTimeout() function. // When retries are enabled, the timeout applies to each // try, and failure from timeout does not get retried. // A value of 0 means disable timeout monitoring. uint32_t _timeout = 100000UL; // Finish off request block by waiting for completion and posting status. uint8_t finishRB(I2CRB *rb, uint8_t status); void _initialise(); void _setClock(unsigned long); #if defined(I2C_EXTENDED_ADDRESS) // Count of I2C multiplexers found when initialising. If there is only one // MUX then the subbus does not need de-selecting after use; however, if there // are two or more, then the subbus must be deselected to avoid multiple // sub-bus legs on different multiplexers being accessible simultaneously. private: uint8_t _muxCount = 0; public: uint8_t getMuxCount() { return _muxCount; } #endif #if !defined(I2C_USE_WIRE) // I2CRB structs are queued on the following two links. // If there are no requests, both are NULL. // If there is only one request, then queueHead and queueTail both point to it. // Otherwise, queueHead is the pointer to the first request in the queue and // queueTail is the pointer to the last request in the queue. // 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. private: I2CRB * volatile queueHead = NULL; I2CRB * volatile queueTail = NULL; // State is set to I2C_STATE_FREE when the interrupt handler has finished // the current request and is ready to complete. uint8_t state = I2C_STATE_FREE; // CompletionStatus may be set by the interrupt handler at any time but is // not written to the I2CRB until the state is I2C_STATE_FREE. uint8_t completionStatus = I2C_STATUS_OK; uint8_t overallStatus = I2C_STATUS_OK; I2CRB * currentRequest = NULL; uint8_t txCount = 0; uint8_t rxCount = 0; uint8_t bytesToSend = 0; uint8_t bytesToReceive = 0; uint8_t operation = 0; uint32_t startTime = 0; uint8_t muxPhase = 0; uint8_t muxAddress = 0; uint8_t muxData[1]; uint8_t deviceAddress; const uint8_t *sendBuffer; uint8_t *receiveBuffer; uint8_t transactionState = 0; volatile uint32_t pendingClockSpeed = 0; void startTransaction(); // Low-level hardware manipulation functions. void I2C_init(); void I2C_setClock(unsigned long i2cClockSpeed); void I2C_handleInterrupt(); void I2C_sendStart(); void I2C_sendStop(); void I2C_close(); public: // handleInterrupt needs to be public to be called from the ISR function! 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 ================================================ FILE: I2CManager_AVR.h ================================================ /* * © 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 . */ #ifndef I2CMANAGER_AVR_H #define I2CMANAGER_AVR_H #include #include "I2CManager.h" #include "I2CManager_NonBlocking.h" // to satisfy intellisense #include #include /**************************************************************************** TWI State codes ****************************************************************************/ // General TWI Master staus codes #define TWI_START 0x08 // START has been transmitted #define TWI_REP_START 0x10 // Repeated START has been transmitted #define TWI_ARB_LOST 0x38 // Arbitration lost // TWI Master Transmitter staus codes #define TWI_MTX_ADR_ACK 0x18 // SLA+W has been tramsmitted and ACK received #define TWI_MTX_ADR_NACK 0x20 // SLA+W has been tramsmitted and NACK received #define TWI_MTX_DATA_ACK 0x28 // Data byte has been tramsmitted and ACK received #define TWI_MTX_DATA_NACK 0x30 // Data byte has been tramsmitted and NACK received // TWI Master Receiver staus codes #define TWI_MRX_ADR_ACK 0x40 // SLA+R has been tramsmitted and ACK received #define TWI_MRX_ADR_NACK 0x48 // SLA+R has been tramsmitted and NACK received #define TWI_MRX_DATA_ACK 0x50 // Data byte has been received and ACK tramsmitted #define TWI_MRX_DATA_NACK 0x58 // Data byte has been received and NACK tramsmitted // TWI Miscellaneous status codes #define TWI_NO_STATE 0xF8 // No relevant state information available #define TWI_BUS_ERROR 0x00 // Bus error due to an illegal START or STOP condition #define TWI_TWBR ((F_CPU / I2C_FREQ) - 16) / 2 // TWI Bit rate Register setting. #if defined(I2C_USE_INTERRUPTS) #define ENABLE_TWI_INTERRUPT (1< 0) { receiveBuffer[rxCount++] = TWDR; bytesToReceive--; } /* fallthrough */ case TWI_MRX_ADR_ACK: // SLA+R has been sent and ACK received if (bytesToReceive <= 1) { TWCR = (1< 0) { receiveBuffer[rxCount++] = TWDR; bytesToReceive--; } TWCR = (1<. */ #ifndef I2CMANAGER_MEGA4809_H #define I2CMANAGER_MEGA4809_H #include #include "I2CManager.h" /*************************************************************************** * Set I2C clock speed register. ***************************************************************************/ void I2CManagerClass::I2C_setClock(unsigned long i2cClockSpeed) { uint16_t t_rise; if (i2cClockSpeed < 200000) t_rise = 1000; else if (i2cClockSpeed < 800000) t_rise = 300; else t_rise = 120; 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; } /*************************************************************************** * Initialise I2C registers. ***************************************************************************/ 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 TWI0.MSTATUS = TWI_BUSSTATE_IDLE_gc; } /*************************************************************************** * Initiate a start bit for transmission, followed by address and R/W ***************************************************************************/ void I2CManagerClass::I2C_sendStart() { txCount = 0; rxCount = 0; // If anything to send, initiate write. Otherwise initiate read. if (operation == OPERATION_READ || ((operation == OPERATION_REQUEST) && !bytesToSend)) TWI0.MADDR = (currentRequest->i2cAddress << 1) | 1; else TWI0.MADDR = (currentRequest->i2cAddress << 1) | 0; } /*************************************************************************** * Initiate a stop bit for transmission. ***************************************************************************/ void I2CManagerClass::I2C_sendStop() { TWI0.MCTRLB = TWI_MCMD_STOP_gc; } /*************************************************************************** * Close I2C down ***************************************************************************/ void I2CManagerClass::I2C_close() { 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) } /*************************************************************************** * Main state machine for I2C, called from interrupt handler. ***************************************************************************/ void I2CManagerClass::I2C_handleInterrupt() { uint8_t currentStatus = TWI0.MSTATUS; if (currentStatus & TWI_ARBLOST_bm) { // Arbitration lost, restart TWI0.MSTATUS = currentStatus; // clear all flags I2C_sendStart(); // Reinitiate request } else if (currentStatus & TWI_BUSERR_bm) { // 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; completionStatus = I2C_STATUS_NEGATIVE_ACKNOWLEDGE; state = I2C_STATE_COMPLETED; } else if (bytesToSend) { // 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 = (deviceAddress << 1) | 1; } else { // No more data to send/receive. Initiate a STOP condition. TWI0.MCTRLB = TWI_MCMD_STOP_gc; state = I2C_STATE_COMPLETED; } } else if (currentStatus & TWI_RIF_bm) { // Master read completed without errors if (bytesToReceive) { receiveBuffer[rxCount++] = TWI0.MDATA; // Store received byte bytesToReceive--; } 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_STATE_COMPLETED; } } } /*************************************************************************** * Interrupt handler. ***************************************************************************/ ISR(TWI0_TWIM_vect) { I2CManager.handleInterrupt(); } #endif ================================================ FILE: I2CManager_NonBlocking.h ================================================ /* * © 2023, Neil McKechnie * © 2022 Paul M Antoine * 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 . */ #ifndef I2CMANAGER_NONBLOCKING_H #define I2CMANAGER_NONBLOCKING_H #include #include "I2CManager.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) { #if defined(ARDUINO_ARCH_STM32) NVIC_DisableIRQ(I2C1_EV_IRQn); NVIC_DisableIRQ(I2C1_ER_IRQn); #else noInterrupts(); #endif return 1; } static inline void _conditionalEnableInterrupts(bool *wasEnabled) { #if defined(ARDUINO_ARCH_STM32) (void)wasEnabled; NVIC_EnableIRQ(I2C1_EV_IRQn); NVIC_EnableIRQ(I2C1_ER_IRQn); #else if (*wasEnabled) interrupts(); #endif } #define ATOMIC_BLOCK(x) \ for (bool _int_saved __attribute__((__cleanup__(_conditionalEnableInterrupts))) \ =_getInterruptState(),_ToDo=_deferInterrupts(); _ToDo; _ToDo=0) // The construct of // "variable __attribute__((__cleanup__(func)))" // calls the func with *variable when variable goes out of scope #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(ARDUINO_ARCH_STM32) static inline bool _getInterruptState( void ) { // as we do ony mess with the I2C interrupts in the STM32 case, // we do not care about their previous state return true; } #elif defined(__arm__) // 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 #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. ***************************************************************************/ 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) { pendingClockSpeed = i2cClockSpeed; } /*************************************************************************** * 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() { 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; // 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(); } } } /*************************************************************************** * Function to queue a request block and initiate operations. ***************************************************************************/ void I2CManagerClass::queueRequest(I2CRB *req) { if (((req->operation & OPERATION_MASK) == OPERATION_READ) && req->readLen == 0) return; // Ignore null read req->status = I2C_STATUS_PENDING; req->nextRequest = NULL; ATOMIC_BLOCK() { if (!queueTail) queueHead = queueTail = req; // Only item on queue else queueTail = queueTail->nextRequest = req; // Add to end startTransaction(); } } /*************************************************************************** * Initiate a write to an I2C device (non-blocking operation) ***************************************************************************/ 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); queueRequest(req); return I2C_STATUS_OK; } /*************************************************************************** * Initiate a write from PROGMEM (flash) to an I2C device (non-blocking operation) ***************************************************************************/ 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); req->operation = OPERATION_SEND_P; queueRequest(req); return I2C_STATUS_OK; } /*************************************************************************** * Initiate a read from the I2C device, optionally preceded by a write * (non-blocking operation) ***************************************************************************/ 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. req->wait(); req->setRequestParams(i2cAddress, readBuffer, readLen, writeBuffer, writeLen); queueRequest(req); 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. Such faults * may be caused by an I2C wire short for example. ***************************************************************************/ void I2CManagerClass::checkForTimeout() { ATOMIC_BLOCK() { I2CRB *t = queueHead; if (state==I2C_STATE_ACTIVE && t!=0 && t==currentRequest && _timeout > 0) { // Check for timeout int32_t elapsed = micros() - startTime; if (elapsed > (int32_t)_timeout) { #ifdef DIAG_IO //DIAG(F("I2CManager Timeout on %s"), t->i2cAddress.toString()); #endif // Excessive time. Dequeue request queueHead = t->nextRequest; if (!queueHead) queueTail = NULL; currentRequest = NULL; bytesToReceive = bytesToSend = 0; // Post request as timed out. t->status = I2C_STATUS_TIMEOUT; // Reset TWI interface so it is able to continue // Try close and init, not entirely satisfactory but sort of works... I2C_close(); // Shutdown and restart twi interface // If SDA is stuck low, issue up to 9 clock pulses to attempt to free it. pinMode(SCL, INPUT_PULLUP); pinMode(SDA, INPUT_PULLUP); for (int i=0; !digitalRead(SDA) && i<9; i++) { digitalWrite(SCL, 0); pinMode(SCL, OUTPUT); // Force clock low delayMicroseconds(10); // ... for 5us pinMode(SCL, INPUT_PULLUP); // ... then high delayMicroseconds(10); // ... for 5us (100kHz Clock) } // Whether that's succeeded or not, now try reinitialising. I2C_init(); _setClock(_clockSpeed); state = I2C_STATE_FREE; // Initiate next queued request if any. startTransaction(); } } } } /*************************************************************************** * Loop function, for general background work ***************************************************************************/ void I2CManagerClass::loop() { #if !defined(I2C_USE_INTERRUPTS) handleInterrupt(); #endif // Call function to monitor for stuck I2C operations. checkForTimeout(); } /*************************************************************************** * Interupt handler. Call I2C state machine, and dequeue request * if completed. ***************************************************************************/ void I2CManagerClass::handleInterrupt() { // Update hardware state machine I2C_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_COMPLETED && currentRequest != NULL && currentRequest == queueHead) { // Operation has completed. if (completionStatus == I2C_STATUS_OK || ++retryCounter > MAX_I2C_RETRIES || currentRequest->operation & OPERATION_NORETRY) { // Status is OK, or has failed and retry count exceeded, or failed and retries disabled. #if defined(I2C_EXTENDED_ADDRESS) if (muxPhase == MuxPhase_PROLOG ) { overallStatus = completionStatus; uint8_t rbAddress = currentRequest->i2cAddress.deviceAddress(); if (completionStatus == I2C_STATUS_OK && rbAddress != 0) { // Mux request OK, start handling application request. muxPhase = MuxPhase_PAYLOAD; deviceAddress = rbAddress; sendBuffer = currentRequest->writeBuffer; bytesToSend = currentRequest->writeLen; receiveBuffer = currentRequest->readBuffer; bytesToReceive = currentRequest->readLen; operation = currentRequest->operation & OPERATION_MASK; state = I2C_STATE_ACTIVE; I2C_sendStart(); return; } } else if (muxPhase == MuxPhase_PAYLOAD) { // Application request completed, now send epilogue to mux overallStatus = completionStatus; currentRequest->nBytes = rxCount; // Save number of bytes read into rb if (_muxCount == 1) { // Only one MUX, don't need to deselect subbus muxPhase = MuxPhase_OFF; } else { muxPhase = MuxPhase_EPILOG; deviceAddress = I2C_MUX_BASE_ADDRESS + currentRequest->i2cAddress.muxNumber(); muxData[0] = 0x00; sendBuffer = &muxData[0]; bytesToSend = 1; bytesToReceive = 0; operation = OPERATION_SEND; state = I2C_STATE_ACTIVE; I2C_sendStart(); return; } } else if (muxPhase == MuxPhase_EPILOG) { // Epilog finished, ignore completionStatus muxPhase = MuxPhase_OFF; } else overallStatus = completionStatus; #else overallStatus = completionStatus; currentRequest->nBytes = rxCount; #endif // Remove completed request from head of queue I2CRB * t = queueHead; if (t == currentRequest) { queueHead = t->nextRequest; if (!queueHead) queueTail = queueHead; t->status = overallStatus; // I2C state machine is now free for next request currentRequest = NULL; state = I2C_STATE_FREE; } 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(); } } #endif ================================================ FILE: I2CManager_SAMD.h ================================================ /* * © 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 . */ #ifndef I2CMANAGER_SAMD_H #define I2CMANAGER_SAMD_H #include #include "I2CManager.h" //#include //#include #include /*************************************************************************** * 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 */ ================================================ FILE: I2CManager_STM32.h ================================================ /* * © 2022-24 Paul M Antoine * © 2023, Neil McKechnie * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef I2CMANAGER_STM32_H #define I2CMANAGER_STM32_H #include #include "I2CManager.h" #include "I2CManager_NonBlocking.h" // to satisfy intellisense #include #include "stm32f4xx_hal_rcc.h" /***************************************************************************** * STM32F4xx I2C native driver support * * Nucleo-64 and Nucleo-144 boards all use I2C1 as the default I2C peripheral * Later we may wish to support other STM32 boards, allow use of an alternate * I2C bus, or more than one I2C bus on the STM32 architecture *****************************************************************************/ #if defined(I2C_USE_INTERRUPTS) && defined(ARDUINO_ARCH_STM32) #if defined(ARDUINO_NUCLEO_F401RE) || defined(ARDUINO_NUCLEO_F411RE) || defined(ARDUINO_NUCLEO_F446RE) \ || defined(ARDUINO_NUCLEO_F412ZG) || defined(ARDUINO_NUCLEO_F413ZH) || defined(ARDUINO_NUCLEO_F446ZE) \ || defined(ARDUINO_NUCLEO_F429ZI) || defined(ARDUINO_NUCLEO_F439ZI) || defined(ARDUINO_NUCLEO_F4X9ZI) // Assume I2C1 for now - default I2C bus on Nucleo-F411RE and likely all Nucleo-64 // and Nucleo-144 variants I2C_TypeDef *s = I2C1; // In init we will ask the STM32 HAL layer for the configured APB1 clock frequency in Hz uint32_t APB1clk1; // Peripheral Input Clock speed in Hz. uint32_t i2c_MHz; // Peripheral Input Clock speed in MHz. // IRQ handler for I2C1, replacing the weak definition in the STM32 HAL extern "C" void I2C1_EV_IRQHandler(void) { I2CManager.handleInterrupt(); } extern "C" void I2C1_ER_IRQHandler(void) { I2CManager.handleInterrupt(); } #else #warning STM32 board selected is not yet supported - so I2C1 peripheral is not defined #endif #endif // Peripheral Input Clock speed in MHz. // For STM32F446RE, the speed is 45MHz. Ideally, this should be determined // at run-time from the APB1 clock, as it can vary from STM32 family to family. // #define I2C_PERIPH_CLK 45 // I2C SR1 Status Register #1 bit definitions for convenience // #define I2C_SR1_SMBALERT (1<<15) // SMBus alert // #define I2C_SR1_TIMEOUT (1<<14) // Timeout of Tlow error // #define I2C_SR1_PECERR (1<<12) // PEC error in reception // #define I2C_SR1_OVR (1<<11) // Overrun/Underrun error // #define I2C_SR1_AF (1<<10) // Acknowledge failure // #define I2C_SR1_ARLO (1<<9) // Arbitration lost (master mode) // #define I2C_SR1_BERR (1<<8) // Bus error (misplaced start or stop condition) // #define I2C_SR1_TxE (1<<7) // Data register empty on transmit // #define I2C_SR1_RxNE (1<<6) // Data register not empty on receive // #define I2C_SR1_STOPF (1<<4) // Stop detection (slave mode) // #define I2C_SR1_ADD10 (1<<3) // 10 bit header sent // #define I2C_SR1_BTF (1<<2) // Byte transfer finished - data transfer done // #define I2C_SR1_ADDR (1<<1) // Address sent (master) or matched (slave) // #define I2C_SR1_SB (1<<0) // Start bit (master mode) 1=start condition generated // I2C CR1 Control Register #1 bit definitions for convenience // #define I2C_CR1_SWRST (1<<15) // Software reset - places peripheral under reset // #define I2C_CR1_ALERT (1<<13) // SMBus alert assertion // #define I2C_CR1_PEC (1<<12) // Packet Error Checking transfer in progress // #define I2C_CR1_POS (1<<11) // Acknowledge/PEC Postion (for data reception in PEC mode) // #define I2C_CR1_ACK (1<<10) // Acknowledge enable - ACK returned after byte is received (address or data) // #define I2C_CR1_STOP (1<<9) // STOP generated // #define I2C_CR1_START (1<<8) // START generated // #define I2C_CR1_NOSTRETCH (1<<7) // Clock stretching disable (slave mode) // #define I2C_CR1_ENGC (1<<6) // General call (broadcast) enable (address 00h is ACKed) // #define I2C_CR1_ENPEC (1<<5) // PEC Enable // #define I2C_CR1_ENARP (1<<4) // ARP enable (SMBus) // #define I2C_CR1_SMBTYPE (1<<3) // SMBus type, 1=host, 0=device // #define I2C_CR1_SMBUS (1<<1) // SMBus mode, 1=SMBus, 0=I2C // #define I2C_CR1_PE (1<<0) // I2C Peripheral enable // States of the STM32 I2C driver state machine enum {TS_IDLE,TS_START,TS_W_ADDR,TS_W_DATA,TS_W_STOP,TS_R_ADDR,TS_R_DATA,TS_R_STOP}; /*************************************************************************** * Set I2C clock speed register. This should only be called outside of * a transmission. The I2CManagerClass::_setClock() function ensures * that it is only called at the beginning of an I2C transaction. ***************************************************************************/ void I2CManagerClass::I2C_setClock(uint32_t i2cClockSpeed) { // Calculate a rise time appropriate to the requested bus speed // Use 10x the rise time spec to enable integer divide of 50ns clock period uint16_t t_rise; while (s->CR1 & I2C_CR1_STOP); // Prevents lockup by guarding further // writes to CR1 while STOP is being executed! // Disable the I2C device, as TRISE can only be programmed whilst disabled s->CR1 &= ~(I2C_CR1_PE); // Disable I2C s->CR1 |= I2C_CR1_SWRST; // reset the I2C asm("nop"); // wait a bit... suggestion from online! s->CR1 &= ~(I2C_CR1_SWRST); // Normal operation if (i2cClockSpeed > 100000UL) { // if (i2cClockSpeed > 400000L) // i2cClockSpeed = 400000L; t_rise = 300; // nanoseconds } else { // i2cClockSpeed = 100000L; t_rise = 1000; // nanoseconds } // Configure the rise time register - max allowed tRISE is 1000ns, // so value = 1000ns * I2C_PERIPH_CLK MHz / 1000 + 1. s->TRISE = (t_rise * i2c_MHz / 1000) + 1; // Bit 15: I2C Master mode, 0=standard, 1=Fast Mode // Bit 14: Duty, fast mode duty cycle (use 2:1) // Bit 11-0: FREQR // if (i2cClockSpeed > 400000UL) { // // In fast mode plus, I2C period is 3 * CCR * TPCLK1. // // s->CCR &= ~(0x3000); // Clear all bits except 12 and 13 which must remain per reset value // s->CCR = APB1clk1 / 3 / i2cClockSpeed; // Set I2C clockspeed to start! // s->CCR |= 0xC000; // We need Fast Mode AND DUTY bits set // } else { // In standard and fast mode, I2C period is 2 * CCR * TPCLK1 s->CCR &= ~(0x3000); // Clear all bits except 12 and 13 which must remain per reset value s->CCR |= (APB1clk1 / 2 / i2cClockSpeed); // Set I2C clockspeed to start! // s->CCR |= (i2c_MHz * 500 / (i2cClockSpeed / 1000)); // Set I2C clockspeed to start! // if (i2cClockSpeed > 100000UL) // s->CCR |= 0xC000; // We need Fast Mode bits set as well // } // DIAG(F("I2C_init() peripheral clock is now: %d, full reg is %x"), (s->CR2 & 0xFF), s->CR2); // DIAG(F("I2C_init() peripheral CCR is now: %d"), s->CCR); // DIAG(F("I2C_init() peripheral TRISE is now: %d"), s->TRISE); // Enable the I2C master mode s->CR1 |= I2C_CR1_PE; // Enable I2C } /*************************************************************************** * Initialise I2C registers. ***************************************************************************/ void I2CManagerClass::I2C_init() { // Query the clockspeed from the STM32 HAL layer APB1clk1 = HAL_RCC_GetPCLK1Freq(); i2c_MHz = APB1clk1 / 1000000UL; // DIAG(F("I2C_init() peripheral clock speed is: %d"), i2c_MHz); // Enable clocks RCC->APB1ENR |= RCC_APB1ENR_I2C1EN;//(1 << 21); // Enable I2C CLOCK // Reset the I2C1 peripheral to initial state RCC->APB1RSTR |= RCC_APB1RSTR_I2C1RST; RCC->APB1RSTR &= ~RCC_APB1RSTR_I2C1RST; // Standard I2C pins are SCL on PB8 and SDA on PB9 RCC->AHB1ENR |= (1<<1); // Enable GPIOB CLOCK for PB8/PB9 // Bits (17:16)= 1:0 --> Alternate Function for Pin PB8; // Bits (19:18)= 1:0 --> Alternate Function for Pin PB9 GPIOB->MODER &= ~((3<<(8*2)) | (3<<(9*2))); // Clear all MODER bits for PB8 and PB9 GPIOB->MODER |= (2<<(8*2)) | (2<<(9*2)); // PB8 and PB9 set to ALT function GPIOB->OTYPER |= (1<<8) | (1<<9); // PB8 and PB9 set to open drain output capability GPIOB->OSPEEDR |= (3<<(8*2)) | (3<<(9*2)); // PB8 and PB9 set to High Speed mode GPIOB->PUPDR &= ~((3<<(8*2)) | (3<<(9*2))); // Clear all PUPDR bits for PB8 and PB9 // GPIOB->PUPDR |= (1<<(8*2)) | (1<<(9*2)); // PB8 and PB9 set to pull-up capability // Alt Function High register routing pins PB8 and PB9 for I2C1: // Bits (3:2:1:0) = 0:1:0:0 --> AF4 for pin PB8 // Bits (7:6:5:4) = 0:1:0:0 --> AF4 for pin PB9 GPIOB->AFR[1] &= ~((15<<0) | (15<<4)); // Clear all AFR bits for PB8 on low nibble, PB9 on next nibble up GPIOB->AFR[1] |= (4<<0) | (4<<4); // PB8 on low nibble, PB9 on next nibble up // Software reset the I2C peripheral I2C1->CR1 &= ~I2C_CR1_PE; // Disable I2C1 peripheral s->CR1 |= I2C_CR1_SWRST; // reset the I2C asm("nop"); // wait a bit... suggestion from online! s->CR1 &= ~(I2C_CR1_SWRST); // Normal operation // Clear all bits in I2C CR2 register except reserved bits s->CR2 &= 0xE000; // Set I2C peripheral clock frequency // s->CR2 |= I2C_PERIPH_CLK; s->CR2 |= i2c_MHz; // DIAG(F("I2C_init() peripheral clock is now: %d"), s->CR2); // set own address to 00 - not used in master mode I2C1->OAR1 = (1 << 14); // bit 14 should be kept at 1 according to the datasheet #if defined(I2C_USE_INTERRUPTS) // Setting NVIC NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4); // 4 means that we have all bits for preemptive grouping // prio scheme: // systick : 0 // waveform timer : 1 // i2c : 2 // one must call NVIC_EncodePriority() to bitshift the priorities // according to the active priority grouping and then use that // value as argument to NVIC_SetPriority(). NVIC_SetPriority(I2C1_EV_IRQn, NVIC_EncodePriority(NVIC_GetPriorityGrouping(), 2, 0)); NVIC_EnableIRQ(I2C1_EV_IRQn); NVIC_SetPriority(I2C1_ER_IRQn, NVIC_EncodePriority(NVIC_GetPriorityGrouping(), 2, 0)); NVIC_EnableIRQ(I2C1_ER_IRQn); // CR2 Interrupt Settings // Bit 15-13: reserved // Bit 12: LAST - DMA last transfer // Bit 11: DMAEN - DMA enable // Bit 10: ITBUFEN - Buffer interrupt enable // Bit 9: ITEVTEN - Event interrupt enable // Bit 8: ITERREN - Error interrupt enable // Bit 7-6: reserved // Bit 5-0: FREQ - Peripheral clock frequency (max 50MHz) s->CR2 |= (I2C_CR2_ITBUFEN | I2C_CR2_ITEVTEN | I2C_CR2_ITERREN); // Enable Buffer, Event and Error interrupts #endif // DIAG(F("I2C_init() setting initial I2C clock to 100KHz")); // Calculate baudrate and set default rate for now // Configure the Clock Control Register for 100KHz SCL frequency // Bit 15: I2C Master mode, 0=standard, 1=Fast Mode // Bit 14: Duty, fast mode duty cycle // Bit 11-0: so CCR divisor would be clk / 2 / 100000 (where clk is in Hz) // s->CCR = I2C_PERIPH_CLK * 5; s->CCR &= ~(0x3000); // Clear all bits except 12 and 13 which must remain per reset value s->CCR |= (APB1clk1 / 2 / 100000UL); // Set a default of 100KHz I2C clockspeed to start! // Configure the rise time register - max allowed is 1000ns, so value = 1000ns * I2C_PERIPH_CLK MHz / 1000 + 1. s->TRISE = (1000 * i2c_MHz / 1000) + 1; // DIAG(F("I2C_init() peripheral clock is now: %d, full reg is %x"), (s->CR2 & 0xFF), s->CR2); // DIAG(F("I2C_init() peripheral CCR is now: %d"), s->CCR); // DIAG(F("I2C_init() peripheral TRISE is now: %d"), s->TRISE); // Enable the I2C master mode s->CR1 |= I2C_CR1_PE; // Enable I2C } /*************************************************************************** * Initiate a start bit for transmission. ***************************************************************************/ void I2CManagerClass::I2C_sendStart() { // Set counters here in case this is a retry. rxCount = txCount = 0; // On a single-master I2C bus, the start bit won't be sent until the bus // state goes to IDLE so we can request it without waiting. On a // multi-master bus, the bus may be BUSY under control of another master, // in which case we can avoid some arbitration failures by waiting until // the bus state is IDLE. We don't do that here. //while (s->SR2 & I2C_SR2_BUSY) {} // Check there's no STOP still in progress. If we OR the START bit into CR1 // and the STOP bit is already set, we could output multiple STOP conditions. while (s->CR1 & I2C_CR1_STOP) {} // Wait for STOP bit to reset s->CR2 |= (I2C_CR2_ITEVTEN | I2C_CR2_ITERREN); // Enable interrupts s->CR2 &= ~I2C_CR2_ITBUFEN; // Don't enable buffer interupts yet. s->CR1 &= ~I2C_CR1_POS; // Clear the POS bit s->CR1 |= (I2C_CR1_ACK | I2C_CR1_START); // Enable the ACK and generate START transactionState = TS_START; } /*************************************************************************** * Initiate a stop bit for transmission (does not interrupt) ***************************************************************************/ void I2CManagerClass::I2C_sendStop() { s->CR1 |= I2C_CR1_STOP; // Stop I2C } /*************************************************************************** * Close I2C down ***************************************************************************/ void I2CManagerClass::I2C_close() { I2C_sendStop(); // Disable the I2C master mode and wait for sync s->CR1 &= ~I2C_CR1_PE; // Disable I2C peripheral // Should never happen, but wait for up to 500us only. unsigned long startTime = micros(); while ((s->CR1 & I2C_CR1_PE) != 0) { if ((int32_t)(micros() - startTime) >= 500) break; } NVIC_DisableIRQ(I2C1_EV_IRQn); NVIC_DisableIRQ(I2C1_ER_IRQn); } /*************************************************************************** * Main state machine for I2C, called from interrupt handler or, * if I2C_USE_INTERRUPTS isn't defined, from the I2CManagerClass::loop() function * (and therefore, indirectly, from I2CRB::wait() and I2CRB::isBusy()). ***************************************************************************/ void I2CManagerClass::I2C_handleInterrupt() { volatile uint16_t temp_sr1, temp_sr2; (void) temp_sr2; // only used as target for reads temp_sr1 = s->SR1; // Check for errors first if (temp_sr1 & (I2C_SR1_AF | I2C_SR1_ARLO | I2C_SR1_BERR)) { // Check which error flag is set if (temp_sr1 & I2C_SR1_AF) { s->SR1 &= ~(I2C_SR1_AF); // Clear AF I2C_sendStop(); // Clear the bus transactionState = TS_IDLE; completionStatus = I2C_STATUS_NEGATIVE_ACKNOWLEDGE; state = I2C_STATE_COMPLETED; } else if (temp_sr1 & I2C_SR1_ARLO) { // Arbitration lost, restart s->SR1 &= ~(I2C_SR1_ARLO); // Clear ARLO I2C_sendStart(); // Reinitiate request transactionState = TS_START; } else if (temp_sr1 & I2C_SR1_BERR) { // Bus error s->SR1 &= ~(I2C_SR1_BERR); // Clear BERR I2C_sendStop(); // Clear the bus transactionState = TS_IDLE; completionStatus = I2C_STATUS_BUS_ERROR; state = I2C_STATE_COMPLETED; } } else { // No error flags, so process event according to current state. switch (transactionState) { case TS_START: if (temp_sr1 & I2C_SR1_SB) { // Event EV5 // Start bit has been sent successfully and we have the bus. // If anything to send, initiate write. Otherwise initiate read. if (operation == OPERATION_READ || ((operation == OPERATION_REQUEST) && !bytesToSend)) { // Send address with read flag (1) or'd in s->DR = (deviceAddress << 1) | 1; // send the address transactionState = TS_R_ADDR; } else { // Send address with write flag (0) or'd in s->DR = (deviceAddress << 1) | 0; // send the address transactionState = TS_W_ADDR; } } // SB bit is cleared by writing to DR (already done). break; case TS_W_ADDR: if (temp_sr1 & I2C_SR1_ADDR) { temp_sr2 = s->SR2; // read SR2 to complete clearing the ADDR bit // Event EV6 // Address sent successfully, device has ack'd in response. if (!bytesToSend) { I2C_sendStop(); transactionState = TS_IDLE; completionStatus = I2C_STATUS_OK; state = I2C_STATE_COMPLETED; } else { // Put one byte into DR to load shift register. s->DR = sendBuffer[txCount++]; bytesToSend--; if (bytesToSend) { // Put another byte to load DR s->DR = sendBuffer[txCount++]; bytesToSend--; } if (!bytesToSend) { // No more bytes to send. // The TXE interrupt occurs when the DR is empty, and the BTF interrupt // occurs when the shift register is also empty (one character later). // To avoid repeated TXE interrupts during this time, we disable TXE interrupt. s->CR2 &= ~I2C_CR2_ITBUFEN; // Wait for BTF interrupt, disable TXE interrupt transactionState = TS_W_STOP; } else { // More data remaining to send after this interrupt, enable TXE interrupt. s->CR2 |= I2C_CR2_ITBUFEN; transactionState = TS_W_DATA; } } } break; case TS_W_DATA: if (temp_sr1 & I2C_SR1_TXE) { // Event EV8_1/EV8 // Transmitter empty, write a byte to it. if (bytesToSend) { s->DR = sendBuffer[txCount++]; bytesToSend--; if (!bytesToSend) { s->CR2 &= ~I2C_CR2_ITBUFEN; // Disable TXE interrupt transactionState = TS_W_STOP; } } } break; case TS_W_STOP: if (temp_sr1 & I2C_SR1_BTF) { // Event EV8_2 // Done, last character sent. Anything to receive? if (bytesToReceive) { I2C_sendStart(); // NOTE: Three redundant BTF interrupts take place between the // first BTF interrupt and the START interrupt. I've tried all sorts // of ways to eliminate them, and the only thing that worked for // me was to loop until the BTF bit becomes reset. Either way, // it's a waste of processor time. Anyone got a solution? //while (s->SR1 && I2C_SR1_BTF) {} transactionState = TS_START; } else { I2C_sendStop(); transactionState = TS_IDLE; completionStatus = I2C_STATUS_OK; state = I2C_STATE_COMPLETED; } s->SR1 &= I2C_SR1_BTF; // Clear BTF interrupt } break; case TS_R_ADDR: if (temp_sr1 & I2C_SR1_ADDR) { // Event EV6 // Address sent for receive. // The next bit is different depending on whether there are // 1 byte, 2 bytes or >2 bytes to be received, in accordance with the // Programmers Reference RM0390. if (bytesToReceive == 1) { // Receive 1 byte s->CR1 &= ~I2C_CR1_ACK; // Disable ack temp_sr2 = s->SR2; // read SR2 to complete clearing the ADDR bit // Next step will occur after a RXNE interrupt, so enable it s->CR2 |= I2C_CR2_ITBUFEN; transactionState = TS_R_STOP; } else if (bytesToReceive == 2) { // Receive 2 bytes s->CR1 &= ~I2C_CR1_ACK; // Disable ACK for final byte s->CR1 |= I2C_CR1_POS; // set POS flag to delay effect of ACK flag // Next step will occur after a BTF interrupt, so disable RXNE interrupt s->CR2 &= ~I2C_CR2_ITBUFEN; temp_sr2 = s->SR2; // read SR2 to complete clearing the ADDR bit transactionState = TS_R_STOP; } else { // >2 bytes, just wait for bytes to come in and ack them for the time being // (ack flag has already been set). // Next step will occur after a BTF interrupt, so disable RXNE interrupt s->CR2 &= ~I2C_CR2_ITBUFEN; temp_sr2 = s->SR2; // read SR2 to complete clearing the ADDR bit transactionState = TS_R_DATA; } } break; case TS_R_DATA: // Event EV7/EV7_1 if (temp_sr1 & I2C_SR1_BTF) { // Byte received in receiver - read next byte if (bytesToReceive == 3) { // Getting close to the last byte, so a specific sequence is recommended. s->CR1 &= ~I2C_CR1_ACK; // Reset ack for next byte received. transactionState = TS_R_STOP; } receiveBuffer[rxCount++] = s->DR; // Store received byte bytesToReceive--; } break; case TS_R_STOP: if (temp_sr1 & I2C_SR1_BTF) { // Event EV7 (last one) // When we've got here, the receiver has got the last two bytes // (or one byte, if only one byte is being received), // and NAK has already been sent, so we need to read from the receiver. if (bytesToReceive) { if (bytesToReceive > 1) I2C_sendStop(); while(bytesToReceive) { receiveBuffer[rxCount++] = s->DR; // Store received byte(s) bytesToReceive--; } // Finish. transactionState = TS_IDLE; completionStatus = I2C_STATUS_OK; state = I2C_STATE_COMPLETED; } } else if (temp_sr1 & I2C_SR1_RXNE) { if (bytesToReceive == 1) { // One byte on a single-byte transfer. Ack has already been set. I2C_sendStop(); receiveBuffer[rxCount++] = s->DR; // Store received byte bytesToReceive--; // Finish. transactionState = TS_IDLE; completionStatus = I2C_STATUS_OK; state = I2C_STATE_COMPLETED; } else s->SR1 &= I2C_SR1_RXNE; // Acknowledge interrupt } break; } // If we've received an interrupt at any other time, we're not interested so clear it // to prevent it recurring ad infinitum. s->SR1 = 0; } } #endif /* I2CMANAGER_STM32_H */ ================================================ FILE: I2CManager_Wire.h ================================================ /* * © 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 . */ #ifndef I2CMANAGER_WIRE_H #define I2CMANAGER_WIRE_H #include #include #include "I2CManager.h" // This module is only compiled if I2C_USE_WIRE is defined, so define it here // to get intellisense to work correctly. #if !defined(I2C_USE_WIRE) #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 } /*************************************************************************** * Set I2C clock speed. Normally 100000 (Standard) or 400000 (Fast) * on Arduino. Mega4809 supports 1000000 (Fast+) too. ***************************************************************************/ 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(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(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 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. * 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) { switch (req->operation & OPERATION_MASK) { case OPERATION_READ: read(req->i2cAddress, req->readBuffer, req->readLen, NULL, 0, req); break; case OPERATION_SEND: write(req->i2cAddress, req->writeBuffer, req->writeLen, req); break; case OPERATION_SEND_P: write_P(req->i2cAddress, req->writeBuffer, req->writeLen, req); break; case OPERATION_REQUEST: read(req->i2cAddress, req->readBuffer, req->readLen, req->writeBuffer, req->writeLen, req); break; } } /*************************************************************************** * Loop function, for general background work ***************************************************************************/ void I2CManagerClass::loop() {} #endif ================================================ FILE: IODevice.cpp ================================================ /* * © 2021 Neil McKechnie * © 2021 Harald Barth * 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 . */ #include #include "IODevice.h" #include "DIAG.h" #include "FSH.h" #include "IO_MCP23017.h" #include "DCCTimer.h" #if defined(ARDUINO_ARCH_AVR) || defined(ARDUINO_ARCH_MEGAAVR) #define USE_FAST_IO #endif // Link to halSetup function. If not defined, the function reference will be NULL. extern __attribute__((weak)) void halSetup(); extern __attribute__((weak)) bool exrailHalSetup1(); extern __attribute__((weak)) bool exrailHalSetup2(); //================================================================================================================== // Static methods //------------------------------------------------------------------------------------------------------------------ // Static functions // Static method to initialise the IODevice subsystem. #if !defined(IO_NO_HAL) // Create any standard device instances that may be required, such as the Arduino pins // and PCA9685. void IODevice::begin() { // Initialise the IO subsystem defaults ArduinoPins::create(2, NUM_DIGITAL_PINS-2); // Reserve pins for direct access // 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. // The first pass call only creates HAL devices, // the second pass will apply servo settings etc which can only be // done after all devices (including the defaults) are created. // If exrailHalSetup1 is not defined, then it will be NULL and the call // will be ignored. // If it returns true, then the default HAL devices will not be created. bool ignoreDefaults=false; if (exrailHalSetup1) ignoreDefaults=exrailHalSetup1(); if (!ignoreDefaults) { // Predefine two PCA9685 modules 0x40-0x41 if no conflicts // Allocates 32 pins 100-131 const bool silent=true; // no message if these conflict if (checkNoOverlap(100, 16, 0x40, silent)) { PCA9685::create(100, 16, 0x40); } if (checkNoOverlap(116, 16, 0x41, silent)) { PCA9685::create(116, 16, 0x41); } // Predefine two MCP23017 module 0x20/0x21 if no conflicts // Allocates 32 pins 164-195 if (checkNoOverlap(164, 16, 0x20, silent)) { MCP23017::create(164, 16, 0x20); } if (checkNoOverlap(180, 16, 0x21, silent)) { MCP23017::create(180, 16, 0x21); } } // apply any second pass HAL setup from EXRAIL. // This will typically set up servo profiles, or create turnouts. if (exrailHalSetup2) exrailHalSetup2(); } // 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(); } } // Overarching static loop() method for the IODevice subsystem. Works through the // list of installed devices and calls their individual _loop() method. // Devices may or may not implement this, but if they do it is useful for things like animations // or flashing LEDs. // The current value of micros() is passed as a parameter, so the called loop function // doesn't need to invoke it. void IODevice::loop() { unsigned long currentMicros = micros(); IODevice *lastLoopDevice = _nextLoopDevice; // So we know when to stop... // Loop through devices until we find one ready to be serviced. do { if (!_nextLoopDevice) _nextLoopDevice = _firstDevice; if (_nextLoopDevice) { if (_nextLoopDevice->_deviceState != DEVSTATE_FAILED && ((long)(currentMicros - _nextLoopDevice->_nextEntryTime)) >= 0) { // Found one ready to run, so invoke its _loop method. _nextLoopDevice->_nextEntryTime = currentMicros; _nextLoopDevice->_loop(currentMicros); _nextLoopDevice = _nextLoopDevice->_nextDevice; break; } // Not this one, move to next one _nextLoopDevice = _nextLoopDevice->_nextDevice; } } while (_nextLoopDevice != lastLoopDevice); // Stop looking when we've done all. // Report loop time if diags enabled #if defined(DIAG_LOOPTIMES) unsigned long diagMicros = micros(); static unsigned long lastMicros = 0; // 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 (~3 milliseconds) if (currentMicros - lastOutputTime > 3000UL) { if (elapsed > maxElapsed) maxElapsed = elapsed; if (halElapsed > maxHalElapsed) maxHalElapsed = halElapsed; halTotal += halElapsed; total += elapsed; count++; } 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 = diagMicros; } // Read microsecond count after calculations, so they aren't // included in the overall timings. lastMicros = micros(); #endif } // Display a list of all the devices on the diagnostic stream. void IODevice::DumpAll() { for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) { dev->_display(); } } // Determine if the specified vpin is allocated to a device. bool IODevice::exists(VPIN vpin) { return findDevice(vpin) != NULL; } // Return the status of the device att vpin. uint8_t IODevice::getStatus(VPIN vpin) { IODevice *dev = findDevice(vpin); if (!dev) return false; return dev->_deviceState; } // check whether the pin supports notification. If so, then regular _read calls are not required. bool IODevice::hasCallback(VPIN vpin) { IODevice *dev = findDevice(vpin); if (!dev) return false; return dev->_hasCallback; } // Display (to diagnostics) details of the device. void IODevice::_display() { DIAG(F("Unknown device Vpins:%u-%u %S"), (int)_firstVpin, (int)_firstVpin+_nPins-1, _deviceState==DEVSTATE_FAILED ? F("OFFLINE") : F("")); } // Find device associated with nominated Vpin and pass configuration values on to it. // Return false if not found. 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) { IODevice *dev = findDevice(vpin); if (dev) { dev->_write(vpin, value); return; } #ifdef DIAG_IO DIAG(F("IODevice::write(): VPIN %u not found!"), (int)vpin); #endif } // Write value to count virtual pin(s). // these may be within one driver or separated over several drivers void IODevice::writeRange(VPIN vpin, int value, int count) { while(count) { auto dev = findDevice(vpin); if (dev) { auto vpinBefore=vpin; // write to driver, driver will return next vpin it cant handle vpin=dev->_writeRange(vpin, value,count); count-= vpin-vpinBefore; // decrement by number of vpins changed } else { // skip a vpin if no device handler vpin++; count--; } } } // Write analogue value to virtual pin(s). If multiple devices are allocated // the same pin then only the first one found will be used. // // The significance of param1 and param2 may vary from device to device. // For servo controllers, param1 is the profile of the transition and param2 // the duration, i.e. the time that the operation is to be animated over // in deciseconds (0-3276 sec) // void IODevice::writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t param2) { IODevice *dev = findDevice(vpin); if (dev) { dev->_writeAnalogue(vpin, value, param1, param2); return; } #ifdef DIAG_IO DIAG(F("IODevice::writeAnalogue(): VPIN %u not found!"), (int)vpin); #endif } // void IODevice::writeAnalogueRange(VPIN vpin, int value, uint8_t param1, uint16_t param2,int count) { while(count) { auto dev = findDevice(vpin); if (dev) { auto vpinBefore=vpin; // write to driver, driver will return next vpin it cant handle vpin=dev->_writeAnalogueRange(vpin, value, param1, param2,count); count-= vpin-vpinBefore; // decrement by number of vpins changed } else { // skip a vpin if no device handler vpin++; count--; } } } // isBusy, when called for a device pin is always a digital output or analogue output, // returns input feedback state of the pin, i.e. whether the pin is busy performing // an animation or fade over a period of time. bool IODevice::isBusy(VPIN vpin) { IODevice *dev = findDevice(vpin); if (dev) return dev->_read(vpin); else return false; } void IODevice::setGPIOInterruptPin(int16_t pinNumber) { if (pinNumber >= 0) pinMode(pinNumber, INPUT_PULLUP); _gpioInterruptPin = pinNumber; } // 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) { 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->_begin(); } // Private helper function to locate a device by VPIN. Returns NULL if not found. // This is performance-critical, so minimises the calculation and function calls necessary. IODevice *IODevice::findDevice(VPIN vpin) { for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) { VPIN firstVpin = dev->_firstVpin; if (vpin >= firstVpin && vpin < firstVpin+dev->_nPins) return dev; } return NULL; } // Instance helper function for filter devices (layered over others). Looks for // a device that is further down the chain than the current device. IODevice *IODevice::findDeviceFollowing(VPIN vpin) { for (IODevice *dev = _nextDevice; dev != 0; dev = dev->_nextDevice) { VPIN firstVpin = dev->_firstVpin; if (vpin >= firstVpin && vpin < firstVpin+dev->_nPins) return dev; } return NULL; } // Private helper function to check for vpin overlap. Run during setup only. // returns true if pins DONT overlap with existing device // TODO: Move the I2C address reservation and checks into the I2CManager code. // That will enable non-HAL devices to reserve I2C addresses too. // Silent is used by the default setup so that there is no message if the default // device has already been handled by the user setup. bool IODevice::checkNoOverlap(VPIN firstPin, uint8_t nPins, I2CAddress i2cAddress, bool silent) { #ifdef DIAG_IO DIAG(F("Check no overlap %u %u %s"), firstPin,nPins,i2cAddress.toString()); #endif VPIN lastPin=firstPin+nPins-1; for (IODevice *dev = _firstDevice; dev != 0; dev = dev->_nextDevice) { if (nPins > 0 && dev->_nPins > 0) { // check for pin range overlaps (verbose but compiler will fix that) VPIN firstDevPin=dev->_firstVpin; VPIN lastDevPin=firstDevPin+dev->_nPins-1; bool noOverlap= firstPin>lastDevPin || lastPin_I2CAddress==i2cAddress) { if (!silent) DIAG(F("WARNING HAL Overlap. i2c Addr %s ignored."),i2cAddress.toString()); return false; } } return true; // no overlaps... OK to go on with constructor } //================================================================================================================== // Static data //------------------------------------------------------------------------------------------------------------------ // Chain of callback blocks (identifying registered callback functions for state changes) IONotifyCallback *IONotifyCallback::first = 0; // 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; //================================================================================================================== // Instance members //------------------------------------------------------------------------------------------------------------------ // Method to check whether the id corresponds to this device bool IODevice::owns(VPIN id) { return (id >= _firstVpin && id < _firstVpin + _nPins); } #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 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]); #endif 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); } 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) { return ADCee::read(vpin); } int IODevice::configureAnalogIn(VPIN vpin) { return ADCee::init(vpin); } void IODevice::loop() {} void IODevice::DumpAll() { DIAG(F("NO HAL CONFIGURED!")); } bool IODevice::exists(VPIN vpin) { return (vpin > 2 && vpin < NUM_DIGITAL_PINS); } void IODevice::setGPIOInterruptPin(int16_t) {} // Chain of callback blocks (identifying registered callback functions for state changes) // Not used in IO_NO_HAL but must be declared. IONotifyCallback *IONotifyCallback::first = 0; #endif // IO_NO_HAL ///////////////////////////////////////////////////////////////////////////////////////////////////// // Constructor ArduinoPins::ArduinoPins(VPIN firstVpin, int nPins) { _firstVpin = firstVpin; _nPins = nPins; int arrayLen = (_nPins+7)/8; _pinPullups = (uint8_t *)calloc(3, arrayLen); _pinModes = (&_pinPullups[0]) + arrayLen; _pinInUse = (&_pinPullups[0]) + 2*arrayLen; for (int i=0; i 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) { // Currently in write mode, change to read mode _pinModes[index] &= ~mask; // Since mode changes should be infrequent, use standard pinMode function if (_pinPullups[index] & mask) pinMode(pin, INPUT_PULLUP); else pinMode(pin, INPUT); } int value = ADCee::init(pin); #ifdef DIAG_IO DIAG(F("configureAnalogIn Pin:%d Value:%d"), pin, value); #endif return value; } void ArduinoPins::_display() { DIAG(F("Arduino Vpins:%u-%u"), (int)_firstVpin, (int)_firstVpin+_nPins-1); } ///////////////////////////////////////////////////////////////////////////////////////////////////// void ArduinoPins::fastWriteDigital(uint8_t pin, uint8_t value) { #if defined(USE_FAST_IO) if (pin >= NUM_DIGITAL_PINS) return; uint8_t mask = digitalPinToBitMask(pin); uint8_t port = digitalPinToPort(pin); volatile uint8_t *outPortAdr = portOutputRegister(port); noInterrupts(); if (value) *outPortAdr |= mask; else *outPortAdr &= ~mask; interrupts(); #else digitalWrite(pin, value); #endif } bool ArduinoPins::fastReadDigital(uint8_t pin) { #if defined(USE_FAST_IO) if (pin >= NUM_DIGITAL_PINS) return false; uint8_t mask = digitalPinToBitMask(pin); uint8_t port = digitalPinToPort(pin); volatile uint8_t *inPortAdr = portInputRegister(port); // read input bool result = (*inPortAdr & mask) != 0; #else bool result = digitalRead(pin); #endif return result; } ================================================ FILE: IODevice.h ================================================ /* * © 2023, Paul Antoine, 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 . */ #ifndef iodevice_h #define iodevice_h // Define symbol DIAG_IO to enable diagnostic output //#define DIAG_IO Y // Define symbol DIAG_LOOPTIMES to enable CS loop execution time to be reported //#define DIAG_LOOPTIMES // Define symbol IO_SWITCH_OFF_SERVO to set the PCA9685 output to 0 when an // animation has completed. This switches off the servo motor, preventing // the continuous buzz sometimes found on servos, and reducing the // power consumption of the servo when inactive. // It is recommended to enable this, unless it causes you problems. #define IO_SWITCH_OFF_SERVO #include "DIAG.h" #include "FSH.h" #include "I2CManager.h" #include "inttypes.h" #include "TemplateForEnums.h" typedef uint16_t VPIN; // Limit VPIN number to max 32767. Above this number, printing often gives negative values. // This should be enough for 99% of users. #define VPIN_MAX 32767 #define VPIN_NONE 65535 /* * Callback support for state change notification from an IODevice subclass to a * handler, e.g. Sensor object handling. */ class IONotifyCallback { public: typedef void IONotifyCallbackFunction(VPIN vpin, int value); static void add(IONotifyCallbackFunction *function) { IONotifyCallback *blk = new IONotifyCallback(function); if (first) blk->next = first; first = blk; } static void invokeAll(VPIN vpin, int value) { for (IONotifyCallback *blk = first; blk != NULL; blk = blk->next) blk->invoke(vpin, value); } static bool hasCallback() { return first != NULL; } private: IONotifyCallback(IONotifyCallbackFunction *function) { invoke = function; }; IONotifyCallback *next = 0; IONotifyCallbackFunction *invoke = 0; static IONotifyCallback *first; }; /* * IODevice class * * This class is the basis of the Hardware Abstraction Layer (HAL) for * the DCC++EX Command Station. All device classes derive from this. * */ class IODevice { public: // Parameter values to identify type of call to IODevice::configure. typedef enum : uint8_t { CONFIGURE_INPUT = 1, CONFIGURE_SERVO = 2, CONFIGURE_OUTPUT = 3, CONFIGURE_ANALOGOUTPUT = 4, CONFIGURE_ANALOGINPUT = 5, } ConfigTypeEnum; typedef enum : uint8_t { DEVSTATE_DORMANT = 0, DEVSTATE_PROBING = 1, DEVSTATE_INITIALISING = 2, DEVSTATE_NORMAL = 3, DEVSTATE_SCANNING = 4, DEVSTATE_FAILED = 5, } DeviceStateEnum; // Static functions to find the device and invoke its member functions // begin is invoked to create any standard IODevice subclass instances. // 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[]); // User-friendly function for configuring an input pin. inline static bool configureInput(VPIN vpin, bool pullupEnable) { int params[] = {pullupEnable}; return IODevice::configure(vpin, CONFIGURE_INPUT, 1, params); } // User-friendly function for configuring a servo pin. inline static bool configureServo(VPIN vpin, uint16_t activePosition, uint16_t inactivePosition, uint8_t profile=0, uint16_t duration=0, uint8_t initialState=0) { int params[] = {(int)activePosition, (int)inactivePosition, profile, (int)duration, initialState}; return IODevice::configure(vpin, CONFIGURE_SERVO, 5, params); } // write invokes the IODevice instance's _write method. static void write(VPIN vpin, int value); static void writeRange(VPIN vpin, int value,int count); // write invokes the IODevice instance's _writeAnalogue method (not applicable for digital outputs) static void writeAnalogue(VPIN vpin, int value, uint8_t profile=0, uint16_t duration=0); static void writeAnalogueRange(VPIN vpin, int value, uint8_t profile, uint16_t duration, int count); // isBusy returns true if the device is currently in an animation of some sort, e.g. is changing // the output over a period of time. static bool isBusy(VPIN vpin); // check whether the pin supports notification. If so, then regular _read calls are not required. static bool hasCallback(VPIN vpin); // read invokes the IODevice instance's _read method. static int read(VPIN vpin); // 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(); static void DumpAll(); // exists checks whether there is a device owning the specified vpin static bool exists(VPIN vpin); // getStatus returns the state of the device at the specified vpin static uint8_t getStatus(VPIN vpin); // Enable shared interrupt on specified pin for GPIO extender modules. The extender module // should pull down this pin when requesting a scan. The pin may be shared by multiple modules. // Without the shared interrupt, input states are scanned periodically to detect changes on // GPIO extender pins. If a shared interrupt pin is configured, then input states are scanned // only when the shared interrupt pin is pulled low. The external GPIO module releases the pin // once the GPIO port concerned has been read. void setGPIOInterruptPin(int16_t pinNumber); // Method to check if pins will overlap before creating new device. static bool checkNoOverlap(VPIN firstPin, uint8_t nPins=1, I2CAddress i2cAddress=0, bool silent=false); // Method used by IODevice filters to locate slave pins that may be overlayed by their own // pin range. IODevice *findDeviceFollowing(VPIN vpin); // Method to write new state (optionally implemented within device class) virtual void _write(VPIN vpin, int value) { (void)vpin; (void)value; }; // Method to write new state (optionally implemented within device class) // This will, by default just write to one vpin and return whet to do next. // the real power comes where a single driver can update many vpins in one call. virtual VPIN _writeRange(VPIN vpin, int value, int count) { (void)count; _write(vpin,value); return vpin+1; // try next vpin }; // Method to write an 'analogue' value (optionally implemented within device class) virtual void _writeAnalogue(VPIN vpin, int value, uint8_t param1=0, uint16_t param2=0) { (void)vpin; (void)value; (void) param1; (void)param2; }; // Method to write an 'analogue' value to a VPIN range (optionally implemented within device class) // This will, by default just write to one vpin and return whet to do next. // the real power comes where a single driver can update many vpins in one call. virtual VPIN _writeAnalogueRange(VPIN vpin, int value, uint8_t param1, uint16_t param2, int count) { (void) count; _writeAnalogue(vpin, value, param1, param2); return vpin+1; }; // Method to read digital pin state (optionally implemented within device class) virtual int _read(VPIN vpin) { (void)vpin; return 0; }; // Method to read analogue pin state (optionally implemented within device class) virtual int _readAnalogue(VPIN vpin) { (void)vpin; 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. }; // Method for displaying info on DIAG output (optionally implemented within device class) virtual void _display(); // Destructor virtual ~IODevice() {}; // Non-virtual function void delayUntil(unsigned long futureMicrosCount) { _nextEntryTime = futureMicrosCount; } // 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, IODevice *slaveDevice = NULL); // Method to find device handling Vpin static IODevice *findDevice(VPIN vpin); // Current state of device DeviceStateEnum _deviceState = DEVSTATE_DORMANT; private: IODevice *_nextDevice = 0; unsigned long _nextEntryTime; static IODevice *_firstDevice; static IODevice *_nextLoopDevice; }; ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for PCA9685 16-channel PWM module. */ class PCA9685 : public IODevice { public: 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 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. }; 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; // Device-specific write functions. void _write(VPIN vpin, int value) override; void _writeAnalogue(VPIN vpin, int value, uint8_t profile, uint16_t duration) override; int _read(VPIN vpin) override; // returns the digital state or busy status of the device void _loop(unsigned long currentMicros) override; void updatePosition(uint8_t pin); void writeDevice(uint8_t pin, int value); void _display() override; void writeRegister(uint8_t reg, uint8_t value); 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 // 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 }; ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for DCC accessory decoder. */ class DCCAccessoryDecoder: public IODevice { public: static void create(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; void _display() override; int _packedAddress; }; ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for arduino input/output pins. */ class ArduinoPins: public IODevice { public: static void create(VPIN firstVpin, int nPins) { addDevice(new ArduinoPins(firstVpin, 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. void _write(VPIN vpin, int value) override; // Device-specific read functions. int _read(VPIN vpin) override; int _readAnalogue(VPIN vpin) override; int _configureAnalogIn(VPIN vpin) override; void _display() override; uint8_t *_pinPullups; uint8_t *_pinModes; // each bit is 1 for output, 0 for input uint8_t *_pinInUse; }; #ifndef IO_NO_HAL ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for EX-Turntable. */ class EXTurntable : public IODevice { public: static void create(VPIN firstVpin, int nPins, I2CAddress I2CAddress); // Constructor EXTurntable(VPIN firstVpin, int nPins, I2CAddress I2CAddress); enum ActivityNumber : uint8_t { Turn = 0, // Rotate turntable, maintain phase Turn_PInvert = 1, // Rotate turntable, invert phase Home = 2, // Initiate homing Calibrate = 3, // Initiate calibration sequence LED_On = 4, // Turn LED on LED_Slow = 5, // Set LED to a slow blink LED_Fast = 6, // Set LED to a fast blink LED_Off = 7, // Turn LED off Acc_On = 8, // Turn accessory pin on Acc_Off = 9, // Turn accessory pin off }; private: // Device-specific write function. void _begin() override; void _loop(unsigned long currentMicros) override; int _read(VPIN vpin) override; void _broadcastStatus (VPIN vpin, uint8_t status, uint8_t activity); void _writeAnalogue(VPIN vpin, int value, uint8_t activity, uint16_t duration) override; void _display() override; uint8_t _stepperStatus; uint8_t _previousStatus; uint8_t _currentActivity; }; #endif ///////////////////////////////////////////////////////////////////////////////////////////////////// // IODevice framework for invoking user-written functions. // To use, define a function that you want to be regularly // invoked, and then create an instance of UserAddin. // For example, you can show the status, on screen 3, of the first eight // locos in the speed table: // // void updateLocoScreen() { // for (int i=0; i<8; i++) { // if (DCC::speedTable[i].loco > 0) { // int speed = DCC::speedTable[i].speedCode; // SCREEN(3, i, F("Loco:%4d %3d %c"), DCC::speedTable[i].loco, // speed & 0x7f, speed & 0x80 ? 'R' : 'F'); // } // } // } // // void halSetup() { // ... // UserAddin(updateLocoScreen, 1000); // Update every 1000ms // ... // } // class UserAddin : public IODevice { private: void (*_invokeUserFunction)(); int _delay; // milliseconds public: UserAddin(void (*func)(), int delay) { _invokeUserFunction = func; _delay = delay; addDevice(this); } // userFunction has no return value, no parameter. delay is in milliseconds. static void create(void (*userFunction)(), int delay) { new UserAddin(userFunction, delay); } protected: void _begin() { _display(); } void _loop(unsigned long currentMicros) override { _invokeUserFunction(); // _loop won't be called again until _delay ms have elapsed. delayUntil(currentMicros + _delay * 1000UL); } void _display() override { DIAG(F("UserAddin run every %dms"), _delay); } }; ///////////////////////////////////////////////////////////////////////////////////////////////////// // // This HAL device driver is intended for communication in automation // sequences. A VPIN can be SET or RESET within a sequence, and its // current state checked elsewhere using IF, IFNOT, AT etc. or monitored // from JMRI using a Sensor object (DCC-EX command). // Alternatively, the flag can be set from JMRI and other interfaces // using the 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 "IODeviceList.h" #endif // iodevice_h ================================================ FILE: IODeviceList.h ================================================ /* * © 2024, Chris Harlow. All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* This is the list of HAL drivers automatically included by IODevice.h It has been moved here to be easier to maintain than editing IODevice.h */ #include "IO_AnalogueInputs.h" #include "IO_DFPlayer.h" #include "IO_DS1307.h" #include "IO_duinoNodes.h" #include "IO_EncoderThrottle.h" #include "IO_EXFastclock.h" #include "IO_EXIOExpander.h" #include "IO_EXSensorCAM.h" #include "IO_HALDisplay.h" #include "IO_HCSR04.h" #include "IO_I2CRailcom.h" #include "IO_MCP23008.h" #include "IO_MCP23017.h" #include "IO_NeoPixel.h" #include "IO_PCA9555.h" #include "IO_PCA9685pwm.h" #include "IO_PCF8574.h" #include "IO_PCF8575.h" #include "IO_RotaryEncoder.h" #include "IO_Servo.h" #include "IO_TCA8418.h" #include "IO_TM1638.h" #include "IO_TouchKeypad.h" #include "IO_trainbrains.h" #include "IO_Bitmap.h" #include "IO_VL53L0X.h" #include "IO_XL9535.h" ================================================ FILE: IO_AnalogueInputs.h ================================================ /* * © 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 . */ #ifndef io_analogueinputs_h #define io_analogueinputs_h // Uncomment following line to slow the scan cycle down to 1second ADC samples, with // diagnostic output of scanned values. //#define IO_ANALOGUE_SLOW #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" #include "FSH.h" /********************************************************************************************** * ADS111x class for I2C-connected analogue input modules ADS1113, ADS1114 and ADS1115. * * ADS1113 and ADS1114 are restricted to 1 input. ADS1115 has a multiplexer which allows * any of four input pins to be read by its ADC. * * The driver polls the device in accordance with the constant 'scanInterval' below. On first loop * entry, the multiplexer is set to pin A0 and the ADC is triggered. On second and subsequent * entries, the analogue value is read from the conversion register and then the multiplexer and * ADC are set up to read the next pin. * * The ADS111x is set up as follows: * Single-shot scan * Data rate 128 samples/sec (7.8ms/sample, but scanned every 10ms) * Comparator off * Gain FSR=6.144V * The gain means that the maximum input voltage of 5V (when Vss=5V) gives a reading * of 32767*(5.0/6.144) = 26666. * * A device is configured by the following: * ADS111x::create(firstVpin, nPins, i2cAddress); * for example * ADS111x::create(300, 1, 0x48); // single-input ADS1113 * ADS111x::create(300, 4, 0x48); // four-input ADS1115 * * Note: The device is simple and does not need initial configuration, so it should recover from * temporary loss of communications or power. **********************************************************************************************/ class ADS111x: public IODevice { public: 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 = (nPins > 4) ? 4 : nPins; _I2CAddress = i2cAddress; _currentPin = 0; for (int8_t i=0; i<_nPins; i++) _value[i] = -1; addDevice(this); } 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)) { _nextState = STATE_STARTSCAN; #ifdef DIAG_IO _display(); #endif } else { DIAG(F("ADS111x device not found, I2C:%s"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; } } void _loop(unsigned long currentMicros) override { // Check that previous non-blocking write has completed, if not then wait uint8_t status = _i2crb.status; if (status == I2C_STATUS_PENDING) return; // Busy, so don't do anything. if (status == I2C_STATUS_OK) { switch (_nextState) { case STATE_STARTSCAN: // Configure ADC and multiplexer for next scan. See ADS111x datasheet for details // of configuration register settings. _outBuffer[0] = 0x01; // Config register address _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); delayUntil(currentMicros + scanInterval); _nextState = STATE_STARTREAD; break; case STATE_STARTREAD: // Reading the pin value _outBuffer[0] = 0x00; // Conversion register address 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 VPIN:%u value:%d"), _currentPin, _value[_currentPin]); #endif // Move to next pin if (++_currentPin >= _nPins) _currentPin = 0; _nextState = STATE_STARTSCAN; break; default: break; } } else { // error status DIAG(F("ADS111x I2C:%s Error:%d %S"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status)); _deviceState = DEVSTATE_FAILED; } } int _readAnalogue(VPIN vpin) override { int pin = vpin - _firstVpin; return _value[pin]; } void _display() override { DIAG(F("ADS111x I2C:%s Configured on Vpins:%u-%u %S"), _I2CAddress.toString(), _firstVpin, _firstVpin+_nPins-1, _deviceState == DEVSTATE_FAILED ? F("OFFLINE") : F("")); } // ADC conversion rate is 250SPS, or 4ms per conversion. Set the period between updates to 10ms. // This is enough to allow the conversion to reliably complete in time. #ifndef IO_ANALOGUE_SLOW const unsigned long scanInterval = 10000UL; // Period between successive ADC scans in microseconds. #else const unsigned long scanInterval = 1000000UL; // Period between successive ADC scans in microseconds. #endif enum : uint8_t { STATE_STARTSCAN, STATE_STARTREAD, STATE_GETVALUE, }; uint16_t _value[4]; uint8_t _outBuffer[3]; uint8_t _inBuffer[2]; uint8_t _currentPin; // ADC pin currently being scanned I2CRB _i2crb; uint8_t _nextState; }; #endif // io_analogueinputs_h ================================================ FILE: IO_Bitmap.h ================================================ /* * © 2025, Chris Harlow. All rights reserved. * * This file is part of DCC-EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef IO_Bitmap_h #define IO_Bitmap_h #include #include "defines.h" #include "IODevice.h" /* Bitmap provides a set of virtual pins with no hardware. Bitmap pins are able to be output and input and may be set and tested as digital or analogue values. When writing a digital value, the analogue value is set to 0 or 1. When reading a digital value, the return is LOW for value 0 or HIGH for any other value or analogue. Bitmap pins may be used for any purpose, this is easier to manage than LATCH in EXRAIL as they can be explicitely set and tested without interfering with underlying hardware. Bitmap pins may be set, reset and tested in the same way as any other pin. They are not persistent across reboots, but are retained in the current session. Bitmap pins may also be monitored by JMRI_SENSOR() and as for any other pin. */ class Bitmap : public IODevice { public: static void create(VPIN firstVpin, int nPins) { if (IODevice::checkNoOverlap(firstVpin,nPins)) new Bitmap( firstVpin, nPins); } Bitmap(VPIN firstVpin, int nPins) : IODevice(firstVpin, nPins) { _pinValues=(int16_t *) calloc(nPins,sizeof(int16_t)); // 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; _display(); } int _read(VPIN vpin) override { int pin=vpin - _firstVpin; return _pinValues[pin]?1:0; } void _write(VPIN vpin, int value) override { int pin = vpin - _firstVpin; _pinValues[pin]=value!=0; // this is digital write } int _readAnalogue(VPIN vpin) override { int pin=vpin - _firstVpin; return _pinValues[pin]; // this is analog read } void _writeAnalogue(VPIN vpin, int value, uint8_t profile, uint16_t duration) override { (void)profile; // suppress warning, not used in this function (void)duration; // suppress warning, not used in this function int pin=vpin - _firstVpin; _pinValues[pin]=value; // this is analog write } void _display() override { DIAG(F("Bitmap Configured on Vpins:%u-%u"), (int)_firstVpin, (int)_firstVpin+_nPins-1); } private: int16_t* _pinValues; }; #endif ================================================ FILE: IO_DCCAccessory.cpp ================================================ /* * © 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 . */ #include "DCC.h" #include "IODevice.h" #include "DIAG.h" #include "defines.h" #define PACKEDADDRESS(addr, subaddr) (((addr) << 2) + (subaddr)) #define ADDRESS(packedaddr) ((packedaddr) >> 2) #define SUBADDRESS(packedaddr) ((packedaddr) % 4) void DCCAccessoryDecoder::create(VPIN firstVpin, int nPins, int DCCAddress, int DCCSubaddress) { if (checkNoOverlap(firstVpin,nPins)) new DCCAccessoryDecoder(firstVpin, nPins, DCCAddress, DCCSubaddress); } // Constructors DCCAccessoryDecoder::DCCAccessoryDecoder(VPIN vpin, int nPins, int DCCAddress, int DCCSubaddress) { _firstVpin = vpin; _nPins = nPins; _packedAddress = PACKEDADDRESS(DCCAddress, DCCSubaddress); addDevice(this); } void DCCAccessoryDecoder::_begin() { #if defined(DIAG_IO) _display(); #endif } // 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; #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:%u-%u Addresses %d/%d-%d/%d)"), _firstVpin, _firstVpin+_nPins-1, ADDRESS(_packedAddress), SUBADDRESS(_packedAddress), ADDRESS(endAddress), SUBADDRESS(endAddress)); } ================================================ FILE: IO_DFPlayer.h ================================================ /* * © 2026, Nicola Malavasi. All rights reserved. * © 2025-26, Chris Harlow. All rights reserved. * © 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 . */ /* * This file acts as the main wrapper for the DFPlayer driver suite. * It provides a unified interface to create Serial or I2C instances. * * KEY FEATURES: * 1. Unified Interface: Simplified 'create' method for all transport layers, * making the driver more user-friendly in myHAL.cpp. * 2. Plug-and-Play (I2C): Eliminates the need for manual crystal frequency * parameters by leveraging the auto-detection logic in the I2C layer. * 3. Platform Abstraction: Automatically handles hardware differences between * standard AVR (Mega) and ESP32 (customizable serial pins). * 4. Resource Protection: Prevents VPIN and address conflicts by integrating * with the DCC-EX IODevice registry. */ #ifndef IO_DFPlayer_h #define IO_DFPlayer_h #include "IO_DFPlayerSerial.h" #include "IO_DFPlayerI2C.h" class DFPlayer : public IODevice { public: static void create(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress) { if (nPins>2) nPins=2; if (checkNoOverlap(firstVpin, nPins, i2cAddress)) { new DFPlayerI2C(firstVpin, i2cAddress, 0); if (nPins >= 2) { new DFPlayerI2C(firstVpin + 1, i2cAddress, 1); } } } #ifdef ESP32 static void create(VPIN f, HardwareSerial &s, int8_t rxPin, int8_t txPin) { create(f, 1, s, rxPin, txPin); } static void create(VPIN firstVpin, int nPins, HardwareSerial &serial, int8_t rxPin, int8_t txPin) { if (checkNoOverlap(firstVpin, nPins)) { serial.begin(9600, SERIAL_8N1, rxPin, txPin); new DFPlayerSerial(firstVpin, nPins, serial); } } #else static void create(VPIN f, HardwareSerial &s) { create(f, 1, s); } static void create(VPIN firstVpin, int nPins, HardwareSerial &serial) { if (checkNoOverlap(firstVpin, nPins)) { serial.begin(9600, SERIAL_8N1); new DFPlayerSerial(firstVpin, nPins, serial); } } #endif }; #endif ================================================ FILE: IO_DFPlayerBase.h ================================================ /* * © 2026, Nicola Malavasi. All rights reserved. * © 2025, Nicola Malavasi. All rights reserved. * © 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 . */ /* * This file defines the Abstract Base Class (DFPlayerBase) for DFPlayer devices. * It manages the high-level logic, state machine, and command queuing, * independent of the physical transport layer. * * KEY FEATURES: * 1. Command Queue (FIFO): Manages a queue to buffer commands, ensuring * a 120ms delay between transmissions to prevent module lock-ups. * 2. Protocol Handling: Automatically calculates the 16-bit checksum and * constructs the 10-byte serial frames required by the DFPlayer hardware. * 3. Power-on Stabilization: Sends a reset command during initialization * to ensure the module is ready before receiving functional commands. * 4. Bidirectional Feedback: Parses incoming bytes from the module to detect * events like "Track Finished" (0x3D), enabling RepeatPlay logic and synchronization. * 5. EX-RAIL Integration: Maps DCC-EX internal opcodes (DF_PLAY, DF_VOL, etc.) * to physical hardware commands via the _writeAnalogue override. * * SD CARD FILENAME CONVENTION (Mandatory): * --------------------------------------- * To ensure compatibility with PLAYSOUND(vpin, track) and DF_FOLDER commands, * the MicroSD must be formatted in FAT32 and follow this naming convention: * * 1. FOLDER NAMING: * Folders must be named with a 2-digit prefix (01 to 99). * Example: /01, /02, /03... * * 2. FILE NAMING: * Files inside folders must start with a 3-digit prefix (001 to 255). * Example: /01/001.mp3, /01/002_Engine_Start.mp3 * * 3. SPECIAL "MP3" FOLDER (Recommended for simple setups): * You can also use a folder named "mp3" (case insensitive) with * 4-digit filenames: /mp3/0001.mp3, /mp3/0002.mp3. * * IMPORTANT: The module often plays files based on their physical copy order. * It is recommended to clear the SD card and copy files in alphabetical order. */ #ifndef IO_DFPlayerBase_h #define IO_DFPlayerBase_h #include "IODevice.h" #include "DIAG.h" class DFPlayerBase : public IODevice { public: static const uint8_t DF_PLAY = 0x0F; static const uint8_t DF_STOPPLAY = 0x16; static const uint8_t DF_REPEATPLAY = 0x11; static const uint8_t DF_FOLDER = 0x17; static const uint8_t DF_VOL = 0x06; static const uint8_t DF_EQ = 0x07; static const uint8_t DF_RESET = 0x0C; static const uint8_t DF_PAUSE = 0x0E; static const uint8_t DF_RESUME = 0x0D; static const uint8_t DF_EQ_NORMAL = 0; static const uint8_t DF_EQ_POP = 1; static const uint8_t DF_EQ_ROCK = 2; static const uint8_t DF_EQ_JAZZ = 3; static const uint8_t DF_EQ_CLASSIC = 4; static const uint8_t DF_EQ_BASS = 5; protected: volatile bool _playing = false; bool _flagLoop = false; uint8_t _lastTrack = 1; uint8_t _currentVolume = 20; uint8_t _currentFolder = 1; uint8_t _inputIndex = 0; uint8_t _recvCMD = 0; unsigned long _lastXmit = 0; unsigned long _initStartTime = 0; unsigned long _unlockTimer = 0; unsigned long _repeatTimer = 0; bool _xtalChecked = false; struct CommandEntry { uint8_t cmd; uint8_t a1; uint8_t a2; }; static const uint8_t Q_SIZE = 8; CommandEntry _q[Q_SIZE]; uint8_t _head = 0; uint8_t _tail = 0; void queuePacket(uint8_t c, uint8_t a1 = 0, uint8_t a2 = 0) { if (_deviceState == DEVSTATE_FAILED) return; uint8_t n = (_head + 1) % Q_SIZE; if (n != _tail) { _q[_head] = {c, a1, a2}; _head = n; } } void forceUpdate(int val) { this->IODevice::write(_firstVpin, val); } DFPlayerBase(VPIN firstVpin, int nPins=1): IODevice(firstVpin, nPins) {} public: void _begin() override { if (_deviceState == DEVSTATE_FAILED) return; _deviceState = DEVSTATE_INITIALISING; _initStartTime = millis(); queuePacket(DF_RESET, 0, 0); } virtual void transmitCommandBuffer(const uint8_t buffer[], size_t bytes) = 0; virtual bool processIncoming() = 0; virtual void detectXtal() { } void _loop(unsigned long currentMicros) override { (void)currentMicros; if (_deviceState == DEVSTATE_FAILED) return; processIncoming(); unsigned long now = millis(); if (_deviceState == DEVSTATE_INITIALISING && (now - _initStartTime > 3000)) { if (!_xtalChecked) { detectXtal(); _xtalChecked = true; _deviceState = DEVSTATE_NORMAL; queuePacket(DF_VOL, 0, _currentVolume); } } if (_repeatTimer > 0 && now > _repeatTimer) { _repeatTimer = 0; queuePacket(DF_PLAY, _currentFolder, _lastTrack); } if (_unlockTimer > 0 && now > _unlockTimer) { _unlockTimer = 0; _playing = false; forceUpdate(0); } if (_head != _tail && (now - _lastXmit > 120)) { uint8_t out[] = {0x7E, 0xFF, 0x06, _q[_tail].cmd, 0x00, _q[_tail].a1, _q[_tail].a2, 0x00, 0x00, 0xEF}; int16_t sum = 0; for (int i = 1; i < 7; i++) sum -= out[i]; out[7] = (uint8_t)(sum >> 8); out[8] = (uint8_t)(sum & 0xff); transmitCommandBuffer(out, 10); _tail = (_tail + 1) % Q_SIZE; _lastXmit = now; } } void processIncomingByte(byte c) { static const byte HDR[] = {0x7E, 0xFF, 0x06}; if (_inputIndex < 3) { if (c == HDR[_inputIndex]) _inputIndex++; else _inputIndex = 0; return; } if (_inputIndex == 3) _recvCMD = c; if (_inputIndex == 6 && _recvCMD == 0x3D) { if (_flagLoop) _repeatTimer = millis() + 600; else _unlockTimer = millis() + 150; } _inputIndex++; if (_inputIndex >= 10) _inputIndex = 0; } void _write(VPIN vpin, int value) override { (void)vpin; if (_deviceState != DEVSTATE_NORMAL) return; _flagLoop = false; _repeatTimer = 0; if (value) { _playing = true; _lastTrack = (uint8_t)(vpin - _firstVpin + 1); queuePacket(DF_PLAY, _currentFolder, _lastTrack); } else { _unlockTimer = 0; _playing = false; queuePacket(DF_STOPPLAY, 0, 0); } } int _read(VPIN vpin) override { (void)vpin; return _playing ? 1 : 0; } protected: void _writeAnalogue(VPIN vpin, int v1, uint8_t v2=0, uint16_t cmd=0) override { (void)vpin; if (_deviceState != DEVSTATE_NORMAL) return; switch (cmd){ case DF_REPEATPLAY: case DF_PLAY: _flagLoop = (cmd == DF_REPEATPLAY); _repeatTimer = 0; _playing = true; _lastTrack = (uint8_t)v1; if (v2 > 0 && v2 <= 30) { _currentVolume = v2; queuePacket(DF_VOL, 0x00, _currentVolume); } queuePacket(DF_PLAY, _currentFolder, _lastTrack); break; case DF_FOLDER: _flagLoop = false; _playing = true; _currentFolder = (uint8_t)v2; _lastTrack = (uint8_t)v1; queuePacket(DF_FOLDER, _currentFolder, _lastTrack); break; case DF_STOPPLAY: _flagLoop = false; _playing = false; _unlockTimer = 0; _repeatTimer = 0; queuePacket(DF_STOPPLAY, 0, 0); forceUpdate(0); break; case DF_VOL: _currentVolume = (v2 > 0) ? v2 : 15; queuePacket(DF_VOL, 0x00, _currentVolume); break; case DF_EQ: queuePacket(DF_EQ, 0x00, (uint8_t)v2); break; case DF_PAUSE: _playing = false; queuePacket(DF_PAUSE, 0, 0); break; case DF_RESUME: _playing = true; queuePacket(DF_RESUME, 0, 0); break; case DF_RESET: _head = _tail = 0; queuePacket(DF_RESET, 0, 0); _deviceState = DEVSTATE_INITIALISING; _initStartTime = millis(); _xtalChecked = false; break; } } }; #endif ================================================ FILE: IO_DFPlayerI2C.h ================================================ /* * © 2025, Nicola Malavasi. All rights reserved. * © 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 . */ /* * This file implements the I2C transport layer for the DFPlayer driver, * using the SC16IS750/752 I2C-to-UART bridge. * * KEY FEATURES: * 1. Register Management: Directly handles SC16IS75x internal registers (THR, RHR, LCR, etc.) * to configure UART parameters over the I2C bus. * 2. Dual-Channel Support: Uses the _UART_CH_BITS to switch between Channel A and Channel B * on dual-UART bridge chips (like the SC16IS752). * 3. Auto-Baud Detection: Automatically probes the bridge crystal frequency * (1.8MHz or 14.7MHz) to lock the output at 9600 baud without manual configuration. * 4. Transparent Communication: Wraps standard DFPlayer serial packets into * I2C messages for seamless integration with the base class logic. * 5. I2C Bus Diagnostics: Monitors device presence and reports status (OK/FAILED) * via the DIAG console, including the detected crystal frequency. */ /* * © 2025, Nicola Malavasi. All rights reserved. * © 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 . */ /* * © 2025, Nicola Malavasi. All rights reserved. * © 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 . */ #ifndef IO_DFPlayerI2C_h #define IO_DFPlayerI2C_h #include "IO_DFPlayerBase.h" #define REG_THR 0x00 << 3 #define REG_RHR 0x00 << 3 #define REG_FCR 0x02 << 3 #define REG_LCR 0x03 << 3 #define REG_DLL 0x00 << 3 #define REG_DLH 0x01 << 3 #define REG_RXLVL 0x09 << 3 class DFPlayerI2C : public DFPlayerBase { private: uint8_t _UART_CH_BITS; unsigned long _xtal_freq; bool _xtal_detected = false; void writeRaw(uint8_t r, uint8_t v) { uint8_t reg = (uint8_t)(r | _UART_CH_BITS); uint8_t data[] = {reg, v}; I2CManager.write(_I2CAddress, data, 2); } void setBaud(unsigned long hz) { uint16_t div = (uint16_t)(hz / (9600UL * 16)); writeRaw(REG_LCR, 0x83); writeRaw(REG_DLL, (uint8_t)(div & 0xFF)); writeRaw(REG_DLH, (uint8_t)(div >> 8)); writeRaw(REG_LCR, 0x03); writeRaw(REG_FCR, 0x07); } public: DFPlayerI2C(VPIN v, I2CAddress a, uint8_t ch) : DFPlayerBase(v) { _I2CAddress = a; _UART_CH_BITS = (ch << 1); _xtal_freq = 1843200; addDevice(this); } void _begin() override { I2CManager.begin(); if (!I2CManager.exists(_I2CAddress)) { _deviceState = DEVSTATE_FAILED; DIAG(F("DFPlayer I2C Error: Bridge NOT found at %s"), _I2CAddress.toString()); return; } setBaud(_xtal_freq); DFPlayerBase::_begin(); } void detectXtal() override { if (_deviceState == DEVSTATE_FAILED) return; unsigned long test_xtals[] = {1843200, 14745600}; uint8_t lvl_reg = (uint8_t)(REG_RXLVL | _UART_CH_BITS); uint8_t rhr_reg = (uint8_t)(REG_RHR | _UART_CH_BITS); for (int i=0; i<2; i++) { setBaud(test_xtals[i]); delay(50); uint8_t avail=0, dummy; I2CManager.read(_I2CAddress, &avail, 1, &lvl_reg, 1); while(avail > 0) { for(int j=0; j= 4) { uint8_t resp[4]; for(int k=0; k<4; k++) I2CManager.read(_I2CAddress, &resp[k], 1, &rhr_reg, 1); if (resp[0] == 0x7E && resp[3] == 0x42) { _xtal_freq = test_xtals[i]; _xtal_detected = true; _display(); return; } } delay(5); } } _display(); } void _display() override { DIAG(F("DFPlayer I2C (%s) Ch %c: Xtal %S MHz %S VPIN %d %S"), _I2CAddress.toString(), (_UART_CH_BITS == 0) ? 'A' : 'B', (_xtal_freq > 2000000) ? F("14.7") : F("1.8"), (_xtal_detected) ? F("(AUTO)") : F("(TIMEOUT/MANUAL)"), _firstVpin, (_deviceState == DEVSTATE_FAILED) ? F("OFFLINE"):F("")); } void transmitCommandBuffer(const uint8_t b[], size_t s) override { if (_deviceState == DEVSTATE_FAILED) return; uint8_t pkt[s+1]; pkt[0] = (uint8_t)(REG_THR | _UART_CH_BITS); for(size_t i=0; i 0) { uint8_t rhr_reg = (uint8_t)(REG_RHR | _UART_CH_BITS); for (uint8_t i=0; i. */ /* * This file implements the Direct Hardware Serial transport layer for * the DFPlayer driver. * * KEY FEATURES: * 1. Hardware Serial Abstraction: Uses the Arduino HardwareSerial interface * to send and receive data directly via TX/RX pins. * 2. Low-Latency Transmission: Overrides transmitCommandBuffer to write * raw packets directly to the serial UART buffer. * 3. Asynchronous Receiving: Implements processIncoming using a non-blocking * while loop to drain the serial RX buffer and feed the base byte parser. * 4. Integration: Relies on the standard baud rate initialization (9600), * focusing strictly on high-speed data movement. * * TECHNICAL NOTE: * On STM32/Nucleo platforms, ensure the use of a 1k Ohm series resistor on * the DFPlayer RX line to mitigate signal noise and electrical mismatch. */ #ifndef IO_DFPlayerSerial_h #define IO_DFPlayerSerial_h #include "IO_DFPlayerBase.h" class DFPlayerSerial : public DFPlayerBase { protected: HardwareSerial *_serial; public: DFPlayerSerial(VPIN firstVpin, int nPins, HardwareSerial &s) : DFPlayerBase(firstVpin, nPins) { _serial = &s; addDevice(this); } void _begin() override { // La seriale viene inizializzata nel bridge IO_DFPlayer.h _deviceState = DEVSTATE_NORMAL; _display(); DFPlayerBase::_begin(); } // Implementazione obbligatoria del display per il log void _display() override { DIAG(F("DFPlayer Serial: Vpin %u %S"), (unsigned int)_firstVpin, (_deviceState==DEVSTATE_FAILED) ? F("FAILED") : F("OK")); } void transmitCommandBuffer(const uint8_t buffer[], size_t bytes) override { if (_deviceState == DEVSTATE_FAILED) return; _serial->write(buffer, bytes); } bool processIncoming() override { if (_deviceState == DEVSTATE_FAILED) return false; bool received = false; while (_serial->available()) { processIncomingByte(_serial->read()); received = true; } return received; } }; #endif ================================================ FILE: IO_DS1307.cpp ================================================ /* * © 2024, Chris Harlow. All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * The IO_DS1307 device driver is used to interface a standalone realtime clock. * The clock will announce every minute (which will trigger EXRAIL ONTIME events). * Seconds, and Day/date info is ignored, except that the announced hhmm time * will attempt to synchronize with the 0 seconds of the clock. * An analog read in EXRAIL (IFGTE(vpin, value) etc will check against the hh*60+mm time. * The clock can be easily set by an analog write to the vpin using 24 hr clock time * with the command */ #include "IO_DS1307.h" #include "I2CManager.h" #include "DIAG.h" #include "CommandDistributor.h" uint8_t d2b(uint8_t d) { return (d >> 4)*10 + (d & 0x0F); } void DS1307::create(VPIN vpin, I2CAddress i2cAddress) { if (checkNoOverlap(vpin, 1, i2cAddress)) new DS1307(vpin, i2cAddress); } // Constructor DS1307::DS1307(VPIN vpin,I2CAddress i2cAddress){ _firstVpin = vpin; _nPins = 1; _I2CAddress = i2cAddress; addDevice(this); } uint32_t DS1307::getTime() { // Obtain ss,mm,hh buffers from device uint8_t readBuffer[3]; const uint8_t writeBuffer[1]={0}; // address register 0 for read. I2CManager.write(_I2CAddress, writeBuffer, 1); if (I2CManager.read(_I2CAddress, readBuffer, 3) != I2C_STATUS_OK) { _deviceState=DEVSTATE_FAILED; return 0; } _deviceState=DEVSTATE_NORMAL; if (debug) { static const char hexchars[]="0123456789ABCDEF"; USB_SERIAL.print(F("<*RTC")); for (int i=2;i>=0;i--) { USB_SERIAL.write(' '); USB_SERIAL.write(hexchars[readBuffer[i]>>4]); USB_SERIAL.write(hexchars[readBuffer[i]& 0x0F ]); } StringFormatter::send(&USB_SERIAL,F(" %d *>\n"),_deviceState); } if (readBuffer[0] & 0x80) { _deviceState=DEVSTATE_INITIALISING; DIAG(F("DS1307 clock in standby")); return 0; // clock is not running } // convert device format to seconds since midnight uint8_t ss=d2b(readBuffer[0] & 0x7F); uint8_t mm=d2b(readBuffer[1]); uint8_t hh=d2b(readBuffer[2] & 0x3F); return (hh*60ul +mm)*60ul +ss; } void DS1307::_begin() { // Initialise device and sync loop() to zero seconds I2CManager.begin(); auto tstamp=getTime(); if (_deviceState==DEVSTATE_NORMAL) { byte seconds=tstamp%60; delayUntil(micros() + ((60-seconds) * 1000000)); } _display(); } // Processing loop to obtain clock time. // This self-synchronizes to the next minute tickover void DS1307::_loop(unsigned long currentMicros) { byte ss=0; auto time=getTime(); if (_deviceState==DEVSTATE_NORMAL) { ss=time%60; CommandDistributor::setClockTime(time/60, 1); } // delay until next expected minute tickover, // or 1 minute if clock not running delayUntil(currentMicros + ((60-ss) * 1000000)); } // Display device driver info. void DS1307::_display() { auto tstamp=getTime(); byte ss=tstamp%60; tstamp/=60; byte mm=tstamp%60; byte hh=tstamp/60; DIAG(F("DS1307 on I2C:%s vpin %d %d:%d:%d %S"), _I2CAddress.toString(), _firstVpin, hh,mm,ss, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F("")); } // allow user to set the clock void DS1307::_writeAnalogue(VPIN vpin, int hh, uint8_t mm, uint16_t ss) { (void) vpin; uint8_t writeBuffer[3]; writeBuffer[0]=1; // write mm,hh first writeBuffer[1]=((mm/10)<<4) + (mm % 10); writeBuffer[2]=((hh/10)<<4) + (hh % 10); I2CManager.write(_I2CAddress, writeBuffer, 3); writeBuffer[0]=0; // write ss writeBuffer[1]=((ss/10)<<4) + (ss % 10); I2CManager.write(_I2CAddress, writeBuffer, 2); _loop(micros()); // resync with seconds rollover } // Method to read analogue hh*60+mm time int DS1307::_readAnalogue(VPIN vpin) { (void)vpin; return getTime()/60; }; ================================================ FILE: IO_DS1307.h ================================================ /* * © 2024, Chris Harlow. All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * The IO_DS1307 device driver is used to interface a standalone realtime clock. * The clock will announce every minute (which will trigger EXRAIL ONTIME events). * Seconds, and Day/date info is ignored, except that the announced hhmm time * will attempt to synchronize with the 0 seconds of the clock. * An analog read in EXRAIL (IFGTE(vpin, value) etc will check against the hh*60+mm time. * The clock can be easily set by an analog write to the vpin using 24 hr clock time * with the command */ #ifndef IO_DS1307_h #define IO_DS1307_h #include "IODevice.h" class DS1307 : public IODevice { public: static const bool debug=false; static void create(VPIN vpin, I2CAddress i2cAddress); private: // Constructor DS1307(VPIN vpin,I2CAddress i2cAddress); uint32_t getTime(); void _begin() override; void _display() override; void _loop(unsigned long currentMicros) override; int _readAnalogue(VPIN vpin) override; void _writeAnalogue(VPIN vpin, int hh, uint8_t mm, uint16_t ss) override; }; #endif ================================================ FILE: IO_EXFastclock.h ================================================ /* * © 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 . */ /* * The IO_EXFastclock device driver is used to interface the standalone fast clock and receive time data. * * The EX-fastClock code lives in a separate repo (https://github.com/DCC-EX/EX-Fastclock) and contains the clock logic. * * */ #ifndef IO_EXFastclock_h #define IO_EXFastclock_h #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" #include "EXRAIL2.h" #include "CommandDistributor.h" bool FAST_CLOCK_EXISTS = true; class EXFastClock : public IODevice { public: // Constructor EXFastClock(I2CAddress i2cAddress){ _I2CAddress = i2cAddress; addDevice(this); } static void create(I2CAddress i2cAddress) { DIAG(F("Checking for Clock")); // Start by assuming we will find the clock // Check if specified I2C address is responding (blocking operation) // Returns I2C_STATUS_OK (0) if OK, or error code. I2CManager.begin(); uint8_t _checkforclock = I2CManager.checkAddress(i2cAddress); DIAG(F("Clock check result - %d"), _checkforclock); // XXXX change thistosave2 bytes if (_checkforclock == 0) { FAST_CLOCK_EXISTS = true; //DIAG(F("I2C Fast Clock found at %s"), i2cAddress.toString()); new EXFastClock(i2cAddress); } else { FAST_CLOCK_EXISTS = false; //DIAG(F("No Fast Clock found")); LCD(6,F("CLOCK NOT FOUND")); } } private: // Initialisation of Fastclock void _begin() override { if (FAST_CLOCK_EXISTS == true) { I2CManager.begin(); if (I2CManager.exists(_I2CAddress)) { _deviceState = DEVSTATE_NORMAL; #ifdef DIAG_IO _display(); #endif } else { _deviceState = DEVSTATE_FAILED; //LCD(6,F("CLOCK NOT FOUND")); DIAG(F("Fast Clock Not Found at address %s"), _I2CAddress.toString()); } } } // Processing loop to obtain clock time void _loop(unsigned long currentMicros) override{ if (FAST_CLOCK_EXISTS==true) { uint8_t readBuffer[3]; byte a,b; #ifdef EXRAIL_ACTIVE I2CManager.read(_I2CAddress, readBuffer, 3); // XXXX change this to save a few bytes a = readBuffer[0]; b = readBuffer[1]; //_clocktime = (a << 8) + b; //_clockrate = readBuffer[2]; CommandDistributor::setClockTime(((a << 8) + b), readBuffer[2]); //setClockTime(int16_t clocktime, int8_t clockrate); // 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 ================================================ FILE: IO_EXIOExpander.h ================================================ /* * © 2022, Peter Cole. All rights reserved. * © 2024, Harald Barth. All rights reserved. * * This file is part of EX-CommandStation * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * The IO_EXIOExpander.h device driver integrates with one or more EX-IOExpander devices. * This device driver will configure the device on startup, along with * interacting with the device for all input/output duties. * * To create EX-IOExpander devices, these are defined in myAutomation.h: * (Note the device driver is included by default) * * HAL(EXIOExpander,800,18,0x65) * * All pins on an EX-IOExpander device are allocated according to the pin map for the specific * device in use. There is no way for the device driver to sanity check pins are used for the * correct purpose, however the EX-IOExpander device's pin map will prevent pins being used * incorrectly (eg. A6/7 on Nano cannot be used for digital input/output). * * The total number of pins cannot exceed 256 because of the communications packet format. * The number of analogue inputs cannot exceed 16 because of a limit on the maximum * I2C packet size of 32 bytes (in the Wire library). */ #ifndef IO_EX_IOEXPANDER_H #define IO_EX_IOEXPANDER_H #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" #include "FSH.h" ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for EX-IOExpander. */ class EXIOExpander : public IODevice { public: enum ProfileType : uint8_t { Instant = 0, // Moves immediately between positions (if duration not specified) UseDuration = 0, // Use specified duration Fast = 1, // Takes around 500ms end-to-end Medium = 2, // 1 second end-to-end Slow = 3, // 2 seconds end-to-end Bounce = 4, // For semaphores/turnouts with a bit of bounce!! NoPowerOff = 0x80, // Flag to be ORed in to suppress power off after move. }; static void create(VPIN vpin, int nPins, I2CAddress i2cAddress) { if (checkNoOverlap(vpin, nPins, i2cAddress)) new EXIOExpander(vpin, nPins, i2cAddress); } private: // Constructor EXIOExpander(VPIN firstVpin, int nPins, I2CAddress i2cAddress) { _firstVpin = firstVpin; // Number of pins cannot exceed 256 (1 byte) because of I2C message structure. if (nPins > 256) nPins = 256; _nPins = nPins; _I2CAddress = i2cAddress; addDevice(this); } void _begin() { uint8_t status; // Initialise EX-IOExander device I2CManager.begin(); if (I2CManager.exists(_I2CAddress)) { // Send config, if EXIOPINS returned, we're good, setup pin buffers, otherwise go offline // NB The I2C calls here are done as blocking calls, as they're not time-critical // during initialisation and the reads require waiting for a response anyway. // Hence we can allocate I/O buffers from the stack. uint8_t receiveBuffer[3]; uint8_t commandBuffer[4] = {EXIOINIT, (uint8_t)_nPins, (uint8_t)(_firstVpin & 0xFF), (uint8_t)(_firstVpin >> 8)}; status = I2CManager.read(_I2CAddress, receiveBuffer, sizeof(receiveBuffer), commandBuffer, sizeof(commandBuffer)); if (status == I2C_STATUS_OK) { if (receiveBuffer[0] == EXIOPINS) { _numDigitalPins = receiveBuffer[1]; _numAnaloguePins = receiveBuffer[2]; // See if we already have suitable buffers assigned if (_numDigitalPins>0) { size_t digitalBytesNeeded = (_numDigitalPins + 7) / 8; if (_digitalPinBytes < digitalBytesNeeded) { // Not enough space, free any existing buffer and allocate a new one if (_digitalPinBytes > 0) free(_digitalInputStates); if ((_digitalInputStates = (byte*) calloc(digitalBytesNeeded, 1)) != NULL) { _digitalPinBytes = digitalBytesNeeded; } else { DIAG(F("EX-IOExpander I2C:%s ERROR alloc %d bytes"), _I2CAddress.toString(), digitalBytesNeeded); _deviceState = DEVSTATE_FAILED; _digitalPinBytes = 0; return; } } } if (_numAnaloguePins>0) { size_t analogueBytesNeeded = _numAnaloguePins * 2; if (_analoguePinBytes < analogueBytesNeeded) { // Free any existing buffers and allocate new ones. if (_analoguePinBytes > 0) { free(_analogueInputBuffer); free(_analogueInputStates); free(_analoguePinMap); } _analogueInputStates = (uint8_t*) calloc(analogueBytesNeeded, 1); _analogueInputBuffer = (uint8_t*) calloc(analogueBytesNeeded, 1); _analoguePinMap = (uint8_t*) calloc(_numAnaloguePins, 1); if (_analogueInputStates != NULL && _analogueInputBuffer != NULL && _analoguePinMap != NULL) { _analoguePinBytes = analogueBytesNeeded; } else { DIAG(F("EX-IOExpander I2C:%s ERROR alloc analog pin bytes"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; _analoguePinBytes = 0; return; } } } } else { DIAG(F("EX-IOExpander I2C:%s ERROR configuring device"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; return; } } // We now need to retrieve the analogue pin map if there are analogue pins if (status == I2C_STATUS_OK && _numAnaloguePins>0) { commandBuffer[0] = EXIOINITA; status = I2CManager.read(_I2CAddress, _analoguePinMap, _numAnaloguePins, commandBuffer, 1); } if (status == I2C_STATUS_OK) { // Attempt to get version, if we don't get it, we don't care, don't go offline uint8_t versionBuffer[3]; commandBuffer[0] = EXIOVER; if (I2CManager.read(_I2CAddress, versionBuffer, sizeof(versionBuffer), commandBuffer, 1) == I2C_STATUS_OK) { _majorVer = versionBuffer[0]; _minorVer = versionBuffer[1]; _patchVer = versionBuffer[2]; } DIAG(F("EX-IOExpander device found, I2C:%s, Version v%d.%d.%d"), _I2CAddress.toString(), _majorVer, _minorVer, _patchVer); #ifdef DIAG_IO _display(); #endif } if (status != I2C_STATUS_OK) reportError(status); } else { DIAG(F("EX-IOExpander I2C:%s device not found"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; } } // Digital input pin configuration, used to enable on EX-IOExpander device and set pullups if requested. // Configuration isn't done frequently so we can use blocking I2C calls here, and so buffers can // be allocated from the stack to reduce RAM allocation. bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) override { if (paramCount != 1) return false; int pin = vpin - _firstVpin; if (configType == CONFIGURE_INPUT) { uint8_t pullup = params[0]; uint8_t outBuffer[] = {EXIODPUP, (uint8_t)pin, pullup}; uint8_t responseBuffer[1]; uint8_t status = I2CManager.read(_I2CAddress, responseBuffer, sizeof(responseBuffer), outBuffer, sizeof(outBuffer)); if (status == I2C_STATUS_OK) { if (responseBuffer[0] == EXIORDY) { return true; } else { DIAG(F("EXIOVpin %u cannot be used as a digital input pin"), (int)vpin); } } else reportError(status); } else if (configType == CONFIGURE_ANALOGINPUT) { // TODO: Consider moving code from _configureAnalogIn() to here and remove _configureAnalogIn // from IODevice class definition. Not urgent, but each virtual function defined // means increasing the RAM requirement of every HAL device driver, whether it's relevant // to the driver or not. return false; } return false; } // Analogue input pin configuration, used to enable an EX-IOExpander device. // Use I2C blocking calls and allocate buffers from stack to save RAM. int _configureAnalogIn(VPIN vpin) override { int pin = vpin - _firstVpin; uint8_t commandBuffer[] = {EXIOENAN, (uint8_t)pin}; uint8_t responseBuffer[1]; uint8_t status = I2CManager.read(_I2CAddress, responseBuffer, sizeof(responseBuffer), commandBuffer, sizeof(commandBuffer)); if (status == I2C_STATUS_OK) { if (responseBuffer[0] == EXIORDY) { return true; } else { DIAG(F("EX-IOExpander: Vpin %u cannot be used as an analogue input pin"), (int)vpin); } } else reportError(status); return false; } // Main loop, collect both digital and analogue pin states continuously (faster sensor/input reads) void _loop(unsigned long currentMicros) override { if (_deviceState == DEVSTATE_FAILED) return; // If device failed, return // Request block is used for analogue and digital reads from the IOExpander, which are performed // on a cyclic basis. Writes are performed synchronously as and when requested. if (_readState != RDS_IDLE) { if (_i2crb.isBusy()) return; // If I2C operation still in progress, return uint8_t status = _i2crb.status; if (status == I2C_STATUS_OK) { // If device request ok, read input data // First check if we need to process received data if (_readState == RDS_ANALOGUE) { // Read of analogue values was in progress, so process received values // Here we need to copy the values from input buffer to the analogue value array. We need to // do this to avoid tearing of the values (i.e. one byte of a two-byte value being changed // while the value is being read). memcpy(_analogueInputStates, _analogueInputBuffer, _analoguePinBytes); // Copy I2C input buffer to states } else if (_readState == RDS_DIGITAL) { // Read of digital states was in progress, so process received values // The received digital states are placed directly into the digital buffer on receipt, // so don't need any further processing at this point (unless we want to check for // changes and notify them to subscribers, to avoid the need for polling - see IO_GPIOBase.h). } } else reportError(status, false); // report eror but don't go offline. _readState = RDS_IDLE; } // If we're not doing anything now, check to see if a new input transfer is due. if (_readState == RDS_IDLE) { if (_numDigitalPins>0 && currentMicros - _lastDigitalRead > _digitalRefresh) { // Delay for digital read refresh // Issue new read request for digital states. As the request is non-blocking, the buffer has to // be allocated from heap (object state). _readCommandBuffer[0] = EXIORDD; I2CManager.read(_I2CAddress, _digitalInputStates, (_numDigitalPins+7)/8, _readCommandBuffer, 1, &_i2crb); // non-blocking read _lastDigitalRead = currentMicros; _readState = RDS_DIGITAL; } else if (_numAnaloguePins>0 && currentMicros - _lastAnalogueRead > _analogueRefresh) { // Delay for analogue read refresh // Issue new read for analogue input states _readCommandBuffer[0] = EXIORDAN; I2CManager.read(_I2CAddress, _analogueInputBuffer, _numAnaloguePins * 2, _readCommandBuffer, 1, &_i2crb); _lastAnalogueRead = currentMicros; _readState = RDS_ANALOGUE; } } } // Obtain the correct analogue input value, with reference to the analogue // pin map. // Obtain the correct analogue input value int _readAnalogue(VPIN vpin) override { if (_deviceState == DEVSTATE_FAILED) return 0; int pin = vpin - _firstVpin; for (uint8_t aPin = 0; aPin < _numAnaloguePins; aPin++) { if (_analoguePinMap[aPin] == pin) { uint8_t _pinLSBByte = aPin * 2; uint8_t _pinMSBByte = _pinLSBByte + 1; return (_analogueInputStates[_pinMSBByte] << 8) + _analogueInputStates[_pinLSBByte]; } } return -1; // pin not found in table } // Obtain the correct digital input value int _read(VPIN vpin) override { if (_deviceState == DEVSTATE_FAILED) return 0; int pin = vpin - _firstVpin; uint8_t pinByte = pin / 8; bool value = bitRead(_digitalInputStates[pinByte], pin - pinByte * 8); return value; } // Write digital value. We could have an output buffer of states, that is periodically // written to the device if there are any changes; this would reduce the I2C overhead // if lots of output requests are being made. We could also cache the last value // sent so that we don't write the same value over and over to the output. // However, for the time being, we just write the current value (blocking I2C) to the // IOExpander node. As it is a blocking request, we can use buffers allocated from // the stack to save RAM allocation. void _write(VPIN vpin, int value) override { uint8_t digitalOutBuffer[3]; uint8_t responseBuffer[1]; if (_deviceState == DEVSTATE_FAILED) return; int pin = vpin - _firstVpin; digitalOutBuffer[0] = EXIOWRD; digitalOutBuffer[1] = pin; digitalOutBuffer[2] = value; uint8_t status = I2CManager.read(_I2CAddress, responseBuffer, 1, digitalOutBuffer, 3); if (status != I2C_STATUS_OK) { reportError(status); } else { if (responseBuffer[0] != EXIORDY) { DIAG(F("Vpin %u cannot be used as a digital output pin"), (int)vpin); } } } // Write analogue (integer) value. Write the parameters (blocking I2C) to the // IOExpander node. As it is a blocking request, we can use buffers allocated from // the stack to reduce RAM allocation. void _writeAnalogue(VPIN vpin, int value, uint8_t profile, uint16_t duration) override { uint8_t servoBuffer[7]; uint8_t responseBuffer[1]; if (_deviceState == DEVSTATE_FAILED) return; int pin = vpin - _firstVpin; #ifdef DIAG_IO DIAG(F("Servo: WriteAnalogue Vpin:%u Value:%d Profile:%d Duration:%d %S"), vpin, value, profile, duration, _deviceState == DEVSTATE_FAILED?F("DEVSTATE_FAILED"):F("")); #endif servoBuffer[0] = EXIOWRAN; servoBuffer[1] = pin; servoBuffer[2] = value & 0xFF; servoBuffer[3] = value >> 8; servoBuffer[4] = profile; servoBuffer[5] = duration & 0xFF; servoBuffer[6] = duration >> 8; uint8_t status = I2CManager.read(_I2CAddress, responseBuffer, 1, servoBuffer, 7); if (status != I2C_STATUS_OK) { DIAG(F("EX-IOExpander I2C:%s Error:%d %S"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status)); _deviceState = DEVSTATE_FAILED; } else { if (responseBuffer[0] != EXIORDY) { DIAG(F("Vpin %u cannot be used as a servo/PWM pin"), (int)vpin); } } } // Display device information and status. void _display() override { DIAG(F("EX-IOExpander I2C:%s v%d.%d.%d Vpins %u-%u %S"), _I2CAddress.toString(), _majorVer, _minorVer, _patchVer, (int)_firstVpin, (int)_firstVpin+_nPins-1, _deviceState == DEVSTATE_FAILED ? F("OFFLINE") : F("")); } // Helper function for error handling void reportError(uint8_t status, bool fail=true) { DIAG(F("EX-IOExpander I2C:%s Error:%d (%S)"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status)); if (fail) _deviceState = DEVSTATE_FAILED; } uint8_t _numDigitalPins = 0; uint8_t _numAnaloguePins = 0; uint8_t _majorVer = 0; uint8_t _minorVer = 0; uint8_t _patchVer = 0; uint8_t* _digitalInputStates = NULL; uint8_t* _analogueInputStates = NULL; uint8_t* _analogueInputBuffer = NULL; // buffer for I2C input transfers uint8_t _readCommandBuffer[1]; uint8_t _digitalPinBytes = 0; // Size of allocated memory buffer (may be longer than needed) uint8_t _analoguePinBytes = 0; // Size of allocated memory buffer (may be longer than needed) uint8_t* _analoguePinMap = NULL; I2CRB _i2crb; enum {RDS_IDLE, RDS_DIGITAL, RDS_ANALOGUE}; // Read operation states uint8_t _readState = RDS_IDLE; unsigned long _lastDigitalRead = 0; unsigned long _lastAnalogueRead = 0; const unsigned long _digitalRefresh = 10000UL; // Delay refreshing digital inputs for 10ms const unsigned long _analogueRefresh = 50000UL; // Delay refreshing analogue inputs for 50ms // EX-IOExpander protocol flags enum { EXIOINIT = 0xE0, // Flag to initialise setup procedure EXIORDY = 0xE1, // Flag we have completed setup procedure, also for EX-IO to ACK setup EXIODPUP = 0xE2, // Flag we're sending digital pin pullup configuration EXIOVER = 0xE3, // Flag to get version EXIORDAN = 0xE4, // Flag to read an analogue input EXIOWRD = 0xE5, // Flag for digital write EXIORDD = 0xE6, // Flag to read digital input EXIOENAN = 0xE7, // Flag to enable an analogue pin EXIOINITA = 0xE8, // Flag we're receiving analogue pin mappings EXIOPINS = 0xE9, // Flag we're receiving pin counts for buffers EXIOWRAN = 0xEA, // Flag we're sending an analogue write (PWM) EXIOERR = 0xEF, // Flag we've received an error }; }; #endif ================================================ FILE: IO_EXSensorCAM.h ================================================ /* 2024/08/14 * © 2024, Barry Daniel ESP32-CAM revision * * This file is part of EX-CommandStation * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #define driverVer 309 //devel 5.5.15+ only - specifically for Chris' mod // v309 includes changes for Chris' mod addVpin() Specifically for 5.5.15+ method with CAM v320+ // v308 allows v0 to give version without using '^'. CAM address identifier added to 'm' // " added check in Pkt[31] & shared inputBuf[32] "ACK OK" & case:'v'. Shows <> formats // " added setClock as per 307 devel version Note: v308 for 5.4.6+ Prod. only with CAM v320+ // v307 fix to 'p' cmd & CS cmd prompts. includes setClock(100000); // v306 Pass vpin to regeister it in CamParser. Incompatible with 5.4.0+ // " Move base vpin to camparser. devel 5.5.15+ only // v305 less debug & alpha ordered switch // v304 static oldb0; t(##[,%%]); // v303 zipped with CS 5.2.76 and uploaded to repo (with debug) // v302 SEND=StringFormatter::send, remove Sp(), add 'q', memcpy( .8) -> .7); // v301 improved 'f','p'&'q' code and driver version calc. Correct bsNo calc. for 'a' // v300 stripped & revised without expander functionality. Needs sensorCAM.h v300 AND CamParser.cpp // v200 rewrite reduces need for double reads of ESP32 slave CAM. Deleted ESP32CAP. // Inompatible with pre-v170 sensorCAM, unless set S06 to 0 and S07 to 1 (o06 & l07 say) /* * The IO_EXSensorCAM.h device driver can integrate with the sensorCAM device. * It is modelled on the IO_EXIOExpander.h device driver to include specific needs of the ESP32 sensorCAM * This device driver will configure the device on startup, along with CamParser.cpp * interacting with the sensorCAM device for all input/output duties. * * includes not required with devel 5.5.15+ * To create EX-SensorCAM devices, * use HAL(EXSensorCAM, baseVpin, numpins, i2c_address) in myAutomation.h * e.g. * HAL(EXSensorCAM,700, 80, 0x11) * * or (deprecated) define them in myHal.cpp: with * EXSensorCAM::create(baseVpin,num_vpins,i2c_address); * * I2C packet size of 32 bytes (in the Wire library). */ #define DIGITALREFRESH 20000UL // min uSec delay between digital reads of digitalInputStates #ifndef IO_EX_EXSENSORCAM_H #define IO_EX_EXSENSORCAM_H #define SEND StringFormatter::send #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" #include "FSH.h" #include "CamParser.h" ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for EX-SensorCAM. */ class EXSensorCAM : public IODevice { public: static void create(VPIN vpin, int nPins, I2CAddress i2cAddress) { if (checkNoOverlap(vpin, nPins, i2cAddress)) new EXSensorCAM(vpin, nPins, i2cAddress); } private: // Constructor EXSensorCAM(VPIN firstVpin, int nPins, I2CAddress i2cAddress) { _firstVpin = firstVpin; // Number of pins cannot exceed 255 (1 byte) because of I2C message structure. if (nPins > 80) nPins = 80; _nPins = nPins; _I2CAddress = i2cAddress; addDevice(this); CamParser::addVpin(firstVpin); } //************************* void _begin() { uint8_t status; // Initialise EX-SensorCAM device I2CManager.begin(); I2CManager.setClock(100000); // Set speed for I2C operations if (!I2CManager.exists(_I2CAddress)) { DIAG(F("EX-SensorCAM I2C:%s device not found"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; return; }else { uint8_t commandBuffer[4]={EXIOINIT,(uint8_t)_nPins,(uint8_t)(_firstVpin & 0xFF),(uint8_t)(_firstVpin>>8)}; status = I2CManager.read(_I2CAddress,_inputBuf,sizeof(_inputBuf),commandBuffer,sizeof(commandBuffer)); //EXIOINIT needed to trigger and send firstVpin to CAM if (status == I2C_STATUS_OK) { // Attempt to get version, non-blocking results in poor placement of response. Can be blocking here! commandBuffer[0] = '^'; //new version code status = I2CManager.read(_I2CAddress, _inputBuf, sizeof(_inputBuf), commandBuffer, 1); // for ESP32 CAM, read again for good immediate response version data status = I2CManager.read(_I2CAddress, _inputBuf, sizeof(_inputBuf), commandBuffer, 1); if (status == I2C_STATUS_OK) { _majorVer= _inputBuf[1]/10; _minorVer= _inputBuf[1]%10; _patchVer= _inputBuf[2]; DIAG(F("EX-SensorCAM device found, I2C:%s, Version v%d.%d.%d"), _I2CAddress.toString(),_majorVer, _minorVer,_patchVer); } } if (status != I2C_STATUS_OK) reportError(status); } } //************************* // Digital input pin configuration, used to enable on EX-IOExpander device and set pullups if requested. // Configuration isn't done frequently so we can use blocking I2C calls here, and so buffers can // be allocated from the stack to reduce RAM allocation. bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) override { (void)configType; (void)params; // unused if(_verPrint) DIAG(F("_configure() driver IO_EXSensorCAM v0.%d.%d vpin: %d "), driverVer/100,driverVer%100,vpin); _verPrint=false; //only give driver versions once if (paramCount != 1) return false; return true; //at least confirm that CAM is (always) configured (no vpin check!) } //************************* // Analogue input pin configuration, used to enable an EX-IOExpander device. int _configureAnalogIn(VPIN vpin) override { (void)vpin; // DIAG(F("_configureAnalogIn() IO_EXSensorCAM vpin %d"),vpin); return true; // NOTE: use of EXRAIL IFGTE() etc use "analog" reads. } //************************* // Main loop, collect both digital and "analog" pin states continuously (faster sensor/input reads) void _loop(unsigned long currentMicros) override { if (_deviceState == DEVSTATE_FAILED) return; // Request block is used for "analogue" (cmd. data) and digital reads from the sensorCAM, which // are performed on a cyclic basis. Writes are performed synchronously as and when requested. if (_readState != RDS_IDLE) { //expecting a return packet if (_i2crb.isBusy()) return; // If I2C operation still in progress, return uint8_t status = _i2crb.status; if (status == I2C_STATUS_OK) { // If device request ok, read input data //apparently the above checks do not guarantee a good packet! error rate about 1 pkt per 1000 //there should be a packet in _inputBuf[32] if ((_inputBuf[0] & 0x60) >= 0x60) { //Buff[0] seems to have ascii cmd header (bit6 high) (o06) int error = processIncomingPkt( _inputBuf, _inputBuf[0]); // '~' 'i' 'm' 'n' 't' etc if (error>0) DIAG(F("CAM packet header(0x%x) not recognised"),_inputBuf[0]); }else{ // Header not valid - typically replaced by bank 0 data! To avoid any bad responses set S06 to 0 // Versions of sensorCAM.h after v300 should return header for '@' of '`'(0x60) (not 0xE6) // followed by digitalInputStates sensor state array } }else reportError(status, false); // report i2c eror but don't go offline. _readState = RDS_IDLE; } // If we're not doing anything now, check to see if a new state table transfer, or for 't' repeat, is due. if (_readState == RDS_IDLE) { //check if time for digitalRefresh if ( currentMicros - _lastDigitalRead > _digitalRefresh) { // Issue new read request for digital states. _readCommandBuffer[0] = '@'; //start new read of digitalInputStates Table // non-blocking read I2CManager.read(_I2CAddress,_inputBuf, sizeof(_inputBuf),_readCommandBuffer, 1, &_i2crb); _lastDigitalRead = currentMicros; _readState = RDS_DIGITAL; }else{ //slip in a repeat if pending if (currentMicros - _lasttStateRead > _tStateRefresh) // Delay for "analog" command repetitions if (_savedCmd[2]>1) { //repeat a 't' command for (int i=0;i<7;i++) _readCommandBuffer[i] =_savedCmd[i]; int errors = ioESP32(_I2CAddress, _inputBuf, sizeof(_inputBuf), _readCommandBuffer, 7); _lasttStateRead = currentMicros; _savedCmd[2] -= 1; //decrement repeats if (errors==0) return; DIAG(F("ioESP32 error %d header 0x%x"),errors,_inputBuf[0]); _readState = RDS_TSTATE; //this should stop further cmd requests until packet read (or timeout) } } //end repeat 't' } } //************************* // Obtain the bank of 8 sensors as an "analog" value // can be used to track the position through a sequential sensor bank int _readAnalogue(VPIN vpin) override { if (_deviceState == DEVSTATE_FAILED) return 0; return _digitalInputStates[(vpin - _firstVpin) / 8]; } //************************* // Obtain the correct digital sensor input value int _read(VPIN vpin) override { if (_deviceState == DEVSTATE_FAILED) return 0; int pin = vpin - _firstVpin; return bitRead(_digitalInputStates[pin / 8], pin % 8); } //************************* // Write digital value. void _write(VPIN vpin, int value) override { DIAG(F("**_write() vpin %d = %d"),vpin,value); return ; } //************************* // i2cAddr of ESP32 CAM // rBuf buffer for return packet // inbytes number of bytes to request from CAM // outBuff holds outbytes to be sent to CAM int ioESP32(uint8_t i2cAddr,uint8_t *rBuf,int inbytes,uint8_t *outBuff,int outbytes) { uint8_t status = _i2crb.status; while( _i2crb.status != I2C_STATUS_OK){status = _i2crb.status;} //wait until bus free status = I2CManager.read(i2cAddr, rBuf, inbytes, outBuff, outbytes); if (status != I2C_STATUS_OK){ DIAG(F("EX-SensorCAM I2C:%s Error:%d %S"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status)); reportError(status); return status; } return 0; // 0 for no error != 0 for error number. } //************************* //function to interpret packet from sensorCAM.ino //i2cAddr to identify CAM# (if # >1) //rBuf contains packet of up to 32 bytes usually with (ascii) cmd header in rBuf[0] & check byte in [31] //sensorCmd command header byte from CAM (in rBuf[0]?) int processIncomingPkt(uint8_t *rBuf,uint8_t sensorCmd) { //static uint8_t oldb0; //for debug only int k; int b; char str[] = "11111111"; // if(sensorCmd != (rBuf[31] | 0x20)) { #ifdef BADPKTS Serial.print("mismatch31: "); Serial.print((char)sensorCmd);Serial.println(rBuf[31],HEX); #endif return 0; } switch (sensorCmd){ case '`': //response to request for digitalInputStates[] table '@'=>'`' memcpy(_digitalInputStates, rBuf+1, digitalBytesNeeded); break; case EXIORDY: //some commands give back acknowledgement only SEND(&USB_SERIAL,F("\n")); break; case CAMERR: //cmd format error code from CAM DIAG(F("CAM cmd error 0xFE 0x%x"),rBuf[1]); break; case 'v': case '~': //information from 'v/^' version request DIAG(F("EX-SensorCAM device found, I2C:%s,CAM Version v%d.%d.%d vpins %u-%u"), _I2CAddress.toString(), rBuf[1]/10, rBuf[1]%10, rBuf[2],(int) _firstVpin, (int) _firstVpin +_nPins-1); DIAG(F("IO_EXSensorCAM driver v0.%d.%d vpin: %d "), driverVer/100,driverVer%100,_firstVpin); break; case 'f': DIAG(F(" frame header 'f' for bsNo %d/%d - showing Quarter sample (1 row) only"), rBuf[1]/8,rBuf[1]%8); SEND(&USB_SERIAL,F(">4, rBuf[k]&15, k%3==2 ? " " : " "); Serial.print(" latest grab: "); for(k=16;k<28;k++) SEND(&USB_SERIAL,F("%x%x%s"), rBuf[k]>>4, rBuf[k]&15, (k%3==0) ? " " : " "); Serial.print(" n>\n"); break; case 'i': //information from i%% k=256*rBuf[5]+rBuf[4]; DIAG(F(" Info: Sensor 0%o(%d) enabled:%d status:%d row=%d x=%d Twin=0%o pvtThreshold=%d A~%d") ,rBuf[1],rBuf[1],rBuf[3],rBuf[2],rBuf[6],k,rBuf[7],rBuf[9],int(rBuf[8])*16); break; case 'm': DIAG(F("%s Min/max: $ frames min2flip (trip) %d, maxSensors 0%o, minSensors 0%o, nLED %d, thres" "hold %d, TWOIMAGE_MAXBS 0%o"),_I2CAddress.toString(),rBuf[1],rBuf[3],rBuf[2],rBuf[4],rBuf[5],rBuf[6]); break; case 'n': DIAG(F(" Numerate: $ nLED %d, ## minSensors 0%o (maxSensors 0%o threshold %d)") ,rBuf[4],rBuf[2],rBuf[3],rBuf[5]); break; case 'p': b=rBuf[1]-2; if(b<4) { Serial.print(" Bank empty n>\n"); break; } SEND(&USB_SERIAL,F(" Bank: %d "),(0x7F&rBuf[2])/8); for (int j=2; j\n"); break; case 'q': for (int i =0; i<8; i++) str[i] = ((rBuf[2] << i) & 0x80 ? '1' : '0'); DIAG(F(" Query bank %c ENABLED sensors(S%c7-%c0): %s "), rBuf[1], rBuf[1], rBuf[1], str); break; case 't': //threshold etc. from t## //bad pkt if 't' FF's if(rBuf[1]==0xFF) {Serial.println("");_savedCmd[2] +=1; return 0;} SEND(&USB_SERIAL,F(" Threshold:%d sensor S00:-%d"),rBuf[1],min(rBuf[2]&0x7F,99)); if(rBuf[2]>127) Serial.print("##* "); else{ if(rBuf[2]>rBuf[1]) Serial.print("-?* "); else Serial.print("--* "); } for(int i=3;i<31;i+=2){ uint8_t valu=rBuf[i]; //get bsn if(valu==80) break; //80 = end flag else{ SEND(&USB_SERIAL,F("%d%d:"), (valu&0x7F)/8,(valu&0x7F)%8); if(valu>=128) Serial.print("?-"); else {if(rBuf[i+1]>=128) Serial.print("oo");else Serial.print("--");} valu=rBuf[i+1]; SEND(&USB_SERIAL,F("%d%s"),min(valu&0x7F,99),(valu<128) ? "--* ":"##* "); } } Serial.print(" n>\n"); break; default: //header not a recognised cmd character DIAG(F("CAM packet header not valid (0x%x) (0x%x) (0x%x)"),rBuf[0],rBuf[1],rBuf[2]); return 1; } return 0; } //************************* // Write (analogue) 8bit (command) values. Write the parameters to the sensorCAM void _writeAnalogue(VPIN vpin, int param1, uint8_t camop, uint16_t param3) override { uint8_t outputBuffer[7]; int errors=0; outputBuffer[0] = camop; int pin = vpin - _firstVpin; if(camop >= 0x80) { //case "a" (4p) also (3p) e.g. camop=param1; //put row (0-236) in expected place param1=param3; //put column in expected place outputBuffer[0] = 'A'; pin = (pin/8)*10 + pin%8; //restore bsNo. as integer } if (_deviceState == DEVSTATE_FAILED) return; outputBuffer[1] = pin; //vpin => bsn outputBuffer[2] = param1 & 0xFF; outputBuffer[3] = param1 >> 8; outputBuffer[4] = camop; //command code outputBuffer[5] = param3 & 0xFF; outputBuffer[6] = param3 >> 8; int count=param1+1; if(camop=='Q'){ if(param3<=10) {count=param3; camop='B';} //if(param1<10) outputBuffer[2] = param1*10; } if(camop=='B'){ //then 'b'(b%) cmd - can totally deal with that here. (but can't do b%,# (brightSF)) if(param1>97) return; if(param1>9) param1 = param1/10; //accept a bsNo for(int bnk=param1;bnk Bank: %d activated byte: 0x%x%x (sensors S%d7->%d0) %s"), bnk,b>>4,b&15,bnk,bnk,str ); } return; } if (outputBuffer[4]=='T') { //then 't' cmd if(param1<31) { //repeated calls if param < 31 //for (int i=0;i<7;i++) _savedCmd[i]=outputBuffer[i]; memcpy( _savedCmd, outputBuffer, 7); }else _savedCmd[2] = 0; //no repeats if ##>30 }else _savedCmd[2] = 0; //no repeats unless 't' _lasttStateRead = micros(); //don't repeat until _tStateRefresh mSec errors = ioESP32(_I2CAddress, _inputBuf, sizeof(_inputBuf) , outputBuffer, 7); //send to esp32-CAM if (errors==0) return; else { // if (_inputBuf[0] != EXIORDY) //can't be sure what is inBuff[0] ! DIAG(F("ioESP32 i2c error %d header 0x%x"),errors,_inputBuf[0]); } } //************************* // Display device information and status. void _display() override { DIAG(F("EX-SensorCAM I2C:%s v%d.%d.%d Vpins %u-%u %S"), _I2CAddress.toString(), _majorVer, _minorVer, _patchVer, (int)_firstVpin, (int)_firstVpin+_nPins-1, _deviceState == DEVSTATE_FAILED ? F("OFFLINE") : F("")); } //************************* // Helper function for error handling void reportError(uint8_t status, bool fail=true) { DIAG(F("EX-SensorCAM I2C:%s Error:%d (%S)"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status)); if (fail) _deviceState = DEVSTATE_FAILED; } //************************* uint8_t _numDigitalPins = 80; size_t digitalBytesNeeded=10; uint8_t _inputBuf[32]; uint8_t _majorVer = 0; uint8_t _minorVer = 0; uint8_t _patchVer = 0; uint8_t _digitalInputStates[10]; I2CRB _i2crb; byte _outputBuffer[8]; bool _verPrint=true; uint8_t _readCommandBuffer[8]; uint8_t _savedCmd[8]; //for repeat 't' command //uint8_t _digitalPinBytes = 10; // Size of allocated memory buffer (may be longer than needed) enum {RDS_IDLE, RDS_DIGITAL, RDS_TSTATE}; // Read operation states uint8_t _readState = RDS_IDLE; //uint8_t cmdBuffer[7]={0,0,0,0,0,0,0}; unsigned long _lastDigitalRead = 0; unsigned long _lasttStateRead = 0; unsigned long _digitalRefresh = DIGITALREFRESH; // Delay refreshing digital inputs for 10ms const unsigned long _tStateRefresh = 120000UL; // Delay refreshing repeat "tState" inputs enum { EXIOINIT = 0xE0, // Flag to initialise setup procedure EXIORDY = 0xE1, // Flag we have completed setup procedure, also for EX-IO to ACK setup CAMERR = 0xFE }; }; #endif ================================================ FILE: IO_EXTurntable.cpp ================================================ /* * © 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 . */ /* * The IO_EXTurntable device driver is used to control a turntable via an Arduino with a stepper motor over I2C. * * The EX-Turntable code lives in a separate repo (https://github.com/DCC-EX/EX-Turntable) and contains the stepper motor logic. * * This device driver sends a step position to EX-Turntable to indicate the step position to move to using either of these commands: * in the serial console * MOVETT(vpin, steps, activity) in EX-RAIL * Refer to the documentation for further information including the valid activities. */ #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" #include "Turntables.h" #include "CommandDistributor.h" #ifndef IO_NO_HAL void EXTurntable::create(VPIN firstVpin, int nPins, I2CAddress I2CAddress) { new EXTurntable(firstVpin, nPins, I2CAddress); } // Constructor EXTurntable::EXTurntable(VPIN firstVpin, int nPins, I2CAddress I2CAddress) { _firstVpin = firstVpin; _nPins = nPins; _I2CAddress = I2CAddress; _stepperStatus = 0; _previousStatus = 0; addDevice(this); } // Initialisation of EXTurntable void EXTurntable::_begin() { I2CManager.begin(); if (I2CManager.exists(_I2CAddress)) { DIAG(F("EX-Turntable device found, I2C:%s"), _I2CAddress.toString()); #ifdef DIAG_IO _display(); #endif } else { DIAG(F("EX-Turntable I2C:%s device not found"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; } } // Processing loop to obtain status of stepper // 0 = finished moving and in correct position // 1 = still moving void EXTurntable::_loop(unsigned long currentMicros) { uint8_t readBuffer[1]; I2CManager.read(_I2CAddress, readBuffer, 1); _stepperStatus = readBuffer[0]; if (_stepperStatus != _previousStatus && _stepperStatus == 0) { // Broadcast when a rotation finishes if ( _currentActivity < 4) { _broadcastStatus(_firstVpin, _stepperStatus, _currentActivity); } _previousStatus = _stepperStatus; } delayUntil(currentMicros + 100000); // Wait 100ms before checking again } // Read returns status as obtained in our loop. // Return false if our status value is invalid. int EXTurntable::_read(VPIN vpin) { (void)vpin; // surpress warning if (_deviceState == DEVSTATE_FAILED) return 0; if (_stepperStatus > 1) { return false; } else { return _stepperStatus; } } // If a status change has occurred for a turntable object, broadcast it void EXTurntable::_broadcastStatus (VPIN vpin, uint8_t status, uint8_t activity) { Turntable *tto = Turntable::getByVpin(vpin); if (tto) { if (activity < 4) { tto->setMoving(status); CommandDistributor::broadcastTurntable(tto->getId(), tto->getPosition(), status); } } } // writeAnalogue to send the steps and activity to Turntable-EX. // Sends 3 bytes containing the MSB and LSB of the step count, and activity. // value contains the steps, bit shifted to MSB + LSB. // activity contains the activity flag as per this list: // // Turn = 0, // Rotate turntable, maintain phase // Turn_PInvert = 1, // Rotate turntable, invert phase // Home = 2, // Initiate homing // Calibrate = 3, // Initiate calibration sequence // LED_On = 4, // Turn LED on // LED_Slow = 5, // Set LED to a slow blink // LED_Fast = 6, // Set LED to a fast blink // LED_Off = 7, // Turn LED off // Acc_On = 8, // Turn accessory pin on // Acc_Off = 9 // Turn accessory pin off void EXTurntable::_writeAnalogue(VPIN vpin, int value, uint8_t activity, uint16_t duration) { if (_deviceState == DEVSTATE_FAILED) return; if (value < 0) return; uint8_t stepsMSB = value >> 8; uint8_t stepsLSB = value & 0xFF; #ifdef DIAG_IO DIAG(F("EX-Turntable WriteAnalogue VPIN:%u Value:%d Activity:%d Duration:%d"), vpin, value, activity, duration); DIAG(F("I2CManager write I2C Address:%d stepsMSB:%d stepsLSB:%d activity:%d"), _I2CAddress.toString(), stepsMSB, stepsLSB, activity); #else (void)duration; #endif if (activity < 4) _stepperStatus = 1; // Tell the device driver Turntable-EX is busy _previousStatus = _stepperStatus; _currentActivity = activity; _broadcastStatus(vpin, _stepperStatus, activity); // Broadcast when the rotation starts I2CManager.write(_I2CAddress, 3, stepsMSB, stepsLSB, activity); } // Display Turnetable-EX device driver info. void EXTurntable::_display() { DIAG(F("EX-Turntable I2C:%s Configured on Vpins:%u-%u %S"), _I2CAddress.toString(), (int)_firstVpin, (int)_firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F("")); } #endif ================================================ FILE: IO_EncoderThrottle.cpp ================================================ /* * © 2024, Chris Harlow. All rights reserved. * * This file is part of EX-CommandStation * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * The IO_EncoderThrottle device driver uses a rotary encoder connected to vpins * to drive a loco. * Loco id is selected by writeAnalog. */ #include "IODevice.h" #include "IO_EncoderThrottle.h" #include "DIAG.h" #include "DCC.h" const byte _DIR_CW = 0x10; // Clockwise step const byte _DIR_CCW = 0x20; // Counter-clockwise step const byte transition_table[5][4]= { {0,1,3,0}, // 0: 00 {1,1,1,2 | _DIR_CW}, // 1: 00->01 {2,2,0,2}, // 2: 00->01->11 {3,3,3,4 | _DIR_CCW}, // 3: 00->10 {4,0,4,4} // 4: 00->10->11 }; const byte _STATE_MASK = 0x07; const byte _DIR_MASK = 0x30; void EncoderThrottle::create(VPIN firstVpin, int dtPin, int clkPin, int clickPin, byte notch) { if (checkNoOverlap(firstVpin)) new EncoderThrottle(firstVpin, dtPin,clkPin,clickPin,notch); } // Constructor EncoderThrottle::EncoderThrottle(VPIN firstVpin, int dtPin, int clkPin, int clickPin, byte notch){ _firstVpin = firstVpin; _nPins = 1; _I2CAddress = 0; _dtPin=dtPin; _clkPin=clkPin; _clickPin=clickPin; _notch=notch; _locoid=0; _stopState=xrSTOP; _rocoState=0; _prevpinstate=4; // not 01..11 IODevice::configureInput(dtPin,true); IODevice::configureInput(clkPin,true); IODevice::configureInput(clickPin,true); addDevice(this); _display(); } void EncoderThrottle::_loop(unsigned long currentMicros) { (void) currentMicros; // suppress warning if (_locoid==0) return; // not in use // Clicking down on the roco, stops the loco and sets the direction as unknown. if (IODevice::read(_clickPin)) { if (_stopState==xrSTOP) return; // debounced multiple stops DCC::setThrottle(_locoid,1,DCC::getThrottleDirection(_locoid)); _stopState=xrSTOP; DIAG(F("DRIVE %d STOP"),_locoid); return; } // read roco pins and detect state change byte pinstate = (IODevice::read(_dtPin) << 1) | IODevice::read(_clkPin); if (pinstate==_prevpinstate) return; _prevpinstate=pinstate; _rocoState = transition_table[_rocoState & _STATE_MASK][pinstate]; if ((_rocoState & _DIR_MASK) == 0) return; // no value change int change=(_rocoState & _DIR_CW)?+1:-1; // handle roco change -1 or +1 (clockwise) if (_stopState==xrSTOP) { // first move after button press sets the direction. (clockwise=fwd) _stopState=change>0?xrFWD:xrREV; } // when going fwd, clockwise increases speed. // but when reversing, anticlockwise increases speed. // This is similar to a center-zero pot control but with // the added safety that you cant panic-spin into the other // direction. if (_stopState==xrREV) change=-change; // manage limits int oldspeed=DCC::getThrottleSpeed(_locoid); if (oldspeed==1)oldspeed=0; // break out of estop int newspeed=change>0 ? (min((oldspeed+_notch),126)) : (max(0,(oldspeed-_notch))); if (newspeed==1) newspeed=0; // normal decelereated stop. if (oldspeed!=newspeed) { DIAG(F("DRIVE %d notch %S %d %S"),_locoid, change>0?F("UP"):F("DOWN"),_notch, _stopState==xrFWD?F("FWD"):F("REV")); DCC::setThrottle(_locoid,newspeed,_stopState==xrFWD); } } // Set locoid as analog value to start drive // use void EncoderThrottle::_writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t param2) { (void)vpin; // not used, but needed to match IODevice interface (void) param2; _locoid=value; if (param1>0) _notch=param1; _rocoState=0; // If loco is moving, we inherit direction from it. _stopState=xrSTOP; if (_locoid>0) { auto speedbyte=DCC::getThrottleSpeedByte(_locoid); if ((speedbyte & 0x7f) >1) { // loco is moving _stopState= (speedbyte & 0x80)?xrFWD:xrREV; } } _display(); } void EncoderThrottle::_display() { DIAG(F("DRIVE vpin %d loco %d notch %d"),_firstVpin,_locoid,_notch); } ================================================ FILE: IO_EncoderThrottle.h ================================================ /* * © 2024, Chris Harlow. All rights reserved. * * This file is part of EX-CommandStation * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * The IO_EncoderThrottle device driver uses a rotary encoder connected to vpins * to drive a loco. * Loco id is selected by writeAnalog. */ #ifndef IO_EncoderThrottle_H #define IO_EncoderThrottle_H #include "IODevice.h" class EncoderThrottle : public IODevice { public: static void create(VPIN firstVpin, int dtPin, int clkPin, int clickPin, byte notch=10); private: int _dtPin,_clkPin,_clickPin, _locoid, _notch,_prevpinstate; enum {xrSTOP,xrFWD,xrREV} _stopState; byte _rocoState; // Constructor EncoderThrottle(VPIN firstVpin, int dtPin, int clkPin, int clickPin, byte notch); void _loop(unsigned long currentMicros) override ; // Selocoid as analog value to start drive // use void _writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t param2) override; void _display() override ; }; #endif ================================================ FILE: IO_ExampleSerial.h ================================================ /* * © 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 . */ /* * To declare a device instance, * IO_ExampleSerial myDevice(1000, 10, Serial3, 9600); * or to create programmatically, * IO_ExampleSerial::create(1000, 10, Serial3, 9600); * * (uses VPINs 1000-1009, talke on Serial 3 at 9600 baud.) * * See IO_ExampleSerial.cpp for the protocol used over the serial line. * */ #ifndef IO_EXAMPLESERIAL_H #define IO_EXAMPLESERIAL_H #include "IODevice.h" class IO_ExampleSerial : public IODevice { 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 ================================================ FILE: IO_GPIOBase.h ================================================ /* * © 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 . */ #ifndef IO_GPIOBASE_H #define IO_GPIOBASE_H #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" // GPIOBase is defined as a class template. This allows it to be instantiated by // subclasses with different types, according to the number of pins on the GPIO module. // For example, GPIOBase for 8 pins, GPIOBase for 16 pins etc. // A module with up to 64 pins can be handled in this way (uint64_t). template class GPIOBase : public IODevice { protected: // Constructor GPIOBase(FSH *deviceName, VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin); // Device-specific initialisation void _begin() override; // Device-specific pin configuration function. bool _configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) override; // Pin write function. void _write(VPIN vpin, int value) override; // Pin read function. int _read(VPIN vpin) override; void _display() override; void _loop(unsigned long currentMicros) override; // Data fields // Allocate enough space for all input pins 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; virtual void _readGpioPort(bool immediate=true) = 0; virtual void _writePullups() {}; virtual void _writePortModes() {}; virtual void _setupDevice() {}; virtual void _processCompletion(uint8_t status) { (void)status; // Suppress compiler warning }; I2CRB requestBlock; FSH *_deviceName; }; // Because class GPIOBase is a template, the implementation (below) must be contained within the same // file as the class declaration (above). Otherwise it won't compile! // Constructor template GPIOBase::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; _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 void GPIOBase::_begin() { // Configure pin used for GPIO extender notification of change (if allocated) if (_gpioInterruptPin >= 0) pinMode(_gpioInterruptPin, INPUT_PULLUP); I2CManager.begin(); I2CManager.setClock(400000); if (I2CManager.exists(_I2CAddress)) { #if defined(DIAG_IO) _display(); #endif _setupDevice(); _deviceState = DEVSTATE_NORMAL; } else { DIAG(F("%S I2C:%s Device not detected"), _deviceName, _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; } } // Configuration parameters for inputs: // params[0]: enable pullup template bool GPIOBase::_configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) { if (configType != CONFIGURE_INPUT) return false; if (paramCount == 0 || paramCount > 1) return false; bool pullup = params[0]; int pin = vpin - _firstVpin; #ifdef DIAG_IO DIAG(F("%S I2C:%s Config Pin:%d Val:%d"), _deviceName, _I2CAddress.toString(), pin, pullup); #endif uint16_t mask = 1 << pin; if (pullup) _portPullup |= mask; else _portPullup &= ~mask; // Mark that port has been accessed _portInUse |= mask; // Set input mode _portMode &= ~mask; // Call subclass's virtual function to write to device _writePortModes(); _writePullups(); // Port change will be notified on next loop entry. return true; } // Periodically read the input port template void GPIOBase::_loop(unsigned long currentMicros) { T lastPortStates = _portInputState; if (_deviceState == DEVSTATE_SCANNING && !requestBlock.isBusy()) { uint8_t status = requestBlock.status; if (status == I2C_STATUS_OK) { _deviceState = DEVSTATE_NORMAL; } else { _deviceState = DEVSTATE_FAILED; DIAG(F("%S I2C:%s Error:%d %S"), _deviceName, _I2CAddress.toString(), status, I2CManager.getErrorMessage(status)); } _processCompletion(status); // Set unused pin and write mode pin value to 1 _portInputState |= ~_portInUse | _portMode; // Scan for changes in input states and invoke callback (if present) T differences = lastPortStates ^ _portInputState; if (differences && IONotifyCallback::hasCallback()) { // Scan for differences bit by bit T mask = 1; for (int pin=0; pin<_nPins; pin++) { if (differences & mask) { // Change detected. IONotifyCallback::invokeAll(_firstVpin+pin, (_portInputState & mask) == 0); } mask <<= 1; } } #ifdef DIAG_IO if (differences) DIAG(F("%S I2C:%s PortStates:%x"), _deviceName, _I2CAddress.toString(), _portInputState); #endif } // Check if interrupt configured. If not, or if it is active (pulled down), then // initiate a scan. if (_gpioInterruptPin < 0 || !digitalRead(_gpioInterruptPin)) { // TODO: Could suppress reads if there are no pins configured as inputs! // Read input if (_deviceState == DEVSTATE_NORMAL) { _readGpioPort(false); // Initiate non-blocking read _deviceState= DEVSTATE_SCANNING; } } // Delay next entry until tick elapsed. delayUntil(currentMicros + _portTickTime); } template void GPIOBase::_display() { DIAG(F("%S I2C:%s Configured on Vpins:%u-%u %S"), _deviceName, _I2CAddress.toString(), _firstVpin, _firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F("")); } template void GPIOBase::_write(VPIN vpin, int value) { int pin = vpin - _firstVpin; T mask = 1 << pin; #ifdef DIAG_IO 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 if (!(_portMode & mask)) { _portInUse |= mask; _portMode |= mask; _writePortModes(); } // Update port output state if (value) _portOutputState |= mask; else _portOutputState &= ~mask; // Call subclass's virtual function to write to device. return _writeGpioPort(); } template int GPIOBase::_read(VPIN vpin) { int pin = vpin - _firstVpin; T mask = 1 << pin; // Set port mode to input if currently output or first use if ((_portMode | ~_portInUse) & mask) { _portMode &= ~mask; _portInUse |= mask; _writePullups(); _writePortModes(); // Port won't have been read yet, so read it now. _readGpioPort(); // Set unused pin and write mode pin value to 1 _portInputState |= ~_portInUse | _portMode; #ifdef DIAG_IO DIAG(F("%S I2C:%s PortStates:%x"), _deviceName, _I2CAddress.toString(), _portInputState); #endif } return (_portInputState & mask) ? 0 : 1; // Invert state (5v=0, 0v=1) } #endif ================================================ FILE: IO_HALDisplay.h ================================================ /* * © 2024, Paul Antoine * © 2023, Neil McKechnie * All rights reserved. * * This file is part of DCC-EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * 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::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::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 HALDisplay : public IODevice, public DisplayInterface { private: // Here we define the device-specific variables. uint8_t _height; // in pixels uint8_t _width; // in pixels T *_displayDriver; uint8_t _rowNo = 0; // Row number being written by caller uint8_t _colNo = 0; // Position in line being written by caller uint8_t _numRows; uint8_t _numCols; char *_buffer = NULL; uint8_t *_rowGeneration = NULL; uint8_t *_lastRowGeneration = NULL; uint8_t _rowNoToScreen = 0; uint8_t _charPosToScreen = 0; bool _startAgain = false; DisplayInterface *_nextDisplay = NULL; public: // Static function to handle "HALDisplay::create(...)" calls. static void create(I2CAddress i2cAddress, int width, int height) { if (checkNoOverlap(0, 0, i2cAddress)) new HALDisplay(0, i2cAddress, width, height); } static void create(uint8_t displayNo, I2CAddress i2cAddress, int width, int height) { if (checkNoOverlap(0, 0, i2cAddress)) new HALDisplay(displayNo, i2cAddress, width, height); } protected: // Constructor HALDisplay(uint8_t displayNo, I2CAddress i2cAddress, int width, int height) { _displayDriver = new T(i2cAddress, width, height); if (!_displayDriver) return; // Check for memory allocation failure _I2CAddress = i2cAddress; _width = width; _height = height; _numCols = _displayDriver->getNumCols(); _numRows = _displayDriver->getNumRows(); _charPosToScreen = _numCols; // Allocate arrays _buffer = (char *)calloc(_numRows*_numCols, sizeof(char)); if (!_buffer) return; // Check for memory allocation failure _rowGeneration = (uint8_t *)calloc(_numRows, sizeof(uint8_t)); if (!_rowGeneration) return; // Check for memory allocation failure _lastRowGeneration = (uint8_t *)calloc(_numRows, sizeof(uint8_t)); if (!_lastRowGeneration) return; // Check for memory allocation failure // Fill buffer with spaces memset(_buffer, ' ', _numCols*_numRows); // Add device to list of HAL devices (not necessary but allows // status to be displayed using and device to be // reinitialised using ). IODevice::addDevice(this); // Moved after addDevice() to ensure I2CManager.begin() has been called fisrt _displayDriver->clearNative(); // Also add this display to list of display handlers DisplayInterface::addDisplay(displayNo); // Is this the system display (0)? if (displayNo == 0) { // Set first two lines on screen this->setRow(displayNo, 0); print(F("DCC-EX v")); print(F(VERSION)); setRow(displayNo, 1); print(F("Lic GPLv3")); } } void screenUpdate() { // Loop through the buffer and if a row has changed // (rowGeneration[row] is changed) then start writing the // characters from the buffer, one character per entry, // to the screen until that row has been refreshed. // First check if the OLED driver is still busy from a previous // call. If so, don't do anything until the next entry. if (!_displayDriver->isBusy()) { // Check if we've just done the end of a row if (_charPosToScreen >= _numCols) { // Move to next line if (++_rowNoToScreen >= _numRows || _startAgain) { _rowNoToScreen = 0; // Wrap to first row _startAgain = false; } if (_rowGeneration[_rowNoToScreen] != _lastRowGeneration[_rowNoToScreen]) { // Row content has changed, so start outputting it _lastRowGeneration[_rowNoToScreen] = _rowGeneration[_rowNoToScreen]; _displayDriver->setRowNative(_rowNoToScreen); _charPosToScreen = 0; // Prepare to output first character on next entry } else { // Row not changed, don't bother writing it. } } else { // output character at current position _displayDriver->writeNative(_buffer[_rowNoToScreen*_numCols+_charPosToScreen++]); } } return; } ///////////////////////////////////////////////// // IODevice Class Member Overrides ///////////////////////////////////////////////// // Device-specific initialisation void _begin() override { // Initialise device if (_displayDriver->begin()) { _display(); // Force all rows to be redrawn for (uint8_t row=0; row<_numRows; row++) _rowGeneration[row]++; // Start with top line (looks better). // The numbers will wrap round on the first loop2 entry. _rowNoToScreen = _numRows; _charPosToScreen = _numCols; } } void _loop(unsigned long) override { screenUpdate(); } // Display information about the device. void _display() { DIAG(F("HALDisplay %d configured on addr %s"), _displayNo, _I2CAddress.toString()); } ///////////////////////////////////////////////// // DisplayInterface functions // ///////////////////////////////////////////////// public: void _displayLoop() override { screenUpdate(); } // Position on nominated line number (0 to number of lines -1) // Clear the line in the buffer ready for updating // The displayNo referenced here is remembered and any following // calls to write() will be directed to that display. void _setRow(byte line) override { if (line == 255) { // LCD(255,"xxx") or SCREEN(displayNo,255, "xxx") - // scroll the contents of the buffer and put the new line // at the bottom of the screen for (int row=1; row<_numRows; row++) { strncpy(&_buffer[(row-1)*_numCols], &_buffer[row*_numCols], _numCols); _rowGeneration[row-1]++; } line = _numRows-1; } else if (line >= _numRows) line = _numRows - 1; // Overwrite bottom line. _rowNo = line; // Fill line with blanks for (_colNo = 0; _colNo < _numCols; _colNo++) _buffer[_rowNo*_numCols+_colNo] = ' '; _colNo = 0; // Mark that the buffer has been touched. It will start being // sent to the screen on the next loop entry, by which time // the line should have been written to the buffer. _rowGeneration[_rowNo]++; // Indicate that the output loop is to start updating the screen again from // row 0. Otherwise, on a full screen rewrite the bottom part may be drawn // before the top part! _startAgain = true; } // Write one character to the screen referenced in the last setRow() call. virtual size_t _write(uint8_t c) override { // Write character to buffer (if there's space) if (_colNo < _numCols) { _buffer[_rowNo*_numCols+_colNo++] = c; } return 1; } // Write blanks to all of the screen buffer void _clear() { // Clear buffer memset(_buffer, ' ', _numCols*_numRows); _colNo = 0; _rowNo = 0; } }; #endif // IO_HALDisplay_H ================================================ FILE: IO_HCSR04.h ================================================ /* * © 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 . */ /* * The HC-SR04 module has an ultrasonic transmitter (40kHz) and a receiver. * It is operated through two signal pins. When the transmit pin is set to 1 * for 10us, on the falling edge the transmitter sends a short transmission of * 8 pulses (like a sonar 'ping'). This is reflected off objects and received * by the receiver. A pulse is sent on the receive pin whose length is equal * to the delay between the transmission of the pulse and the detection of * its echo. The distance of the reflecting object is calculated by halving * the time (to allow for the out and back distance), then multiplying by the * speed of sound (assumed to be constant). * * 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 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 * offThreshold. * * It might be thought that the measurement would be more reliable if interrupts * were disabled while the pulse is being timed. However, this would affect * other functions in the CS so the measurement is being performed with * interrupts enabled. Also, we could use an interrupt pin in the Arduino for * the timing, but the same consideration applies. In any case, the DCC * interrupt occurs once every 58us, so any IRC code is much faster than that. * And 58us corresponds to 1cm in the calculation, so the effect of * interrupts is negligible. * * 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 #define IO_HCSR04_H #include "IODevice.h" class HCSR04 : public IODevice { 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. uint8_t _onThreshold; // cm uint8_t _offThreshold; // cm // Last measured distance in cm. uint16_t _distance; // Active=1/inactive=0 _state uint8_t _value = 0; // 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; // 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: 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); } // _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); #if defined(DIAG_IO) _display(); #endif } // _read function - just return _value (calculated in _loop). int _read(VPIN vpin) override { (void)vpin; // avoid compiler warning return _value; } int _readAnalogue(VPIN vpin) override { (void)vpin; // avoid compiler warning return _distance; } // _loop function - read HC-SR04 once every 100 milliseconds. void _loop(unsigned long currentMicros) override { 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:%u TrigPin:%d EchoPin:%d On:%dcm Off:%dcm"), _firstVpin, _trigPin, _echoPin, _onThreshold, _offThreshold); } }; #endif //IO_HCSR04_H ================================================ FILE: IO_I2CDFPlayer-OBSOLETE.h ================================================ /* * © 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 . */ /* * DFPlayer is an MP3 player module with an SD card holder. It also has an integrated * amplifier, so it only needs a power supply and a speaker. * This driver is a modified version of the IO_DFPlayer.h file * ********************************************************************************************* * * Dec 2023, Added NXP SC16IS752 I2C Dual UART to enable the DFPlayer connection over the I2C bus * The SC16IS752 has 64 bytes TX & RX FIFO buffer * First version without interrupts from I2C UART and only RX/TX are used, interrupts may not be * needed as the RX Fifo holds the reply * * Jan 2024, Issue with using both UARTs simultaniously, the secod uart seems to work but the first transmit * corrupt data. This need more analysis and experimenatation. * Will push this driver to the dev branch with the uart fixed to 0 * Both SC16IS750 (single uart) and SC16IS752 (dual uart, but only uart 0 is enable) * * myHall.cpp configuration syntax: * * I2CDFPlayer::create(1st vPin, vPins, I2C address, xtal); * * Parameters: * 1st vPin : First virtual pin that EX-Rail can control to play a sound, use PLAYSOUND command (alias of ANOUT) * vPins : Total number of virtual pins allocated (2 vPins are supported, one for each UART) * 1st vPin for UART 0, 2nd for UART 1 * I2C Address : I2C address of the serial controller, in 0x format * xtal : 0 for 1,8432Mhz, 1 for 14,7456Mhz * * The vPin is also a pin that can be read, it indicate if the DFPlayer has finished playing a track * */ #ifndef IO_I2CDFPlayer_h #define IO_I2CDFPlayer_h #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" // Debug and diagnostic defines, enable too many will result in slowing the driver //#define DIAG_I2CDFplayer //#define DIAG_I2CDFplayer_data //#define DIAG_I2CDFplayer_reg //#define DIAG_I2CDFplayer_playing class I2CDFPlayer : public IODevice { private: const uint8_t MAXVOLUME=30; uint8_t RETRYCOUNT = 0x03; bool _playing = false; uint8_t _inputIndex = 0; unsigned long _commandSendTime; // Time (us) that last transmit took place. unsigned long _timeoutTime; uint8_t _recvCMD; // Last received command code byte bool _awaitingResponse = false; uint8_t _retryCounter = RETRYCOUNT; // Max retries before timing out uint8_t _requestedVolumeLevel = MAXVOLUME; uint8_t _currentVolume = MAXVOLUME; int _requestedSong = -1; // -1=none, 0=stop, >0=file number bool _repeat = false; // audio file is repeat playing uint8_t _previousCmd = true; // SC16IS752 defines I2CAddress _I2CAddress; I2CRB _rb; uint8_t _UART_CH=0x00; // Fix uart ch to 0 for now // Communication parameters for the DFPlayer are fixed at 8 bit, No parity, 1 stopbit uint8_t WORD_LEN = 0x03; // Value LCR bit 0,1 uint8_t STOP_BIT = 0x00; // Value LCR bit 2 uint8_t PARITY_ENA = 0x00; // Value LCR bit 3 uint8_t PARITY_TYPE = 0x00; // Value LCR bit 4 uint32_t BAUD_RATE = 9600; uint8_t PRESCALER = 0x01; // Value MCR bit 7 uint8_t TEMP_REG_VAL = 0x00; uint8_t FIFO_RX_LEVEL = 0x00; uint8_t RX_BUFFER = 0x00; // nr of bytes copied into _inbuffer uint8_t FIFO_TX_LEVEL = 0x00; bool _playCmd = false; bool _volCmd = false; bool _folderCmd = false; uint8_t _requestedFolder = 0x01; // default to folder 01 uint8_t _currentFolder = 0x01; // default to folder 01 bool _repeatCmd = false; bool _stopplayCmd = false; bool _resetCmd = false; bool _eqCmd = false; uint8_t _requestedEQValue = DF_NORMAL; uint8_t _currentEQvalue = DF_NORMAL; // start equalizer value bool _daconCmd = false; uint8_t _audioMixer = 0x01; // Default to output amplifier 1 bool _setamCmd = false; // Set the Audio mixer channel uint8_t _outbuffer [11]; // DFPlayer command is 10 bytes + 1 byte register address & UART channel uint8_t _inbuffer[10]; // expected DFPlayer return 10 bytes unsigned long _sc16is752_xtal_freq; unsigned long SC16IS752_XTAL_FREQ_LOW = 1843200; // To support cheap eBay/AliExpress SC16IS752 boards unsigned long SC16IS752_XTAL_FREQ_HIGH = 14745600; // Support for higher baud rates, standard for modular EX-IO system public: // Constructor I2CDFPlayer(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint8_t xtal){ _firstVpin = firstVpin; _nPins = nPins; _I2CAddress = i2cAddress; if (xtal == 0){ _sc16is752_xtal_freq = SC16IS752_XTAL_FREQ_LOW; } else { // should be 1 _sc16is752_xtal_freq = SC16IS752_XTAL_FREQ_HIGH; } addDevice(this); } public: static void create(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint8_t xtal) { if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new I2CDFPlayer(firstVpin, nPins, i2cAddress, xtal); } void _begin() override { // check if SC16IS752 exist first, initialize and then resume DFPlayer init via SC16IS752 I2CManager.begin(); I2CManager.setClock(1000000); if (I2CManager.exists(_I2CAddress)){ DIAG(F("SC16IS752 I2C:%s UART detected"), _I2CAddress.toString()); Init_SC16IS752(); // Initialize UART if (_deviceState == DEVSTATE_FAILED){ DIAG(F("SC16IS752 I2C:%s UART initialization failed"), _I2CAddress.toString()); } } else { DIAG(F("SC16IS752 I2C:%s UART not detected"), _I2CAddress.toString()); } #if defined(DIAG_IO) _display(); #endif // Now init DFPlayer // Send a query to the device to see if it responds _deviceState = DEVSTATE_INITIALISING; sendPacket(0x42,0,0); _timeoutTime = micros() + 5000000UL; // 5 second timeout _awaitingResponse = true; } void _loop(unsigned long currentMicros) override { // Read responses from device uint8_t status = _rb.status; if (status == I2C_STATUS_PENDING) return; // Busy, so don't do anything if (status == I2C_STATUS_OK) { processIncoming(currentMicros); // Check if a command sent to device has timed out. Allow 0.5 second for response // added retry counter, sometimes we do not sent keep alive due to other commands sent to DFPlayer if (_awaitingResponse && (int32_t)(currentMicros - _timeoutTime) > 0) { // timeout triggered if(_retryCounter == 0){ // retry counter out of luck, must take the device to failed state DIAG(F("I2CDFPlayer:%s, DFPlayer not responding on UART channel: 0x%x"), _I2CAddress.toString(), _UART_CH); _deviceState = DEVSTATE_FAILED; _awaitingResponse = false; _playing = false; _retryCounter = RETRYCOUNT; } else { // timeout and retry protection and recovery of corrupt data frames from DFPlayer #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: %s, DFPlayer timout, retry counter: %d on UART channel: 0x%x"), _I2CAddress.toString(), _retryCounter, _UART_CH); #endif _timeoutTime = currentMicros + 5000000UL; // Timeout if no response within 5 seconds// reset timeout _awaitingResponse = false; // trigger sending a keep alive 0x42 in processOutgoing() _retryCounter --; // decrement retry counter resetRX_fifo(); // reset the RX fifo as it has corrupt data } } } status = _rb.status; if (status == I2C_STATUS_PENDING) return; // Busy, try next time if (status == I2C_STATUS_OK) { // Send any commands that need to go. processOutgoing(currentMicros); } delayUntil(currentMicros + 10000); // Only enter every 10ms } // Check for incoming data, and update busy flag and other state accordingly void processIncoming(unsigned long currentMicros) { (void)currentMicros; // suppress warning, not used in this function // Expected message is in the form "7E FF 06 3D xx xx xx xx xx EF" RX_fifo_lvl(); if (FIFO_RX_LEVEL >= 10) { #ifdef DIAG_I2CDFplayer DIAG(F("I2CDFPlayer: %s Retrieving data from RX Fifo on UART_CH: 0x%x FIFO_RX_LEVEL: %d"),_I2CAddress.toString(), _UART_CH, FIFO_RX_LEVEL); #endif _outbuffer[0] = REG_RHR << 3 | _UART_CH << 1; // Only copy 10 bytes from RX FIFO, there maybe additional partial return data after a track is finished playing in the RX FIFO I2CManager.read(_I2CAddress, _inbuffer, 10, _outbuffer, 1); // inbuffer[] has the data now //delayUntil(currentMicros + 10000); // Allow time to get the data RX_BUFFER = 10; // We have copied 10 bytes from RX FIFO to _inbuffer #ifdef DIAG_I2CDFplayer_data DIAG(F("SC16IS752: At I2C: %s, UART channel: 0x%x, RX FIFO Data"), _I2CAddress.toString(), _UART_CH); for (int i = 0; i < sizeof _inbuffer; i++){ DIAG(F("SC16IS752: Data _inbuffer[0x%x]: 0x%x"), i, _inbuffer[i]); } #endif } else { FIFO_RX_LEVEL = 0; //set to 0, we'll read a fresh FIFO_RX_LEVEL next time return; // No data or not enough data in rx fifo, check again next time around } bool ok = false; //DIAG(F("I2CDFPlayer: RX_BUFFER: %d"), RX_BUFFER); while (RX_BUFFER != 0) { int c = _inbuffer[_inputIndex]; // Start at 0, increment to FIFO_RX_LEVEL switch (_inputIndex) { case 0: if (c == 0x7E) ok = true; break; case 1: if (c == 0xFF) ok = true; break; case 2: if (c== 0x06) ok = true; break; case 3: _recvCMD = c; // CMD byte ok = true; break; case 6: switch (_recvCMD) { //DIAG(F("I2CDFPlayer: %s, _recvCMD: 0x%x _awaitingResponse: 0x0%x"),_I2CAddress.toString(), _recvCMD, _awaitingResponse); case 0x42: // Response to status query _playing = (c != 0); // Mark the device online and cancel timeout if (_deviceState==DEVSTATE_INITIALISING) { _deviceState = DEVSTATE_NORMAL; #ifdef DIAG_I2CDFplayer DIAG(F("I2CDFPlayer: %s, UART_CH: 0x0%x, _deviceState: 0x0%x"),_I2CAddress.toString(), _UART_CH, _deviceState); #endif #ifdef DIAG_IO _display(); #endif } _awaitingResponse = false; break; case 0x3d: // End of play if (_playing) { #ifdef DIAG_IO DIAG(F("I2CDFPlayer: Finished")); #endif _playing = false; } break; case 0x40: // Error codes; 1: Module Busy DIAG(F("I2CDFPlayer: Error %d returned from device"), c); _playing = false; break; } ok = true; break; case 4: case 5: case 7: case 8: ok = true; // Skip over these bytes in message. break; case 9: if (c==0xef) { // Message finished _retryCounter = RETRYCOUNT; // reset the retry counter as we have received a valid packet } break; default: break; } if (ok){ _inputIndex++; // character as expected, so increment index RX_BUFFER --; // Decrease FIFO_RX_LEVEL with each character read from _inbuffer[_inputIndex] } else { _inputIndex = 0; // otherwise reset. RX_BUFFER = 0; } } RX_BUFFER = 0; //Set to 0, we'll read a new RX FIFO level again } // Send any commands that need to be sent void processOutgoing(unsigned long currentMicros) { // When two commands are sent in quick succession, the device will often fail to // execute one. Testing has indicated that a delay of 100ms or more is required // between successive commands to get reliable operation. // If 100ms has elapsed since the last thing sent, then check if there's some output to do. if (((int32_t)currentMicros - _commandSendTime) > 100000) { if ( _resetCmd == true){ sendPacket(0x0C,0,0); _resetCmd = false; } else if(_volCmd == true) { // do the volme before palying a track if(_requestedVolumeLevel <= 30) { _currentVolume = _requestedVolumeLevel; // If _requestedVolumeLevel is out of range, sent _currentV1olume } sendPacket(0x06, 0x00, _currentVolume); _volCmd = false; } else if (_playCmd == true) { // Change song if (_requestedSong != -1) { #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: _requestedVolumeLevel: %u, _requestedSong: %u, _currentFolder: %u _playCmd: 0x%x"), _requestedVolumeLevel, _requestedSong, _currentFolder, _playCmd); #endif sendPacket(0x0F, _currentFolder, _requestedSong); // audio file in folder _requestedSong = -1; _playCmd = false; } } //else if (_requestedSong == 0) { else if (_stopplayCmd == true) { #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: Stop playing: _stopplayCmd: 0x%x"), _stopplayCmd); #endif sendPacket(0x16, 0x00, 0x00); // Stop playing _requestedSong = -1; _repeat = false; // reset repeat _stopplayCmd = false; } else if (_folderCmd == true) { #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: Folder: _folderCmd: 0x%x, _requestedFolder: %d"), _stopplayCmd, _requestedFolder); #endif if (_currentFolder != _requestedFolder){ _currentFolder = _requestedFolder; } _folderCmd = false; } else if (_repeatCmd == true) { if(_repeat == false) { // No repeat play currently #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: Repeat: _repeatCmd: 0x%x, _requestedSong: %d, _repeat: 0x0%x"), _repeatCmd, _requestedSong, _repeat); #endif sendPacket(0x08, 0x00, _requestedSong); // repeat playing audio file in root folder _requestedSong = -1; _repeat = true; } _repeatCmd= false; } else if (_daconCmd == true) { // Always turn DAC on #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: DACON: _daconCmd: 0x%x"), _daconCmd); #endif sendPacket(0x1A,0,0x00); _daconCmd = false; } else if (_eqCmd == true){ // Set Equalizer, values 0x00 - 0x05 if (_currentEQvalue != _requestedEQValue){ #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: EQ: _eqCmd: 0x%x, _currentEQvalue: 0x0%x, _requestedEQValue: 0x0%x"), _eqCmd, _currentEQvalue, _requestedEQValue); #endif _currentEQvalue = _requestedEQValue; sendPacket(0x07,0x00,_currentEQvalue); } _eqCmd = false; } else if (_setamCmd == true){ // Set Audio mixer channel setGPIO(); // Set the audio mixer channel /* if (_audioMixer == 1){ // set to audio mixer 1 if (_UART_CH == 0){ TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 0 to high } else { // must be UART 1 TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 1 to high } //_setamCmd = false; //UART_WriteRegister(REG_IOSTATE, TEMP_REG_VAL); } else { // set to audio mixer 2 if (_UART_CH == 0){ TEMP_REG_VAL &= (0x00 << _UART_CH); //Set GPIO pin 0 to Low } else { // must be UART 1 TEMP_REG_VAL &= (0x00 << _UART_CH); //Set GPIO pin 1 to Low } //_setamCmd = false; //UART_WriteRegister(REG_IOSTATE, TEMP_REG_VAL); }*/ _setamCmd = false; } else if ((int32_t)currentMicros - _commandSendTime > 1000000) { // Poll device every second that other commands aren't being sent, // to check if it's still connected and responding. #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: Send keepalive") ); #endif sendPacket(0x42,0,0); if (!_awaitingResponse) { #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: Send keepalive, _awaitingResponse: 0x0%x"), _awaitingResponse ); #endif _timeoutTime = currentMicros + 5000000UL; // Timeout if no response within 5 seconds _awaitingResponse = true; } } } } // Write to a vPin will do nothing void _write(VPIN vpin, int value) override { (void)vpin; // suppress warning, not used in this function (void)value; // suppress warning, not used in this function if (_deviceState == DEVSTATE_FAILED) return; #ifdef DIAG_IO DIAG(F("I2CDFPlayer: Writing to any vPin not supported")); #endif } // WriteAnalogue on first pin uses the nominated value as a file number to start playing, if file number > 0. // Volume may be specified as second parameter to writeAnalogue. // If value is zero, the player stops playing. // WriteAnalogue on second pin sets the output volume. // // WriteAnalogue to be done on first vpin // //void _writeAnalogue(VPIN vpin, int value, uint8_t volume=0, uint16_t=0) override { void _writeAnalogue(VPIN vpin, int value, uint8_t volume=0, uint16_t cmd=0) override { if (_deviceState == DEVSTATE_FAILED) return; #ifdef DIAG_IO DIAG(F("I2CDFPlayer: VPIN:%u FileNo:%d Volume:%d Command:0x%x"), vpin, value, volume, cmd); #endif uint8_t pin = vpin - _firstVpin; if (pin == 0) { // Enhanced DFPlayer commands, do nothing if not vPin 0 // Read command and value switch (cmd){ //case NONE: // DFPlayerCmd = cmd; // break; case DF_PLAY: _playCmd = true; _volCmd = true; _requestedSong = value; _requestedVolumeLevel = volume; _playing = true; break; case DF_VOL: _volCmd = true; _requestedVolumeLevel = volume; break; case DF_FOLDER: _folderCmd = true; if (volume <= 0 || volume > 99){ // Range checking, valid values 1-99, else default to 1 _requestedFolder = 0x01; // if outside range, default to folder 01 } else { _requestedFolder = volume; } break; case DF_REPEATPLAY: // Need to check if _repeat == true, if so do nothing if (_repeat == false) { #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: WriteAnalog Repeat: _repeat: 0x0%x, value: %d _repeatCmd: 0x%x"), _repeat, value, _repeatCmd); #endif _repeatCmd = true; _requestedSong = value; _requestedVolumeLevel = volume; _playing = true; } break; case DF_STOPPLAY: _stopplayCmd = true; break; case DF_EQ: #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: WriteAnalog EQ: cmd: 0x%x, EQ value: 0x%x"), cmd, volume); #endif _eqCmd = true; if (volume <= 0 || volume > 5) { // If out of range, default to NORMAL _requestedEQValue = DF_NORMAL; } else { // Valid EQ parameter range _requestedEQValue = volume; } break; case DF_RESET: _resetCmd = true; break; case DF_DACON: // Works, but without the DACOFF command limited value, except when not relying on DFPlayer default to turn the DAC on #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: WrtieAnalog DACON: cmd: 0x%x"), cmd); #endif _daconCmd = true; break; case DF_SETAM: // Set the audio mixer channel to 1 or 2 _setamCmd = true; #ifdef DIAG_I2CDFplayer_playing DIAG(F("I2CDFPlayer: WrtieAnalog SETAM: cmd: 0x%x"), cmd); #endif if (volume <= 0 || volume > 2) { // If out of range, default to 1 _audioMixer = 1; } else { // Valid SETAM parameter in range _audioMixer = volume; // _audioMixer valid values 1 or 2 } break; default: break; } } } // A read on any pin indicates if the player is still playing. int _read(VPIN vpin) override { if (_deviceState == DEVSTATE_FAILED) return false; uint8_t pin = vpin - _firstVpin; if (pin == 0) { // Do nothing if not vPin 0 return _playing; } return _playing; // fix for compile error: "control reaches end of non-void function [-Wreturn-type]" } void _display() override { DIAG(F("I2CDFPlayer Configured on Vpins:%u-%u %S"), _firstVpin, _firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F("")); } private: // DFPlayer command frame // 7E FF 06 0F 00 01 01 xx xx EF // 0 -> 7E is start code // 1 -> FF is version // 2 -> 06 is length // 3 -> 0F is command // 4 -> 00 is no receive // 5~6 -> 01 01 is argument // 7~8 -> checksum = 0 - ( FF+06+0F+00+01+01 ) // 9 -> EF is end code void sendPacket(uint8_t command, uint8_t arg1 = 0, uint8_t arg2 = 0) { FIFO_TX_LEVEL = 0; // Reset FIFO_TX_LEVEL uint8_t out[] = { 0x7E, 0xFF, 06, command, 00, //static_cast(arg >> 8), //static_cast(arg & 0x00ff), arg1, arg2, 00, 00, 0xEF }; setChecksum(out); // Prepend the DFPlayer command with REG address and UART Channel in _outbuffer _outbuffer[0] = REG_THR << 3 | _UART_CH << 1; //TX FIFO and UART Channel for ( uint8_t i = 1; i < sizeof(out)+1 ; i++){ _outbuffer[i] = out[i-1]; } #ifdef DIAG_I2CDFplayer_data DIAG(F("SC16IS752: I2C: %s Sent packet function"), _I2CAddress.toString()); for (int i = 0; i < sizeof _outbuffer; i++){ DIAG(F("SC16IS752: Data _outbuffer[0x%x]: 0x%x"), i, _outbuffer[i]); } #endif TX_fifo_lvl(); if(FIFO_TX_LEVEL > 0){ //FIFO is empty I2CManager.write(_I2CAddress, _outbuffer, sizeof(_outbuffer), &_rb); //I2CManager.write(_I2CAddress, _outbuffer, sizeof(_outbuffer)); #ifdef DIAG_I2CDFplayer DIAG(F("SC16IS752: I2C: %s data transmit complete on UART: 0x%x"), _I2CAddress.toString(), _UART_CH); #endif } else { DIAG(F("I2CDFPlayer at: %s, TX FIFO not empty on UART: 0x%x"), _I2CAddress.toString(), _UART_CH); _deviceState = DEVSTATE_FAILED; // This should not happen } _commandSendTime = micros(); } uint16_t calcChecksum(uint8_t* packet) { uint16_t sum = 0; for (int i = 1; i < 7; i++) { sum += packet[i]; } return -sum; } void setChecksum(uint8_t* out) { uint16_t sum = calcChecksum(out); out[7] = (sum >> 8); out[8] = (sum & 0xff); } // SC16IS752 functions // Initialise SC16IS752 only for this channel // First a software reset // Enable FIFO and clear TX & RX FIFO // Need to set the following registers // IOCONTROL set bit 1 and 2 to 0 indicating that they are GPIO // IODIR set all bit to 1 indicating al are output // IOSTATE set only bit 0 to 1 for UART 0, or only bit 1 for UART 1 // // LCR bit 7=0 divisor latch (clock division registers DLH & DLL, they store 16 bit divisor), // WORD_LEN, STOP_BIT, PARITY_ENA and PARITY_TYPE // MCR bit 7=0 clock divisor devide-by-1 clock input // DLH most significant part of divisor // DLL least significant part of divisor // // BAUD_RATE, WORD_LEN, STOP_BIT, PARITY_ENA and PARITY_TYPE have been defined and initialized // void Init_SC16IS752(){ // Return value is in _deviceState #ifdef DIAG_I2CDFplayer DIAG(F("SC16IS752: Initialize I2C: %s , UART Ch: 0x%x"), _I2CAddress.toString(), _UART_CH); #endif //uint16_t _divisor = (SC16IS752_XTAL_FREQ / PRESCALER) / (BAUD_RATE * 16); uint16_t _divisor = (_sc16is752_xtal_freq/PRESCALER)/(BAUD_RATE * 16); // Calculate _divisor for baudrate TEMP_REG_VAL = 0x08; // UART Software reset UART_WriteRegister(REG_IOCONTROL, TEMP_REG_VAL); // Extra delay when using low frequency xtal after soft reset // Test when using 1.8432 Mhz xtal if(_sc16is752_xtal_freq == SC16IS752_XTAL_FREQ_LOW){ _timeoutTime = micros() + 10000UL; // 10mS timeout _awaitingResponse = true; } TEMP_REG_VAL = 0x00; // Set pins to GPIO mode UART_WriteRegister(REG_IOCONTROL, TEMP_REG_VAL); TEMP_REG_VAL = 0xFF; //Set all pins as output UART_WriteRegister(REG_IODIR, TEMP_REG_VAL); UART_ReadRegister(REG_IOSTATE); // Read current state as not to overwrite the other GPIO pins TEMP_REG_VAL = _inbuffer[0]; setGPIO(); // Set the audio mixer channel /* if (_UART_CH == 0){ // Set Audio mixer channel TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 0 to high } else { // must be UART 1 TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 1 to high } UART_WriteRegister(REG_IOSTATE, TEMP_REG_VAL); */ TEMP_REG_VAL = 0x07; // Reset FIFO, clear RX & TX FIFO UART_WriteRegister(REG_FCR, TEMP_REG_VAL); TEMP_REG_VAL = 0x00; // Set MCR to all 0, includes Clock divisor UART_WriteRegister(REG_MCR, TEMP_REG_VAL); TEMP_REG_VAL = 0x80 | WORD_LEN | STOP_BIT | PARITY_ENA | PARITY_TYPE; UART_WriteRegister(REG_LCR, TEMP_REG_VAL); // Divisor latch enabled UART_WriteRegister(REG_DLL, (uint8_t)_divisor); // Write DLL UART_WriteRegister(REG_DLH, (uint8_t)(_divisor >> 8)); // Write DLH UART_ReadRegister(REG_LCR); TEMP_REG_VAL = _inbuffer[0] & 0x7F; // Disable Divisor latch enabled bit UART_WriteRegister(REG_LCR, TEMP_REG_VAL); // Divisor latch disabled uint8_t status = _rb.status; if (status != I2C_STATUS_OK) { DIAG(F("SC16IS752: I2C: %s failed %S"), _I2CAddress.toString(), I2CManager.getErrorMessage(status)); _deviceState = DEVSTATE_FAILED; } else { #ifdef DIAG_IO DIAG(F("SC16IS752: I2C: %s, _deviceState: %S"), _I2CAddress.toString(), I2CManager.getErrorMessage(status)); #endif _deviceState = DEVSTATE_NORMAL; // If I2C state is OK, then proceed to initialize DFPlayer } } // Read the Receive FIFO Level register (RXLVL), return a single unsigned integer // of nr of characters in the RX FIFO, bit 6:0, 7 not used, set to zero // value from 0 (0x00) to 64 (0x40) Only display if RX FIFO has data // The RX fifo level is used to check if there are enough bytes to process a frame void RX_fifo_lvl(){ UART_ReadRegister(REG_RXLV); FIFO_RX_LEVEL = _inbuffer[0]; #ifdef DIAG_I2CDFplayer if (FIFO_RX_LEVEL > 0){ //if (FIFO_RX_LEVEL > 0 && FIFO_RX_LEVEL < 10){ DIAG(F("SC16IS752: At I2C: %s, UART channel: 0x%x, FIFO_RX_LEVEL: 0d%d"), _I2CAddress.toString(), _UART_CH, _inbuffer[0]); } #endif } // When a frame is transmitted from the DFPlayer to the serial port, and at the same time the CS is sending a 42 query // the following two frames from the DFPlayer are corrupt. This result in the receive buffer being out of sync and the // CS will complain and generate a timeout. // The RX fifo has corrupt data and need to be flushed, this function does that // void resetRX_fifo(){ #ifdef DIAG_I2CDFplayer DIAG(F("SC16IS752: At I2C: %s, UART channel: 0x%x, RX fifo reset"), _I2CAddress.toString(), _UART_CH); #endif TEMP_REG_VAL = 0x03; // Reset RX fifo UART_WriteRegister(REG_FCR, TEMP_REG_VAL); } // Set or reset GPIO pin 0 and 1 depending on the UART ch // This function may be modified in a future release to enable all 8 pins to be set or reset with EX-Rail // for various auxilary functions void setGPIO(){ UART_ReadRegister(REG_IOSTATE); // Get the current GPIO pins state from the IOSTATE register TEMP_REG_VAL = _inbuffer[0]; if (_audioMixer == 1){ // set to audio mixer 1 if (_UART_CH == 0){ TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 0 to high } else { // must be UART 1 TEMP_REG_VAL |= (0x01 << _UART_CH); //Set GPIO pin 1 to high } } else { // set to audio mixer 2 if (_UART_CH == 0){ TEMP_REG_VAL &= ~(0x01 << _UART_CH); //Set GPIO pin 0 to Low } else { // must be UART 1 TEMP_REG_VAL &= ~(0x01 << _UART_CH); //Set GPIO pin 1 to Low } } UART_WriteRegister(REG_IOSTATE, TEMP_REG_VAL); _setamCmd = false; } // Read the Tranmit FIFO Level register (TXLVL), return a single unsigned integer // of nr characters free in the TX FIFO, bit 6:0, 7 not used, set to zero // value from 0 (0x00) to 64 (0x40) // void TX_fifo_lvl(){ UART_ReadRegister(REG_TXLV); FIFO_TX_LEVEL = _inbuffer[0]; #ifdef DIAG_I2CDFplayer // DIAG(F("SC16IS752: At I2C: %s, UART channel: 0x%x, FIFO_TX_LEVEL: 0d%d"), _I2CAddress.toString(), _UART_CH, FIFO_TX_LEVEL); #endif } //void UART_WriteRegister(I2CAddress _I2CAddress, uint8_t _UART_CH, uint8_t UART_REG, uint8_t Val, I2CRB &_rb){ void UART_WriteRegister(uint8_t UART_REG, uint8_t Val){ _outbuffer[0] = UART_REG << 3 | _UART_CH << 1; _outbuffer[1] = Val; #ifdef DIAG_I2CDFplayer_reg DIAG(F("SC16IS752: Write register at I2C: %s, UART channel: 0x%x, Register: 0x%x, Data: 0b%b"), _I2CAddress.toString(), _UART_CH, UART_REG, _outbuffer[1]); #endif I2CManager.write(_I2CAddress, _outbuffer, 2); } void UART_ReadRegister(uint8_t UART_REG){ _outbuffer[0] = UART_REG << 3 | _UART_CH << 1; // _outbuffer[0] has now UART_REG and UART_CH I2CManager.read(_I2CAddress, _inbuffer, 1, _outbuffer, 1); // _inbuffer has the REG data #ifdef DIAG_I2CDFplayer_reg DIAG(F("SC16IS752: Read register at I2C: %s, UART channel: 0x%x, Register: 0x%x, Data: 0b%b"), _I2CAddress.toString(), _UART_CH, UART_REG, _inbuffer[0]); #endif } // SC16IS752 General register set (from the datasheet) enum : uint8_t{ REG_RHR = 0x00, // FIFO Read REG_THR = 0x00, // FIFO Write REG_IER = 0x01, // Interrupt Enable Register R/W REG_FCR = 0x02, // FIFO Control Register Write REG_IIR = 0x02, // Interrupt Identification Register Read REG_LCR = 0x03, // Line Control Register R/W REG_MCR = 0x04, // Modem Control Register R/W REG_LSR = 0x05, // Line Status Register Read REG_MSR = 0x06, // Modem Status Register Read REG_SPR = 0x07, // Scratchpad Register R/W REG_TCR = 0x06, // Transmission Control Register R/W REG_TLR = 0x07, // Trigger Level Register R/W REG_TXLV = 0x08, // Transmitter FIFO Level register Read REG_RXLV = 0x09, // Receiver FIFO Level register Read REG_IODIR = 0x0A, // Programmable I/O pins Direction register R/W REG_IOSTATE = 0x0B, // Programmable I/O pins State register R/W REG_IOINTENA = 0x0C, // I/O Interrupt Enable register R/W REG_IOCONTROL = 0x0E, // I/O Control register R/W REG_EFCR = 0x0F, // Extra Features Control Register R/W }; // SC16IS752 Special register set enum : uint8_t{ REG_DLL = 0x00, // Division registers R/W REG_DLH = 0x01, // Division registers R/W }; // SC16IS752 Enhanced regiter set enum : uint8_t{ REG_EFR = 0X02, // Enhanced Features Register R/W REG_XON1 = 0x04, // R/W REG_XON2 = 0x05, // R/W REG_XOFF1 = 0x06, // R/W REG_XOFF2 = 0x07, // R/W }; // DFPlayer commands and values // Declared in this scope enum : uint8_t{ DF_PLAY = 0x0F, DF_VOL = 0x06, DF_FOLDER = 0x2B, // Not a DFPlayer command, used to set folder nr where audio file is DF_REPEATPLAY = 0x08, DF_STOPPLAY = 0x16, DF_EQ = 0x07, // Set equaliser, require parameter NORMAL, POP, ROCK, JAZZ, CLASSIC or BASS DF_RESET = 0x0C, DF_DACON = 0x1A, DF_SETAM = 0x2A, // Set audio mixer 1 or 2 for this DFPLayer DF_NORMAL = 0x00, // Equalizer parameters DF_POP = 0x01, DF_ROCK = 0x02, DF_JAZZ = 0x03, DF_CLASSIC = 0x04, DF_BASS = 0x05, }; }; #endif // IO_I2CDFPlayer_h ================================================ FILE: IO_I2CRailcom.cpp ================================================ /* * © 2024, Henk Kruisbrink & Chris Harlow. All rights reserved. * © 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 . */ /* * * Dec 2023, Added NXP SC16IS752 I2C Dual UART * The SC16IS752 has 64 bytes TX & RX FIFO buffer * First version without interrupts from I2C UART and only RX/TX are used, interrupts may not be * needed as the RX Fifo holds the reply * * Jan 2024, Issue with using both UARTs simultaniously, the secod uart seems to work but the first transmit * corrupt data. This need more analysis and experimenatation. * Will push this driver to the dev branch with the uart fixed to 0 * Both SC16IS750 (single uart) and SC16IS752 (dual uart, but only uart 0 is enable) * * myHall.cpp configuration syntax: * * I2CRailcom::create(1st vPin, vPins, I2C address); * * myAutomation configuration * HAL(I2CRailcom, 1st vPin, vPins, I2C address) * Parameters: * 1st vPin : First virtual pin that EX-Rail can control to play a sound, use PLAYSOUND command (alias of ANOUT) * vPins : Total number of virtual pins allocated (to prevent overlaps) * I2C Address : I2C address of the serial controller, in 0x format */ #include "IODevice.h" #include "IO_I2CRailcom.h" #include "I2CManager.h" #include "DIAG.h" #include "DCC.h" #include "DCCWaveform.h" #include "Railcom.h" I2CRailcom::I2CRailcom(VPIN firstVpin, int nPins, I2CAddress i2cAddress){ _firstVpin = firstVpin; _nPins = nPins; _I2CAddress = i2cAddress; addDevice(this); } void I2CRailcom::create(VPIN firstVpin, int nPins, I2CAddress i2cAddress) { if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new I2CRailcom(firstVpin,nPins,i2cAddress); } void I2CRailcom::_begin() { I2CManager.begin(); I2CManager.setClock(1000000); // TODO do we need this? auto exists=I2CManager.exists(_I2CAddress); DIAG(F("I2CRailcom: %s RailcomCollector %S detected"), _I2CAddress.toString(), exists?F(""):F(" NOT")); if (!exists) return; _deviceState=DEVSTATE_NORMAL; _display(); } void I2CRailcom::_loop(unsigned long currentMicros) { (void)currentMicros; // not used, but needed to match IODevice interface // Read responses from device if (_deviceState!=DEVSTATE_NORMAL) return; // have we read this cutout already? // basically we only poll once per packet when railcom cutout is working auto cut=Railcom::getCutout(); if (cutoutCounter==cut) return; cutoutCounter=cut; Railcom::loop(); // in case a csv read has timed out // Obtain data length from the collector byte inbuf[1]; byte queryLength[]={'?'}; auto state=I2CManager.read(_I2CAddress, inbuf, 1,queryLength,sizeof(queryLength)); if (state) { DIAG(F("RC ? state=%d"),state); return; } auto length=inbuf[0]; if (length==0) return; // nothing to report // Build a buffer and import the data from the collector byte inbuf2[length]; byte queryData[]={'>'}; state=I2CManager.read(_I2CAddress, inbuf2, length,queryData,sizeof(queryData)); if (state) { DIAG(F("RC > %d state=%d"),length,state); return; } // process incoming data buffer Railcom::process(_firstVpin,inbuf2,length); } void I2CRailcom::_display() { DIAG(F("I2CRailcom: %s blocks %d-%d %S"), _I2CAddress.toString(), _firstVpin, _firstVpin+_nPins-1, (_deviceState!=DEVSTATE_NORMAL) ? F("OFFLINE") : F("")); } ================================================ FILE: IO_I2CRailcom.h ================================================ /* * © 2024, Henk Kruisbrink & Chris Harlow. All rights reserved. * © 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 . */ /* * This polls the RailcomCollecter device once per dcc packet * and obtains an abbreviated list of block occupancy changes which * are fortunately very rare compared with Railcom raw data. * * myAutomation configuration * HAL(I2CRailcom, 1st vPin, vPins, I2C address) * Parameters: * 1st vPin : First virtual pin that EX-Rail can control to play a sound, use PLAYSOUND command (alias of ANOUT) * vPins : Total number of virtual pins allocated * I2C Address : I2C address of the Railcom Collector, in 0x format */ #ifndef IO_I2CRailcom_h #define IO_I2CRailcom_h #include "Arduino.h" #include "IODevice.h" class I2CRailcom : public IODevice { private: byte cutoutCounter; public: // Constructor I2CRailcom(VPIN firstVpin, int nPins, I2CAddress i2cAddress); static void create(VPIN firstVpin, int nPins, I2CAddress i2cAddress) ; void _begin() ; void _loop(unsigned long currentMicros) override ; void _display() override ; private: }; #endif // IO_I2CRailcom_h ================================================ FILE: IO_MCP23008.h ================================================ /* * © 2022 Paul M Antoine * © 2021, Neil McKechnie. All rights reserved. * * This file is part of DCC++EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef IO_MCP23008_H #define IO_MCP23008_H #include "IO_GPIOBase.h" class MCP23008 : public GPIOBase { public: 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, I2CAddress i2cAddress, int interruptPin=-1) : GPIOBase((FSH *)F("MCP23008"), firstVpin, nPins, i2cAddress, interruptPin) { requestBlock.setRequestParams(_I2CAddress, inputBuffer, sizeof(inputBuffer), outputBuffer, sizeof(outputBuffer)); outputBuffer[0] = REG_GPIO; } void _writeGpioPort() override { I2CManager.write(_I2CAddress, 2, REG_GPIO, _portOutputState); } void _writePullups() override { // Set pullups only for in-use pins. This prevents pullup being set for a pin that // is intended for use as an output but hasn't been written to yet. I2CManager.write(_I2CAddress, 2, REG_GPPU, _portPullup & _portInUse); } void _writePortModes() override { // Write 0 to IODIR for in-use pins that are outputs, 1 for others. uint8_t temp = ~(_portMode & _portInUse); I2CManager.write(_I2CAddress, 2, REG_IODIR, temp); // Enable interrupt-on-change for in-use pins that are inputs (_portMode=0) temp = ~_portMode & _portInUse; I2CManager.write(_I2CAddress, 2, REG_INTCON, 0x00); I2CManager.write(_I2CAddress, 2, REG_GPINTEN, temp); } void _readGpioPort(bool immediate) override { if (immediate) { uint8_t buffer; I2CManager.read(_I2CAddress, &buffer, 1, 1, REG_GPIO); _portInputState = buffer | _portMode; } else { // Queue new request requestBlock.wait(); // Wait for preceding operation to complete // Issue new request to read GPIO register I2CManager.queueRequest(&requestBlock); } } // This function is invoked when an I/O operation on the requestBlock completes. void _processCompletion(uint8_t status) override { if (status == I2C_STATUS_OK) _portInputState = inputBuffer[0] | _portMode; else _portInputState = 0xff; } void _setupDevice() override { // IOCON is set ODR=1 (open drain shared interrupt pin), INTPOL=0 (active-Low) I2CManager.write(_I2CAddress, 2, REG_IOCON, 0x04); _writePortModes(); _writePullups(); _writeGpioPort(); } uint8_t inputBuffer[1]; uint8_t outputBuffer[1]; enum { // Register definitions for MCP23008 REG_IODIR=0x00, REG_GPINTEN=0x02, REG_INTCON=0x04, REG_IOCON=0x05, REG_GPPU=0x06, REG_GPIO=0x09, }; }; #endif ================================================ FILE: IO_MCP23017.h ================================================ /* * © 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 . */ #ifndef io_mcp23017_h #define io_mcp23017_h #include "IO_GPIOBase.h" #include "FSH.h" ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for MCP23017 16-bit I/O expander. */ class MCP23017 : public GPIOBase { public: 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, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) : GPIOBase((FSH *)F("MCP23017"), vpin, nPins, i2cAddress, interruptPin) { requestBlock.setRequestParams(_I2CAddress, inputBuffer, sizeof(inputBuffer), outputBuffer, sizeof(outputBuffer)); outputBuffer[0] = REG_GPIOA; } void _writeGpioPort() override { I2CManager.write(_I2CAddress, 3, REG_GPIOA, _portOutputState, _portOutputState>>8); } void _writePullups() override { // Set pullups only for in-use pins. This prevents pullup being set for a pin that // is intended for use as an output but hasn't been written to yet. uint16_t temp = _portPullup & _portInUse; I2CManager.write(_I2CAddress, 3, REG_GPPUA, temp, temp>>8); } void _writePortModes() override { // Write 0 to IODIR for in-use pins that are outputs, 1 for others. uint16_t temp = ~(_portMode & _portInUse); I2CManager.write(_I2CAddress, 3, REG_IODIRA, temp, temp>>8); // Enable interrupt for in-use pins which are inputs (_portMode=0) temp = ~_portMode & _portInUse; I2CManager.write(_I2CAddress, 3, REG_INTCONA, 0x00, 0x00); I2CManager.write(_I2CAddress, 3, REG_GPINTENA, temp, temp>>8); } void _readGpioPort(bool immediate) override { if (immediate) { uint8_t buffer[2]; I2CManager.read(_I2CAddress, buffer, 2, 1, REG_GPIOA); _portInputState = ((uint16_t)buffer[1]<<8) | buffer[0] | _portMode; } else { // Queue new request requestBlock.wait(); // Wait for preceding operation to complete // Issue new request to read GPIO register I2CManager.queueRequest(&requestBlock); } } // This function is invoked when an I/O operation on the requestBlock completes. void _processCompletion(uint8_t status) override { if (status == I2C_STATUS_OK) _portInputState = (((uint16_t)inputBuffer[1]<<8) | inputBuffer[0]) | _portMode; else _portInputState = 0xffff; } void _setupDevice() override { // IOCON is set MIRROR=1, ODR=1 (open drain shared interrupt pin) I2CManager.write(_I2CAddress, 2, REG_IOCON, 0x44); _writePortModes(); _writePullups(); _writeGpioPort(); } uint8_t inputBuffer[2]; uint8_t outputBuffer[1]; enum { REG_IODIRA = 0x00, REG_IODIRB = 0x01, REG_GPINTENA = 0x04, REG_GPINTENB = 0x05, REG_INTCONA = 0x08, REG_INTCONB = 0x09, REG_IOCON = 0x0A, REG_GPPUA = 0x0C, REG_GPPUB = 0x0D, REG_GPIOA = 0x12, REG_GPIOB = 0x13, }; }; #endif ================================================ FILE: IO_NeoPixel.h ================================================ /* * © 2024, Chris Harlow. All rights reserved. * * This file is part of EX-CommandStation * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * The IO_NEOPIXEL.h device driver integrates with one or more Adafruit neopixel drivers. * This device driver will configure the device on startup, along with * interacting with the device for all input/output duties. * * To create NEOPIXEL devices, these are defined in myAutomation.h: * (Note the device driver is included by default) * * HAL(NEOPIXEL,first vpin, number of pixels,mode, i2c address) * e.g. HAL(NEOPIXEL,1000,64,NEO_RGB,0x60) * This gives each pixel in the chain an individual vpin * The number of pixels must match the physical pixels in the chain. * * This driver maintains a colour (rgb value in 5,5,5 bits only) plus an ON bit. * This can be written/read with an analog write/read call. * The ON bit can be set on and off with a digital write. This allows for * a pixel to be preset a colour and then turned on and off like any other light. */ #ifndef IO_EX_NeoPixel_H #define IO_EX_NeoPixel_H #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" #include "FSH.h" // The following macros to define the Neopixel String type // have been copied from the Adafruit Seesaw Library under the // terms of the GPL. // Credit to: https://github.com/adafruit/Adafruit_Seesaw // The order of primary colors in the NeoPixel data stream can vary // among device types, manufacturers and even different revisions of // the same item. The third parameter to the seesaw_NeoPixel // constructor encodes the per-pixel byte offsets of the red, green // and blue primaries (plus white, if present) in the data stream -- // the following #defines provide an easier-to-use named version for // each permutation. e.g. NEO_GRB indicates a NeoPixel-compatible // device expecting three bytes per pixel, with the first byte // containing the green value, second containing red and third // containing blue. The in-memory representation of a chain of // NeoPixels is the same as the data-stream order; no re-ordering of // bytes is required when issuing data to the chain. // Bits 5,4 of this value are the offset (0-3) from the first byte of // a pixel to the location of the red color byte. Bits 3,2 are the // green offset and 1,0 are the blue offset. If it is an RGBW-type // device (supporting a white primary in addition to R,G,B), bits 7,6 // are the offset to the white byte...otherwise, bits 7,6 are set to // the same value as 5,4 (red) to indicate an RGB (not RGBW) device. // i.e. binary representation: // 0bWWRRGGBB for RGBW devices // 0bRRRRGGBB for RGB // RGB NeoPixel permutations; white and red offsets are always same // Offset: W R G B #define NEO_RGB ((0 << 6) | (0 << 4) | (1 << 2) | (2)) #define NEO_RBG ((0 << 6) | (0 << 4) | (2 << 2) | (1)) #define NEO_GRB ((1 << 6) | (1 << 4) | (0 << 2) | (2)) #define NEO_GBR ((2 << 6) | (2 << 4) | (0 << 2) | (1)) #define NEO_BRG ((1 << 6) | (1 << 4) | (2 << 2) | (0)) #define NEO_BGR ((2 << 6) | (2 << 4) | (1 << 2) | (0)) // RGBW NeoPixel permutations; all 4 offsets are distinct // Offset: W R G B #define NEO_WRGB ((0 << 6) | (1 << 4) | (2 << 2) | (3)) #define NEO_WRBG ((0 << 6) | (1 << 4) | (3 << 2) | (2)) #define NEO_WGRB ((0 << 6) | (2 << 4) | (1 << 2) | (3)) #define NEO_WGBR ((0 << 6) | (3 << 4) | (1 << 2) | (2)) #define NEO_WBRG ((0 << 6) | (2 << 4) | (3 << 2) | (1)) #define NEO_WBGR ((0 << 6) | (3 << 4) | (2 << 2) | (1)) #define NEO_RWGB ((1 << 6) | (0 << 4) | (2 << 2) | (3)) #define NEO_RWBG ((1 << 6) | (0 << 4) | (3 << 2) | (2)) #define NEO_RGWB ((2 << 6) | (0 << 4) | (1 << 2) | (3)) #define NEO_RGBW ((3 << 6) | (0 << 4) | (1 << 2) | (2)) #define NEO_RBWG ((2 << 6) | (0 << 4) | (3 << 2) | (1)) #define NEO_RBGW ((3 << 6) | (0 << 4) | (2 << 2) | (1)) #define NEO_GWRB ((1 << 6) | (2 << 4) | (0 << 2) | (3)) #define NEO_GWBR ((1 << 6) | (3 << 4) | (0 << 2) | (2)) #define NEO_GRWB ((2 << 6) | (1 << 4) | (0 << 2) | (3)) #define NEO_GRBW ((3 << 6) | (1 << 4) | (0 << 2) | (2)) #define NEO_GBWR ((2 << 6) | (3 << 4) | (0 << 2) | (1)) #define NEO_GBRW ((3 << 6) | (2 << 4) | (0 << 2) | (1)) #define NEO_BWRG ((1 << 6) | (2 << 4) | (3 << 2) | (0)) #define NEO_BWGR ((1 << 6) | (3 << 4) | (2 << 2) | (0)) #define NEO_BRWG ((2 << 6) | (1 << 4) | (3 << 2) | (0)) #define NEO_BRGW ((3 << 6) | (1 << 4) | (2 << 2) | (0)) #define NEO_BGWR ((2 << 6) | (3 << 4) | (1 << 2) | (0)) #define NEO_BGRW ((3 << 6) | (2 << 4) | (1 << 2) | (0)) // If 400 KHz support is enabled, the third parameter to the constructor // requires a 16-bit value (in order to select 400 vs 800 KHz speed). // If only 800 KHz is enabled (as is default on ATtiny), an 8-bit value // is sufficient to encode pixel color order, saving some space. #define NEO_KHZ800 0x0000 // 800 KHz datastream #define NEO_KHZ400 0x0100 // 400 KHz datastream ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for NeoPixel. */ class NeoPixel : public IODevice { public: static void create(VPIN vpin, int nPins, uint16_t mode=(NEO_GRB | NEO_KHZ800), I2CAddress i2cAddress=0x60) { if (checkNoOverlap(vpin, nPins, i2cAddress)) new NeoPixel(vpin, nPins, mode, i2cAddress); } private: static const byte SEESAW_NEOPIXEL_BASE=0x0E; static const byte SEESAW_NEOPIXEL_STATUS = 0x00; static const byte SEESAW_NEOPIXEL_PIN = 0x01; static const byte SEESAW_NEOPIXEL_SPEED = 0x02; static const byte SEESAW_NEOPIXEL_BUF_LENGTH = 0x03; static const byte SEESAW_NEOPIXEL_BUF=0x04; static const byte SEESAW_NEOPIXEL_SHOW=0x05; // all adafruit examples say this pin. Presumably its hard wired // in the adapter anyway. static const byte SEESAW_PIN15 = 15; // Constructor NeoPixel(VPIN firstVpin, int nPins, uint16_t mode, I2CAddress i2cAddress) { _firstVpin = firstVpin; _nPins=nPins; _I2CAddress = i2cAddress; // calculate the offsets into the seesaw buffer for each colour depending // on the pixel strip type passed in mode. _redOffset=4+(mode >> 4 & 0x03); _greenOffset=4+(mode >> 2 & 0x03); _blueOffset=4+(mode & 0x03); _whiteOffset=4+(mode >> 6 & 0x03); // if this is the same as red then we are doing a RGB string and the white byte is not used. If its different then we are doing a RGBW string and the white byte is used. if (_whiteOffset == _redOffset) _bytesPerPixel=3; else _bytesPerPixel=4; // string has a white byte. _kHz800=(mode & NEO_KHZ400)==0; _showPendimg=false; // Each pixel requires 3 bytes RGB memory. // Although the driver device can remember this, it cant do off/on without // forgetting what the on colour was! pixelBuffer=(RGB *) malloc(_nPins*sizeof(RGB)); stateBuffer=(byte *) calloc((_nPins+7)/8,sizeof(byte)); // all pixels off if (pixelBuffer==nullptr || stateBuffer==nullptr) { DIAG(F("NeoPixel I2C:%s not enough RAM"), _I2CAddress.toString()); return; } // preset all pins to white so a digital on/off will do something even if no colour set. memset(pixelBuffer,0xFF,_nPins*sizeof(RGB)); addDevice(this); } void _begin() { // Initialise Neopixel device I2CManager.begin(); if (!I2CManager.exists(_I2CAddress)) { DIAG(F("NeoPixel I2C:%s device not found"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; return; } byte speedBuffer[]={SEESAW_NEOPIXEL_BASE, SEESAW_NEOPIXEL_SPEED,_kHz800}; I2CManager.write(_I2CAddress, speedBuffer, sizeof(speedBuffer)); // In the driver there are 3 of 4 byts per pixel auto numBytes=_bytesPerPixel * _nPins; byte setbuffer[] = {SEESAW_NEOPIXEL_BASE, SEESAW_NEOPIXEL_BUF_LENGTH, (byte)(numBytes >> 8), (byte)(numBytes & 0xFF)}; I2CManager.write(_I2CAddress, setbuffer, sizeof(setbuffer)); const byte pinbuffer[] = {SEESAW_NEOPIXEL_BASE, SEESAW_NEOPIXEL_PIN,SEESAW_PIN15}; I2CManager.write(_I2CAddress, pinbuffer, sizeof(pinbuffer)); for (auto pin=0;pin<_nPins;pin++) transmit(pin); _display(); } // loop called by HAL supervisor void _loop(unsigned long currentMicros) override { (void)currentMicros; if (!_showPendimg) return; byte showBuffer[]={SEESAW_NEOPIXEL_BASE,SEESAW_NEOPIXEL_SHOW}; I2CManager.write(_I2CAddress,showBuffer,sizeof(showBuffer)); _showPendimg=false; } // read back pixel on/off int _read(VPIN vpin) override { if (_deviceState == DEVSTATE_FAILED) return 0; return isPixelOn(vpin-_firstVpin); } // Write digital value. Sets pixel on or off void _write(VPIN vpin, int value) override { if (_deviceState == DEVSTATE_FAILED) return; auto pixel=vpin-_firstVpin; if (value) { if (isPixelOn(pixel)) return; setPixelOn(pixel); } else { // set off if (!isPixelOn(pixel)) return; setPixelOff(pixel); } transmit(pixel); } VPIN _writeRange(VPIN vpin,int value, int count) { // using write range cuts out the constant vpin to driver lookup so // we can update multiple pixels much faster. VPIN nextVpin=vpin + (count>_nPins ? _nPins : count); if (_deviceState != DEVSTATE_FAILED) while(vpin>8) & 0xFF), (byte)(colour_RG & 0xFF), (byte)(colour_B & 0xFF)}; auto pixel=vpin-_firstVpin; if (pixelBuffer[pixel]==newColour && isPixelOn(pixel)==(bool)onoff) return; // no change if (onoff) setPixelOn(pixel); else setPixelOff(pixel); pixelBuffer[pixel]=newColour; transmit(pixel); } VPIN _writeAnalogueRange(VPIN vpin, int colour_RG, uint8_t onoff, uint16_t colour_B, int count) override { // using write range cuts out the constant vpin to driver lookup so VPIN nextVpin=vpin + (count>_nPins ? _nPins : count); if (_deviceState != DEVSTATE_FAILED) while(vpin>(pixel%8));} void setPixelOn(int16_t pixel) {stateBuffer[pixel/8] |= (0x80>>(pixel%8));} void setPixelOff(int16_t pixel) {stateBuffer[pixel/8] &= ~(0x80>>(pixel%8));} // Helper function for error handling void reportError(uint8_t status, bool fail=true) { DIAG(F("NeoPixel I2C:%s Error:%d (%S)"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status)); if (fail) _deviceState = DEVSTATE_FAILED; } void transmit(uint16_t pixel) { byte buffer[]={SEESAW_NEOPIXEL_BASE,SEESAW_NEOPIXEL_BUF,0x00,0x00,0x00,0x00,0x00,0x00}; uint16_t offset= pixel * _bytesPerPixel; buffer[2]=(byte)(offset>>8); buffer[3]=(byte)(offset & 0xFF); if (isPixelOn(pixel)) { auto colour=pixelBuffer[pixel]; if (_bytesPerPixel==4 && colour.red==colour.blue && colour.red==colour.green) { // we are doing a white pixel on a RGBW string. // To save electricity we can just send the white byte and leave the RGB bytes as zero. buffer[_whiteOffset]=colour.red; } else { buffer[_redOffset]=colour.red; buffer[_greenOffset]=colour.green; buffer[_blueOffset]=colour.blue; } } // else leave buffer black (in buffer preset to zeros above) // Transmit pixel to driver I2CManager.write(_I2CAddress,buffer,4 +_bytesPerPixel); _showPendimg=true; } struct RGB { byte red; byte green; byte blue; bool operator==(const RGB& other) const { return red == other.red && green == other.green && blue == other.blue; } }; RGB* pixelBuffer = nullptr; byte* stateBuffer = nullptr; // 1 bit per pixel bool _showPendimg; // mapping of RGB onto pixel buffer for seesaw. byte _bytesPerPixel; byte _redOffset; byte _greenOffset; byte _blueOffset; byte _whiteOffset; // only used if 4 bytes per pixel (RGBW string) bool _kHz800; }; #endif ================================================ FILE: IO_PCA9554.h ================================================ /* * © 2025, Paul M. Antoine * © 2021, Neil McKechnie. All rights reserved. * * This file is part of DCC-EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef io_pca9554_h #define io_pca9554_h #include "IO_GPIOBase.h" #include "FSH.h" ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for PCA9554/TCA9554 8-bit I/O expander (NXP & Texas Instruments). */ class PCA9554 : public GPIOBase { public: static void create(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) { if (checkNoOverlap(vpin, nPins, i2cAddress)) new PCA9554(vpin,nPins, i2cAddress, interruptPin); } private: // Constructor PCA9554(VPIN vpin, uint8_t nPins, I2CAddress I2CAddress, int interruptPin=-1) : GPIOBase((FSH *)F("PCA9554"), vpin, nPins, I2CAddress, interruptPin) { requestBlock.setRequestParams(_I2CAddress, inputBuffer, sizeof(inputBuffer), outputBuffer, sizeof(outputBuffer)); outputBuffer[0] = REG_INPUT_P0; } void _writeGpioPort() override { I2CManager.write(_I2CAddress, 2, REG_OUTPUT_P0, _portOutputState); } void _writePullups() override { // Do nothing, pull-ups are always in place for input ports // This function is here for HAL GPIOBase API compatibilitiy } void _writePortModes() override { // Write 0 to REG_CONF_P0 for in-use pins that are outputs, 1 for others. // PCA9554 & TCA9554, Interrupt is always enabled for raising and falling edge uint8_t temp = ~(_portMode & _portInUse); I2CManager.write(_I2CAddress, 2, REG_CONF_P0, temp); } void _readGpioPort(bool immediate) override { if (immediate) { uint8_t buffer[1]; I2CManager.read(_I2CAddress, buffer, 1, 1, REG_INPUT_P0); _portInputState = buffer[0]; } else { // Queue new request requestBlock.wait(); // Wait for preceding operation to complete // Issue new request to read GPIO register I2CManager.queueRequest(&requestBlock); } } // This function is invoked when an I/O operation on the requestBlock completes. void _processCompletion(uint8_t status) override { if (status == I2C_STATUS_OK) _portInputState = inputBuffer[0]; else _portInputState = 0xff; } void _setupDevice() override { // HAL API calls _writePortModes(); _writePullups(); _writeGpioPort(); } uint8_t inputBuffer[1]; uint8_t outputBuffer[1]; enum { REG_INPUT_P0 = 0x00, REG_OUTPUT_P0 = 0x01, REG_POL_INV_P0 = 0x02, REG_CONF_P0 = 0x03, }; }; #endif ================================================ FILE: IO_PCA9555.h ================================================ /* * © 2021, Neil McKechnie. All rights reserved. * © 2026, Chris Harlow. All rights reserved. * * This file is part of DCC-EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef io_pca9555_h #define io_pca9555_h #include "IO_GPIOBase.h" #include "FSH.h" ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for PCA9555 16-bit I/O expander (NXP & Texas Instruments). */ class PCA9555 : public GPIOBase { public: static void create(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1, char PorT='P') { if (checkNoOverlap(vpin, nPins, i2cAddress)) new PCA9555(vpin,nPins, i2cAddress, interruptPin,PorT); } private: // Constructor PCA9555(VPIN vpin, uint8_t nPins, I2CAddress I2CAddress, int interruptPin,char PorT) : GPIOBase((PorT=='P') ? (FSH *)F("PCA9555") : (FSH *)F("TCA9555"), vpin, nPins, I2CAddress, interruptPin) { requestBlock.setRequestParams(_I2CAddress, inputBuffer, sizeof(inputBuffer), outputBuffer, sizeof(outputBuffer)); outputBuffer[0] = REG_INPUT_P0; } void _writeGpioPort() override { I2CManager.write(_I2CAddress, 3, REG_OUTPUT_P0, _portOutputState, _portOutputState>>8); } void _writePullups() override { // Do nothing, pull-ups are always in place for input ports // This function is here for HAL GPIOBase API compatibilitiy } void _writePortModes() override { // Write 0 to REG_CONF_P0 & REG_CONF_P1 for in-use pins that are outputs, 1 for others. // PCA9555 & TCA9555, Interrupt is always enabled for raising and falling edge uint16_t temp = ~(_portMode & _portInUse); I2CManager.write(_I2CAddress, 3, REG_CONF_P0, temp, temp>>8); } void _readGpioPort(bool immediate) override { if (immediate) { uint8_t buffer[2]; I2CManager.read(_I2CAddress, buffer, 2, 1, REG_INPUT_P0); _portInputState = ((uint16_t)buffer[1]<<8) | buffer[0]; /* PCA9555 Int bug fix, from PCA9555 datasheet: "must change command byte to something besides 00h * after a Read operation to the PCA9555 device or before reading from * another device" * Recommended solution, read from REG_OUTPUT_P0, then do nothing with the received data * Issue not seen during testing, uncomment if needed */ //I2CManager.read(_I2CAddress, buffer, 2, 1, REG_OUTPUT_P0); } else { // Queue new request requestBlock.wait(); // Wait for preceding operation to complete // Issue new request to read GPIO register I2CManager.queueRequest(&requestBlock); } } // This function is invoked when an I/O operation on the requestBlock completes. void _processCompletion(uint8_t status) override { if (status == I2C_STATUS_OK) _portInputState = ((uint16_t)inputBuffer[1]<<8) | inputBuffer[0]; else _portInputState = 0xffff; } void _setupDevice() override { // HAL API calls _writePortModes(); _writePullups(); _writeGpioPort(); } uint8_t inputBuffer[2]; uint8_t outputBuffer[1]; enum { REG_INPUT_P0 = 0x00, REG_INPUT_P1 = 0x01, REG_OUTPUT_P0 = 0x02, REG_OUTPUT_P1 = 0x03, REG_POL_INV_P0 = 0x04, REG_POL_INV_P1 = 0x05, REG_CONF_P0 = 0x06, REG_CONF_P1 = 0x07, }; }; class TCA9555 { // ALIAS for PCA9555 as they are identical for our purposes public: static void create(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) { PCA9555::create(vpin, nPins, i2cAddress, interruptPin,'T'); } }; #endif ================================================ FILE: IO_PCA9685.cpp ================================================ /* * © 2026 Paul M. Antoine * © 2026 Filip Šilar * © 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 . */ #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" // REGISTER ADDRESSES static const byte PCA9685_MODE1=0x00; // Mode Register static const byte PCA9685_FIRST_SERVO=0x06; /** low byte first servo register ON*/ static const byte PCA9685_PRESCALE=0xFE; /** Prescale register for PWM output frequency */ // MODE1 bits static const byte MODE1_SLEEP=0x10; /**< Low power mode. Oscillator off */ 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 uint32_t MAX_I2C_SPEED = 1000000L; // PCA9685 rated up to 1MHz I2C clock speed // Create device driver instance. 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. bool PCA9685::_configure(VPIN vpin, ConfigTypeEnum configType, int paramCount, int params[]) { if (configType != CONFIGURE_SERVO) return false; if (paramCount != 5) return false; #ifdef DIAG_IO 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 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, 0, 0); } return true; } // Constructor PCA9685::PCA9685(VPIN firstVpin, int nPins, I2CAddress i2cAddress, uint16_t frequency) { _firstVpin = firstVpin; _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++) _servoData[i] = NULL; addDevice(this); // Initialise structure used for setting pulse rate requestBlock.setWriteParams(_I2CAddress, outputBuffer, sizeof(outputBuffer)); } // Device-specific initialisation void PCA9685::_begin() { 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(PCA9685_MODE1, MODE1_SLEEP | MODE1_AI); writeRegister(PCA9685_PRESCALE, prescaler); writeRegister(PCA9685_MODE1, MODE1_AI); writeRegister(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 write function, invoked from IODevice::write(). // For this function, the configured profile is used. void PCA9685::_write(VPIN vpin, int value) { #ifdef DIAG_IO DIAG(F("PCA9685 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 PWM to 0% to power off servo motor when finished // 1=Keep PWM pulses on (better when using PWM to drive an LED) // 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. // void PCA9685::_writeAnalogue(VPIN vpin, int value, uint8_t profile, uint16_t duration) { #ifdef DIAG_IO 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; 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 PCA9685::_read(VPIN vpin) { 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 PCA9685::_loop(unsigned long currentMicros) { 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 PCA9685::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 byte 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 writeDevice(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 PWM to prevent annoying servo buzz writeDevice(pin, 0); } #endif s->numSteps = 0; // Done now. } } // writeDevice 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 PCA9685::writeDevice(uint8_t pin, int value) { #ifdef DIAG_IO 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:%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); } } // Display details of this device. void PCA9685::_display() { 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("")); } // Private member function for this device void PCA9685::writeRegister(byte reg, byte value) { I2CManager.write(_I2CAddress, 2, reg, value); } // 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. 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}; ================================================ FILE: IO_PCA9685pwm.h ================================================ /* * © 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 . */ /* * 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 ================================================ FILE: IO_PCF8574.h ================================================ /* * © 2025 Herb Morton * © 2022 Paul M Antoine * © 2021, Neil McKechnie. All rights reserved. * * This file is part of DCC++EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * The PCF8574 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_PCF8574_H #define IO_PCF8574_H #include "IO_GPIOBase.h" class PCF8574 : public GPIOBase { public: static void create(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1, int initPortState=-1) { if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new PCF8574(firstVpin, nPins, i2cAddress, interruptPin, initPortState); } private: PCF8574(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1, int initPortState=-1) : GPIOBase((FSH *)F("PCF8574"), firstVpin, nPins, i2cAddress, interruptPin) { requestBlock.setReadParams(_I2CAddress, inputBuffer, 1); if (initPortState>=0) { _portMode = 255; // set all pins to output mode _portInUse = 255; // 8 ports in use _portOutputState = initPortState; // initialize pins low-high 0-255 I2CManager.write(_I2CAddress, 1, initPortState); } } // 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) & _portInUse); } // The PCF8574 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 { } 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[1]; I2CManager.read(_I2CAddress, buffer, 1); _portInputState = 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 = inputBuffer[0] | _portMode; else _portInputState = 0xff; } // Set up device ports void _setupDevice() override { _writePortModes(); } uint8_t inputBuffer[1]; }; #endif ================================================ FILE: IO_PCF8575.h ================================================ /* * © 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 . */ /* * 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 { 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((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 ================================================ FILE: IO_RotaryEncoder.h ================================================ /* * © 2023, Peter Cole. All rights reserved. * © 2022, Peter Cole. All rights reserved. * * This file is part of EX-CommandStation * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* * The IO_RotaryEncoder device driver is used to receive positions from a rotary encoder connected to an Arduino via I2C. * * There is separate code required for the Arduino the rotary encoder is connected to, which is located here: * https://github.com/peteGSX-Projects/dcc-ex-rotary-encoder * * This device driver receives the rotary encoder position when the rotary encoder button is pushed, and these positions * can be tested in EX-RAIL with: * ONCHANGE(vpin) - flag when the rotary encoder position has changed from the previous position * IFRE(vpin, position) - test to see if specified rotary encoder position has been received * * Feedback can also be sent to the rotary encoder by using 2 Vpins, and sending a SET()/RESET() to the second Vpin. * A SET(vpin) will flag that a turntable (or anything else) is in motion, and a RESET(vpin) that the motion has finished. * * In addition, defining a third Vpin will allow a position number to be sent so that when an EXRAIL automation or some other * activity has moved a turntable, the position can be reflected in the rotary encoder software. This can be accomplished * using the EXRAIL SERVO(vpin, position, profile) command, where: * - vpin = the third defined Vpin (any other is ignored) * - position = the defined position in the DCC-EX Rotary Encoder software, 0 (Home) to 255 * - profile = Must be defined as per the SERVO() command, but is ignored as it has no relevance * * Defining in myAutomation.h requires the device driver to be included in addition to the HAL() statement. Examples: * * #include "IO_RotaryEncoder.h" * HAL(RotaryEncoder, 700, 1, 0x67) // Define single Vpin, no feedback or position sent to rotary encoder software * HAL(RotaryEncoder, 700, 2, 0x67) // Define two Vpins, feedback only sent to rotary encoder software * HAL(RotaryEncoder, 700, 3, 0x67) // Define three Vpins, can send feedback and position update to rotary encoder software * * Refer to the documentation for further information including the valid activities and examples. */ #ifndef IO_ROTARYENCODER_H #define IO_ROTARYENCODER_H #include "EXRAIL2.h" #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" class RotaryEncoder : public IODevice { public: static void create(VPIN firstVpin, int nPins, I2CAddress i2cAddress) { if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new RotaryEncoder(firstVpin, nPins, i2cAddress); } private: // Constructor RotaryEncoder(VPIN firstVpin, int nPins, I2CAddress i2cAddress){ _firstVpin = firstVpin; _nPins = nPins; if (_nPins > 3) { _nPins = 3; DIAG(F("RotaryEncoder WARNING:%d vpins defined, only 3 supported"), _nPins); } _I2CAddress = i2cAddress; addDevice(this); } // Initiate the device void _begin() { uint8_t _status; // Attempt to initilalise device I2CManager.begin(); if (I2CManager.exists(_I2CAddress)) { // Send RE_RDY, must receive RE_RDY to be online _sendBuffer[0] = RE_RDY; _status = I2CManager.read(_I2CAddress, _rcvBuffer, 1, _sendBuffer, 1); if (_status == I2C_STATUS_OK) { if (_rcvBuffer[0] == RE_RDY) { _sendBuffer[0] = RE_VER; if (I2CManager.read(_I2CAddress, _versionBuffer, 3, _sendBuffer, 1) == I2C_STATUS_OK) { _majorVer = _versionBuffer[0]; _minorVer = _versionBuffer[1]; _patchVer = _versionBuffer[2]; } } else { DIAG(F("RotaryEncoder I2C:%s garbage received: %d"), _I2CAddress.toString(), _rcvBuffer[0]); _deviceState = DEVSTATE_FAILED; return; } } else { DIAG(F("RotaryEncoder I2C:%s ERROR connecting"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; return; } #ifdef DIAG_IO _display(); #endif } else { DIAG(F("RotaryEncoder I2C:%s device not found"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; } } void _loop(unsigned long currentMicros) override { if (_deviceState == DEVSTATE_FAILED) return; // Return if device has failed if (_i2crb.isBusy()) return; // Return if I2C operation still in progress if (currentMicros - _lastPositionRead > _positionRefresh) { _lastPositionRead = currentMicros; _sendBuffer[0] = RE_READ; I2CManager.read(_I2CAddress, _rcvBuffer, 1, _sendBuffer, 1, &_i2crb); // Read position from encoder _position = _rcvBuffer[0]; // If EXRAIL is active, we need to trigger the ONCHANGE() event handler if it's in use #if defined(EXRAIL_ACTIVE) if (_position != _previousPosition) { _previousPosition = _position; RMFT2::changeEvent(_firstVpin, 1); } else { RMFT2::changeEvent(_firstVpin, 0); } #endif } } // Return the position sent by the rotary encoder software int _readAnalogue(VPIN vpin) override { (void)vpin; // suppress warning, not used in this function if (_deviceState == DEVSTATE_FAILED) return 0; return _position; } // Send the feedback value to the rotary encoder software void _write(VPIN vpin, int value) override { if (vpin == _firstVpin + 1) { if (value != 0) value = 0x01; byte _feedbackBuffer[2] = {RE_OP, (byte)value}; I2CManager.write(_I2CAddress, _feedbackBuffer, 2); } } // Send a position update to the rotary encoder software // To be valid, must be 0 to 255, and different to the current position // If the current position is the same, it was initiated by the rotary encoder void _writeAnalogue(VPIN vpin, int position, uint8_t profile, uint16_t duration) override { (void)profile; // suppress warning, not used in this function (void)duration; // suppress warning, not used in this function if (vpin == _firstVpin + 2) { if (position >= 0 && position <= 255 && position != _position) { byte newPosition = position & 0xFF; byte _positionBuffer[2] = {RE_MOVE, newPosition}; I2CManager.write(_I2CAddress, _positionBuffer, 2); } } } void _display() override { DIAG(F("Rotary Encoder I2C:%s v%d.%d.%d Configured on VPIN:%u-%d %S"), _I2CAddress.toString(), _majorVer, _minorVer, _patchVer, (int)_firstVpin, _firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F("")); } int8_t _position; int8_t _previousPosition = 0; uint8_t _versionBuffer[3]; uint8_t _sendBuffer[1]; uint8_t _rcvBuffer[1]; uint8_t _majorVer = 0; uint8_t _minorVer = 0; uint8_t _patchVer = 0; I2CRB _i2crb; unsigned long _lastPositionRead = 0; const unsigned long _positionRefresh = 100000UL; // Delay refreshing position for 100ms enum { RE_RDY = 0xA0, // Flag to check if encoder is ready for operation RE_VER = 0xA1, // Flag to retrieve rotary encoder software version RE_READ = 0xA2, // Flag to read the current position of the encoder RE_OP = 0xA3, // Flag for operation start/end, sent to when sending feedback on move start/end RE_MOVE = 0xA4, // Flag for sending a position update from the device driver to the encoder }; }; #endif ================================================ FILE: IO_Servo.cpp ================================================ /* * © 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 . */ #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}; ================================================ FILE: IO_Servo.h ================================================ /* * © 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 . */ /* * 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 ================================================ FILE: IO_TCA8418.h ================================================ /* * © 2023-2024, Paul M. Antoine * © 2021, Neil McKechnie. All rights reserved. * * This file is part of DCC-EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef io_tca8418_h #define io_tca8418_h #include "IODevice.h" #include "I2CManager.h" #include "DIAG.h" #include "FSH.h" ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for TCA8418 80-key keypad encoder, which we'll treat as 80 available VPINs where * key down == 1 and key up == 0 by configuring just as an 8x10 keyboard matrix. Users can opt to use * up to all 80 of the available VPINs for now, allowing memory to be saved if not all events are required. * * The datasheet says: * * The TCA8418 can be configured to support many different configurations of keypad setups. * All 18 GPIOs for the rows and columns can be used to support up to 80 keys in an 8x10 key pad * array. Another option is that all 18 GPIOs be used for GPIs to read 18 buttons which are * not connected in an array. Any combination in between is also acceptable (for example, a * 3x4 keypad matrix and using the remaining 11 GPIOs as a combination of inputs and outputs). * * With an 8x10 key event matrix, the events are numbered as such: * * C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 * ======================================== * R0| 0 1 2 3 4 5 6 7 8 9 * R1| 10 11 12 13 14 15 16 17 18 19 * R2| 20 21 22 23 24 25 26 27 28 29 * R3| 30 31 32 33 34 35 36 37 38 39 * R4| 40 41 42 43 44 45 46 47 48 49 * R5| 50 51 52 53 54 55 56 57 58 59 * R6| 60 61 62 63 64 65 66 67 68 69 * R7| 70 71 72 73 74 75 76 77 78 79 * * So if you start with VPIN 300, R0/C0 will be 300, and R7/C9 will be 379. * * HAL declaration for myAutomation.h is: * HAL(TCA8418, firstVpin, numPins, I2CAddress, interruptPin) * * Where numPins can be 1-80, and interruptPin can be any spare Arduino pin. * * Configure using the following on the main I2C bus: * HAL(TCA8418, 300, 80, 0x34) * * Use something like this on a multiplexor, and with up to 8 of the 8-way multiplexors you could have 64 different TCA8418 boards: * HAL(TCA8418, 400, 80, {SubBus_1, 0x34}) * * And if needing an Interrupt pin to speed up operations: * HAL(TCA8418, 300, 80, 0x34, D21) * * Note that using an interrupt pin speeds up button press acquisition considerably (less than a millisecond vs 10-100), * but even with interrupts enabled the code presently checks every 100ms in case the interrupt pin becomes disconnected. * Use any available Arduino pin for interrupt monitoring. */ class TCA8418 : public IODevice { public: static void create(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) { if (checkNoOverlap(firstVpin, nPins, i2cAddress)) new TCA8418(firstVpin, (nPins = (nPins > 80) ? 80 : nPins), i2cAddress, interruptPin); } private: uint8_t* _digitalInputStates = NULL; // Array of pin states uint8_t _digitalPinBytes = 0; // Number of bytes in pin state array uint8_t _numKeyEvents = 0; // Number of outsanding key events waiting for us unsigned long _lastEventRead = 0; unsigned long _eventRefresh = 10000UL; // Delay refreshing events for 10ms const unsigned long _eventRefreshSlow = 100000UL; // Delay refreshing events for 100ms bool _gpioInterruptsEnabled = false; uint8_t _inputBuffer[1]; uint8_t _commandBuffer[1]; I2CRB _i2crb; enum {RDS_IDLE, RDS_EVENT, RDS_KEYCODE}; // Read operation states uint8_t _readState = RDS_IDLE; // Constructor TCA8418(VPIN firstVpin, uint8_t nPins, I2CAddress i2cAddress, int interruptPin=-1) { if (nPins > 0) { _firstVpin = firstVpin; _nPins = nPins; _I2CAddress = i2cAddress; _gpioInterruptPin = interruptPin; addDevice(this); } } void _begin() { I2CManager.begin(); if (I2CManager.exists(_I2CAddress)) { // Default all GPIO pins to INPUT I2CManager.write(_I2CAddress, 2, REG_GPIO_DIR_1, 0x00); I2CManager.write(_I2CAddress, 2, REG_GPIO_DIR_2, 0x00); I2CManager.write(_I2CAddress, 2, REG_GPIO_DIR_3, 0x00); // Remove all GPIO pins from events I2CManager.write(_I2CAddress, 2, REG_GPI_EM_1, 0x00); I2CManager.write(_I2CAddress, 2, REG_GPI_EM_2, 0x00); I2CManager.write(_I2CAddress, 2, REG_GPI_EM_3, 0x00); // Set all pins to FALLING interrupts I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_LVL_1, 0x00); I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_LVL_2, 0x00); I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_LVL_3, 0x00); // Remove all GPIO pins from interrupts I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_EN_1, 0x00); I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_EN_2, 0x00); I2CManager.write(_I2CAddress, 2, REG_GPIO_INT_EN_3, 0x00); // Set up an 8 x 10 matrix by writing 0xFF to all the row and column configs // Row config is maximum of 8, and in REG_KP_GPIO_1 I2CManager.write(_I2CAddress, 2, REG_KP_GPIO_1, 0xFF); // Column config is maximum of 10, lower 8 bits in REG_KP_GPIO_2, upper in REG_KP_GPIO_3 // Set first 8 columns I2CManager.write(_I2CAddress, 2, REG_KP_GPIO_2, 0xFF); // Turn on cols 9/10 I2CManager.write(_I2CAddress, 2, REG_KP_GPIO_3, 0x03); // // Set all pins to Enable Debounce I2CManager.write(_I2CAddress, 2, REG_DEBOUNCE_DIS_1, 0x00); I2CManager.write(_I2CAddress, 2, REG_DEBOUNCE_DIS_2, 0x00); I2CManager.write(_I2CAddress, 2, REG_DEBOUNCE_DIS_3, 0x00); // Let's assume an 8x10 matrix for now, and configure _digitalPinBytes = (_nPins + 7) / 8; if ((_digitalInputStates = (byte *)calloc(_digitalPinBytes, 1)) == NULL) { DIAG(F("TCA8418 I2C: Unable to alloc %d bytes"), _digitalPinBytes); return; } // Configure pin used for GPIO extender notification of change (if allocated) // and configure TCA8418 to produce key event interrupts if (_gpioInterruptPin >= 0) { DIAG(F("TCA8418 I2C: interrupt pin configured on %d"), _gpioInterruptPin); _gpioInterruptsEnabled = true; _eventRefresh = _eventRefreshSlow; // Switch to slower manual refreshes in case the INT pin isn't connected! pinMode(_gpioInterruptPin, INPUT_PULLUP); I2CManager.write(_I2CAddress, 2, REG_CFG, REG_CFG_KE_IEN); // Clear any pending interrupts I2CManager.write(_I2CAddress, 2, REG_INT_STAT, REG_STAT_K_INT); } #ifdef DIAG_IO _display(); #endif } } int _read(VPIN vpin) override { if (_deviceState == DEVSTATE_FAILED) return 0; int pin = vpin - _firstVpin; bool result = _digitalInputStates[pin / 8] & (1 << (pin % 8)); return result; } // Main loop, collect both digital and analogue pin states continuously (faster sensor/input reads) void _loop(unsigned long currentMicros) override { if (_deviceState == DEVSTATE_FAILED) return; // If device failed, return // Request block is used for key event reads from the TCA8418, which are performed // on a cyclic basis. if (_readState != RDS_IDLE) { if (_i2crb.isBusy()) return; // If I2C operation still in progress, return uint8_t status = _i2crb.status; if (status == I2C_STATUS_OK) { // If device request ok, read input data // First check if we have any key events waiting if (_readState == RDS_EVENT) { if ((_numKeyEvents = (_inputBuffer[0] & 0x0F)) != 0) { // We could read each key event waiting in a synchronous loop, which may prove preferable // but for now, schedule an async read of the first key event in the queue _commandBuffer[0] = REG_KEY_EVENT_A; I2CManager.read(_I2CAddress, _inputBuffer, 1, _commandBuffer, 1, &_i2crb); // non-blocking read _readState = RDS_KEYCODE; // Shift to reading key events! } else // We found no key events waiting, return to IDLE _readState = RDS_IDLE; } else { // RDS_KEYCODE uint8_t key = _inputBuffer[0] & 0x7F; bool keyDown = _inputBuffer[0] & 0x80; // Check for just keypad events key--; // R0/C0 is key #1, so subtract 1 to create an array offset // We only want to record key events we're configured for, as we have calloc'd an // appropriately sized _digitalInputStates array! if (key < _nPins) { if (keyDown) _digitalInputStates[key / 8] |= (1 << (key % 8)); else _digitalInputStates[key / 8] &= ~(1 << (key % 8)); } else DIAG(F("TCA8418 I2C: key event %d discarded, outside Vpin range"), key); _numKeyEvents--; // One less key event to get if (_numKeyEvents != 0) { // DIAG(F("TCA8418 I2C: more keys in read event queue, # waiting is: %x"), _numKeyEvents); // We could read each key event waiting in a synchronous loop, which may prove preferable // but for now, schedule an async read of the first key event in the queue _commandBuffer[0] = REG_KEY_EVENT_A; I2CManager.read(_I2CAddress, _inputBuffer, 1, _commandBuffer, 1, &_i2crb); // non-blocking read } else { // DIAG(F("TCA8418 I2C: no more keys in read event queue")); // Clear any pending interrupts I2CManager.write(_I2CAddress, 2, REG_INT_STAT, REG_STAT_K_INT); _readState = RDS_IDLE; // Shift to IDLE return; } } } else reportError(status, false); // report eror but don't go offline. } // If we're not doing anything now, check to see if we have an interrupt pin configured and it is low, // or if our timer has elapsed and we should check anyway in case the interrupt pin is disconnected. if (_readState == RDS_IDLE) { if ((_gpioInterruptsEnabled && !digitalRead(_gpioInterruptPin)) || ((currentMicros - _lastEventRead) > _eventRefresh)) { _commandBuffer[0] = REG_KEY_LCK_EC; I2CManager.read(_I2CAddress, _inputBuffer, 1, _commandBuffer, 1, &_i2crb); // non-blocking read _lastEventRead = currentMicros; _readState = RDS_EVENT; // Shift to looking for key events! } } } // Display device information and status void _display() override { DIAG(F("TCA8418 I2C:%s Vpins %u-%u%S"), _I2CAddress.toString(), _firstVpin, (_firstVpin+_nPins-1), _deviceState == DEVSTATE_FAILED ? F(" OFFLINE") : F("")); if (_gpioInterruptsEnabled) DIAG(F("TCA8418 I2C:Interrupt on pin %d"), _gpioInterruptPin); } // Helper function for error handling void reportError(uint8_t status, bool fail=true) { DIAG(F("TCA8418 I2C:%s Error:%d (%S)"), _I2CAddress.toString(), status, I2CManager.getErrorMessage(status)); if (fail) _deviceState = DEVSTATE_FAILED; } enum tca8418_registers { // REG_RESERVED = 0x00 REG_CFG = 0x01, // Configuration register REG_INT_STAT = 0x02, // Interrupt status REG_KEY_LCK_EC = 0x03, // Key lock and event counter REG_KEY_EVENT_A = 0x04, // Key event register A REG_KEY_EVENT_B = 0x05, // Key event register B REG_KEY_EVENT_C = 0x06, // Key event register C REG_KEY_EVENT_D = 0x07, // Key event register D REG_KEY_EVENT_E = 0x08, // Key event register E REG_KEY_EVENT_F = 0x09, // Key event register F REG_KEY_EVENT_G = 0x0A, // Key event register G REG_KEY_EVENT_H = 0x0B, // Key event register H REG_KEY_EVENT_I = 0x0C, // Key event register I REG_KEY_EVENT_J = 0x0D, // Key event register J REG_KP_LCK_TIMER = 0x0E, // Keypad lock1 to lock2 timer REG_UNLOCK_1 = 0x0F, // Unlock register 1 REG_UNLOCK_2 = 0x10, // Unlock register 2 REG_GPIO_INT_STAT_1 = 0x11, // GPIO interrupt status 1 REG_GPIO_INT_STAT_2 = 0x12, // GPIO interrupt status 2 REG_GPIO_INT_STAT_3 = 0x13, // GPIO interrupt status 3 REG_GPIO_DAT_STAT_1 = 0x14, // GPIO data status 1 REG_GPIO_DAT_STAT_2 = 0x15, // GPIO data status 2 REG_GPIO_DAT_STAT_3 = 0x16, // GPIO data status 3 REG_GPIO_DAT_OUT_1 = 0x17, // GPIO data out 1 REG_GPIO_DAT_OUT_2 = 0x18, // GPIO data out 2 REG_GPIO_DAT_OUT_3 = 0x19, // GPIO data out 3 REG_GPIO_INT_EN_1 = 0x1A, // GPIO interrupt enable 1 REG_GPIO_INT_EN_2 = 0x1B, // GPIO interrupt enable 2 REG_GPIO_INT_EN_3 = 0x1C, // GPIO interrupt enable 3 REG_KP_GPIO_1 = 0x1D, // Keypad/GPIO select 1 REG_KP_GPIO_2 = 0x1E, // Keypad/GPIO select 2 REG_KP_GPIO_3 = 0x1F, // Keypad/GPIO select 3 REG_GPI_EM_1 = 0x20, // GPI event mode 1 REG_GPI_EM_2 = 0x21, // GPI event mode 2 REG_GPI_EM_3 = 0x22, // GPI event mode 3 REG_GPIO_DIR_1 = 0x23, // GPIO data direction 1 REG_GPIO_DIR_2 = 0x24, // GPIO data direction 2 REG_GPIO_DIR_3 = 0x25, // GPIO data direction 3 REG_GPIO_INT_LVL_1 = 0x26, // GPIO edge/level detect 1 REG_GPIO_INT_LVL_2 = 0x27, // GPIO edge/level detect 2 REG_GPIO_INT_LVL_3 = 0x28, // GPIO edge/level detect 3 REG_DEBOUNCE_DIS_1 = 0x29, // Debounce disable 1 REG_DEBOUNCE_DIS_2 = 0x2A, // Debounce disable 2 REG_DEBOUNCE_DIS_3 = 0x2B, // Debounce disable 3 REG_GPIO_PULL_1 = 0x2C, // GPIO pull-up disable 1 REG_GPIO_PULL_2 = 0x2D, // GPIO pull-up disable 2 REG_GPIO_PULL_3 = 0x2E, // GPIO pull-up disable 3 // REG_RESERVED = 0x2F }; enum tca8418_config_reg_fields { // Config Register #1 fields REG_CFG_AI = 0x80, // Auto-increment for read/write REG_CFG_GPI_E_CGF = 0x40, // Event mode config REG_CFG_OVR_FLOW_M = 0x20, // Overflow mode enable REG_CFG_INT_CFG = 0x10, // Interrupt config REG_CFG_OVR_FLOW_IEN = 0x08, // Overflow interrupt enable REG_CFG_K_LCK_IEN = 0x04, // Keypad lock interrupt enable REG_CFG_GPI_IEN = 0x02, // GPI interrupt enable REG_CFG_KE_IEN = 0x01, // Key events interrupt enable }; enum tca8418_int_status_fields { // Interrupt Status Register #2 fields REG_STAT_CAD_INT = 0x10, // Ctrl-alt-del seq status REG_STAT_OVR_FLOW_INT = 0x08, // Overflow interrupt status REG_STAT_K_LCK_INT = 0x04, // Key lock interrupt status REG_STAT_GPI_INT = 0x02, // GPI interrupt status REG_STAT_K_INT = 0x01, // Key events interrupt status }; enum tca8418_lock_ec_fields { // Key Lock Event Count Register #3 REG_LCK_EC_K_LCK_EN = 0x40, // Key lock enable REG_LCK_EC_LCK_2 = 0x20, // Keypad lock status 2 REG_LCK_EC_LCK_1 = 0x10, // Keypad lock status 1 REG_LCK_EC_KLEC_3 = 0x08, // Key event count bit 3 REG_LCK_EC_KLEC_2 = 0x04, // Key event count bit 2 REG_LCK_EC_KLEC_1 = 0x02, // Key event count bit 1 REG_LCK_EC_KLEC_0 = 0x01, // Key event count bit 0 }; }; #endif ================================================ FILE: IO_TM1638.cpp ================================================ /* * © 2024, Chris Harlow. All rights reserved. * * This file is part of DCC++EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* Credit to https://github.com/dvarrel/TM1638 for the basic formulae.*/ #include #include "IODevice.h" #include "IO_TM1638.h" #include "DIAG.h" const uint8_t HIGHFLASH _digits[16]={ 0b00111111,0b00000110,0b01011011,0b01001111, 0b01100110,0b01101101,0b01111101,0b00000111, 0b01111111,0b01101111,0b01110111,0b01111100, 0b00111001,0b01011110,0b01111001,0b01110001 }; // Constructor TM1638::TM1638(VPIN firstVpin, byte clk_pin,byte dio_pin,byte stb_pin){ _firstVpin = firstVpin; _nPins = 8; _clk_pin = clk_pin; _stb_pin = stb_pin; _dio_pin = dio_pin; pinMode(clk_pin,OUTPUT); pinMode(stb_pin,OUTPUT); pinMode(dio_pin,OUTPUT); _pulse = PULSE1_16; _buttons=0; _leds=0; _lastLoop=micros(); addDevice(this); } void TM1638::create(VPIN firstVpin, byte clk_pin,byte dio_pin,byte stb_pin) { if (checkNoOverlap(firstVpin,8)) new TM1638(firstVpin, clk_pin,dio_pin,stb_pin); } void TM1638::_begin() { displayClear(); test(); _display(); } void TM1638::_loop(unsigned long currentMicros) { if (currentMicros - _lastLoop > (1000000UL/LoopHz)) { _buttons=getButtons();// Read the buttons _lastLoop=currentMicros; } } void TM1638::_display() { DIAG(F("TM1638 Configured on Vpins:%u-%u"), _firstVpin, _firstVpin+_nPins-1); } // digital read gets button state int TM1638::_read(VPIN vpin) { byte pin=vpin - _firstVpin; bool result=bitRead(_buttons,pin); // DIAG(F("TM1638 read (%d) buttons %x = %d"),pin,_buttons,result); return result; } // digital write sets led state void TM1638::_write(VPIN vpin, int value) { // TODO.. skip if no state change writeLed(vpin - _firstVpin + 1,value!=0); } // Analog write sets digit displays void TM1638::_writeAnalogue(VPIN vpin, int lowBytes, uint8_t mode, uint16_t highBytes) { // mode is in DataFormat defined above. byte formatLength=mode & 0x0F; // last 4 bits byte formatType=mode & 0xF0; // int8_t leftDigit=vpin-_firstVpin; // 0..7 from left int8_t rightDigit=leftDigit+formatLength-1; // 0..7 from left // loading is done right to left startDigit first int8_t startDigit=7-rightDigit; // reverse as 7 on left int8_t lastDigit=7-leftDigit; // reverse as 7 on left uint32_t value=highBytes; value<<=16; value |= (uint16_t)lowBytes; //DIAG(F("TM1638 fl=%d ft=%x sd=%d ld=%d v=%l vx=%X"), // formatLength,formatType,startDigit,lastDigit,value,value); while(startDigit<=lastDigit) { switch (formatType) { case _DF_DECIMAL:// decimal (leading zeros) displayDig(startDigit,GETHIGHFLASH(_digits,(value%10))); value=value/10; break; case _DF_HEX:// HEX (leading zeros) displayDig(startDigit,GETHIGHFLASH(_digits,(value & 0x0F))); value>>=4; break; case _DF_RAW:// Raw 7-segment pattern displayDig(startDigit,value & 0xFF); value>>=8; break; default: DIAG(F("TM1368 invalid mode 0x%x"),mode); return; } startDigit++; } } uint8_t TM1638::getButtons(){ ArduinoPins::fastWriteDigital(_stb_pin, LOW); writeData(INSTRUCTION_READ_KEY); pinMode(_dio_pin, INPUT); ArduinoPins::fastWriteDigital(_clk_pin, LOW); uint8_t buttons=0; for (uint8_t eachByte=0; eachByte<4;eachByte++) { uint8_t value = 0; for (uint8_t eachBit = 0; eachBit < 8; eachBit++) { ArduinoPins::fastWriteDigital(_clk_pin, HIGH); value |= ArduinoPins::fastReadDigital(_dio_pin) << eachBit; ArduinoPins::fastWriteDigital(_clk_pin, LOW); } buttons |= value << eachByte; delayMicroseconds(1); } pinMode(_dio_pin, OUTPUT); ArduinoPins::fastWriteDigital(_stb_pin, HIGH); return buttons; } void TM1638::displayDig(uint8_t digitId, uint8_t pgfedcba){ if (digitId>7) return; setDataInstruction(DISPLAY_TURN_ON | _pulse); setDataInstruction(INSTRUCTION_WRITE_DATA| INSTRUCTION_ADDRESS_FIXED); writeDataAt(FIRST_DISPLAY_ADDRESS+14-(digitId*2), pgfedcba); } void TM1638::displayClear(){ setDataInstruction(DISPLAY_TURN_ON | _pulse); setDataInstruction(INSTRUCTION_WRITE_DATA | INSTRUCTION_ADDRESS_FIXED); for (uint8_t i=0;i<15;i+=2){ writeDataAt(FIRST_DISPLAY_ADDRESS+i,0x00); } } void TM1638::writeLed(uint8_t num,bool state){ if ((num<1) | (num>8)) return; setDataInstruction(DISPLAY_TURN_ON | _pulse); setDataInstruction(INSTRUCTION_WRITE_DATA | INSTRUCTION_ADDRESS_FIXED); writeDataAt(FIRST_DISPLAY_ADDRESS + (num*2-1), state); } void TM1638::writeData(uint8_t data){ for (uint8_t i = 0; i < 8; i++) { ArduinoPins::fastWriteDigital(_dio_pin, data & 1); data >>= 1; ArduinoPins::fastWriteDigital(_clk_pin, HIGH); ArduinoPins::fastWriteDigital(_clk_pin, LOW); } } void TM1638::writeDataAt(uint8_t displayAddress, uint8_t data){ ArduinoPins::fastWriteDigital(_stb_pin, LOW); writeData(displayAddress); writeData(data); ArduinoPins::fastWriteDigital(_stb_pin, HIGH); delayMicroseconds(1); } void TM1638::setDataInstruction(uint8_t dataInstruction){ ArduinoPins::fastWriteDigital(_stb_pin, LOW); writeData(dataInstruction); ArduinoPins::fastWriteDigital(_stb_pin, HIGH); delayMicroseconds(1); } void TM1638::test(){ DIAG(F("TM1638 test")); uint8_t val=0; for(uint8_t i=0;i<5;i++){ setDataInstruction(DISPLAY_TURN_ON | _pulse); setDataInstruction(INSTRUCTION_WRITE_DATA| INSTRUCTION_ADDRESS_AUTO); ArduinoPins::fastWriteDigital(_stb_pin, LOW); writeData(FIRST_DISPLAY_ADDRESS); for(uint8_t i=0;i<16;i++) writeData(val); ArduinoPins::fastWriteDigital(_stb_pin, HIGH); delay(1000); val = ~val; } } ================================================ FILE: IO_TM1638.h ================================================ /* * © 2024, Chris Harlow. All rights reserved. * * This file is part of DCC++EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef IO_TM1638_h #define IO_TM1638_h #include #include "IODevice.h" #include "DIAG.h" class TM1638 : public IODevice { private: uint8_t _buttons; uint8_t _leds; unsigned long _lastLoop; static const int LoopHz=20; static const byte INSTRUCTION_WRITE_DATA=0x40, INSTRUCTION_READ_KEY=0x42, INSTRUCTION_ADDRESS_AUTO=0x40, INSTRUCTION_ADDRESS_FIXED=0x44, INSTRUCTION_NORMAL_MODE=0x40, INSTRUCTION_TEST_MODE=0x48, FIRST_DISPLAY_ADDRESS=0xC0, DISPLAY_TURN_OFF=0x80, DISPLAY_TURN_ON=0x88; uint8_t _clk_pin; uint8_t _stb_pin; uint8_t _dio_pin; uint8_t _pulse; bool _isOn; // Constructor TM1638(VPIN firstVpin, byte clk_pin,byte dio_pin,byte stb_pin); public: enum DigitFormat : byte { // last 4 bits are length. // DF_1.. DF_8 decimal DF_1=0x01,DF_2=0x02,DF_3=0x03,DF_4=0x04, DF_5=0x05,DF_6=0x06,DF_7=0x07,DF_8=0x08, // DF_1X.. DF_8X HEX DF_1X=0x11,DF_2X=0x12,DF_3X=0x13,DF_4X=0x14, DF_5X=0x15,DF_6X=0x16,DF_7X=0x17,DF_8X=0x18, // DF_1R .. DF_4R raw 7 segmnent data // only 4 because HAL analogWrite only passes 4 bytes DF_1R=0x21,DF_2R=0x22,DF_3R=0x23,DF_4R=0x24, // bits of data conversion type (ored with length) _DF_DECIMAL=0x00,// right adjusted decimal unsigned leading zeros _DF_HEX=0x10, // right adjusted hex leading zeros _DF_RAW=0x20 // bytes are raw 7-segment pattern (max length 4) }; static void create(VPIN firstVpin, byte clk_pin,byte dio_pin,byte stb_pin); // Functions overridden in IODevice void _begin(); void _loop(unsigned long currentMicros) override ; void _writeAnalogue(VPIN vpin, int value, uint8_t param1, uint16_t param2) override; void _display() override ; int _read(VPIN pin) override; void _write(VPIN pin,int value) override; // Device driving functions private: enum pulse_t { PULSE1_16, PULSE2_16, PULSE4_16, PULSE10_16, PULSE11_16, PULSE12_16, PULSE13_16, PULSE14_16 }; /** * @fn getButtons * @return state of 8 buttons */ uint8_t getButtons(); /** * @fn writeLed * @brief put led ON or OFF * @param num num of led(1-8) * @param state (true or false) */ void writeLed(uint8_t num, bool state); /** * @fn displayDig * @brief set 7 segment display + dot * @param digitId num of digit(0-7) * @param val value 8 bits */ void displayDig(uint8_t digitId, uint8_t pgfedcba); /** * @fn displayClear * @brief switch off all leds and segment display */ void displayClear(); void test(); void writeData(uint8_t data); void writeDataAt(uint8_t displayAddress, uint8_t data); void setDisplayMode(uint8_t displayMode); void setDataInstruction(uint8_t dataInstruction); }; #endif ================================================ FILE: IO_TouchKeypad.h ================================================ /* * © 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 . */ /* * 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 ================================================ FILE: IO_VL53L0X.h ================================================ /* * © 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 . */ /* * The VL53L0X Time-Of-Flight sensor operates by sending a short laser pulse and detecting * the reflection of the pulse. The time between the pulse and the receipt of reflections * is measured and used to determine the distance to the reflecting object. * * For economy of memory and processing time, this driver includes only part of the code * that ST provide in their API. Also, the API code isn't very clear and it is not easy * to identify what operations are useful and what are not. * The operation shown here doesn't include any calibration, so is probably not as accurate * as using the full driver, but it's probably accurate enough for the purpose. * * The device driver allocates up to 3 vpins to the device. A digital read on the first pin * will return a value that indicates whether the object is within the threshold range (1) * or not (0). An analogue read on the first pin returns the last measured distance (in mm), * the second pin returns the signal strength, and the third pin returns detected * ambient light level. By default the device takes around 60ms to complete a ranging * operation, so we do a 100ms cycle (10 samples per second). * * The VL53L0X is initially set to respond to I2C address 0x29. If you only have one module, * you can use this address. However, the address can be modified by software. If * you select another address, that address will be written to the device and used until the device is reset. * * 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, * 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. The process is described in ST Microelectronics application * note AN4846. * * 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: * * Single VL53L0X module: * VL53L0X::create(firstVpin, nPins, i2cAddress, lowThreshold, highThreshold); * Where firstVpin is the first vpin reserved for reading the device, * nPins is 1, 2 or 3, * i2cAddress is the address of the device (normally 0x29), * lowThreshold is the distance at which the digital vpin state is set to 1 (in mm), * and highThreshold is the distance at which the digital vpin state is set to 0 (in mm). * * Multiple VL53L0X modules: * VL53L0X::create(firstVpin, nPins, i2cAddress, lowThreshold, highThreshold, xshutPin); * ... * Where firstVpin is the first vpin reserved for reading the device, * nPins is 1, 2 or 3, * i2cAddress is the address of the device (any valid address except 0x29), * 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. The digital output may be an Arduino pin or an * I/O extender pin. * * Example: * In mySetup function within mySetup.cpp: * VL53L0X::create(4000, 3, 0x29, 200, 250); * Sensor::create(4000, 4000, 0); // Create a sensor * * When an object comes within 200mm of the sensor, a message * * will be sent over the serial USB, and when the object moves more than 250mm from the sensor, * a message * * will be sent. * */ #ifndef IO_VL53L0X_h #define IO_VL53L0X_h #include "IODevice.h" class VL53L0X : public IODevice { private: uint16_t _ambient; uint16_t _distance; uint16_t _signal; uint16_t _onThreshold; uint16_t _offThreshold; VPIN _xshutPin; bool _value; 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, STATE_RESTARTMODULE, STATE_CONFIGUREADDRESS, STATE_CONFIGUREDEVICE, STATE_INITIATESCAN, STATE_CHECKSTATUS, STATE_GETRESULTS, STATE_DECODERESULTS, STATE_FAILED, }; // Register addresses enum : uint8_t { VL53L0X_REG_SYSRANGE_START=0x00, VL53L0X_REG_RESULT_INTERRUPT_STATUS=0x13, VL53L0X_REG_RESULT_RANGE_STATUS=0x14, VL53L0X_CONFIG_PAD_SCL_SDA__EXTSUP_HV=0x89, VL53L0X_REG_I2C_SLAVE_DEVICE_ADDRESS=0x8A, }; const uint8_t VL53L0X_I2C_DEFAULT_ADDRESS=0x29; 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 = (nPins > 3) ? 3 : nPins; _I2CAddress = i2cAddress; _onThreshold = onThreshold; _offThreshold = offThreshold; _xshutPin = xshutPin; _value = 0; addDevice(this); } void _begin() override { // 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: 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: // Then write the desired I2C address to the device, while this is the only // module responding to the default address. { #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: // 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 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:%s device not responding"), _I2CAddress.toString()); _deviceState = DEVSTATE_FAILED; _nextState = STATE_FAILED; } 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); _nextState = STATE_CHECKSTATUS; break; case STATE_CHECKSTATUS: status = _rb.status; if (status == I2C_STATUS_PENDING) return; // try next time if (status != I2C_STATUS_OK) { reportError(status); } else _nextState = STATE_GETRESULTS; delayUntil(currentMicros + 95000); // wait for 95 ms before checking. break; case STATE_GETRESULTS: // Ranging completed. Request results _outBuffer[0] = VL53L0X_REG_RESULT_RANGE_STATUS; I2CManager.read(_I2CAddress, _inBuffer, 12, _outBuffer, 1, &_rb); delayUntil(currentMicros + 5000); // Allow 5ms to get data _nextState = STATE_DECODERESULTS; break; case STATE_DECODERESULTS: // If I2C write still busy, return. status = _rb.status; if (status == I2C_STATUS_PENDING) return; // try again next time if (status == I2C_STATUS_OK) { if (!(_inBuffer[0] & 1)) return; // device still busy uint8_t deviceRangeStatus = ((_inBuffer[0] & 0x78) >> 3); if (deviceRangeStatus == 0x0b) { // Range status OK, so use data _ambient = makeuint16(_inBuffer[7], _inBuffer[6]); _signal = makeuint16(_inBuffer[9], _inBuffer[8]); _distance = makeuint16(_inBuffer[11], _inBuffer[10]); if (_distance <= _onThreshold) _value = true; else if (_distance > _offThreshold) _value = false; } // Completed. Restart scan on next loop entry. _nextState = STATE_INITIATESCAN; } else { reportError(status); } 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; switch (pin) { case 0: return _distance; case 1: return _signal; case 2: return _ambient; default: return -1; } } // For digital read, return zero for all but first pin. int _read(VPIN vpin) override { if (vpin == _firstVpin) return _value; else return 0; } void _display() override { 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("")); } private: inline uint16_t makeuint16(byte lsb, byte msb) { return (((uint16_t)msb) << 8) | lsb; } uint8_t write_reg(uint8_t reg, uint8_t data) { // write byte to register uint8_t outBuffer[2]; outBuffer[0] = reg; outBuffer[1] = data; 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, ®, 1); return _inBuffer[0]; } }; bool VL53L0X::_addressConfigInProgress = false; #endif // IO_VL53L0X_h ================================================ FILE: IO_XL9535.h ================================================ /* * © 2026, Terry Wheatcroft & Chris Harlow * All rights reserved. * * This file is part of DCC++EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef io_xl9535_h #define io_xl9535_h #include "IO_GPIOBase.h" #include "FSH.h" ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for XL9535 16-bit I/O expander relay board. * Since this board is effectively an output-only board, it has no I2C read code. */ class XL9535 : public GPIOBase { public: static void create(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress) { if (checkNoOverlap(vpin, nPins, i2cAddress)) new XL9535(vpin,nPins, i2cAddress); } private: // Constructor XL9535(VPIN vpin, uint8_t nPins, I2CAddress I2CAddress) : GPIOBase((FSH *)F("XL9535"), vpin, nPins, I2CAddress,-1) { } void _writeGpioPort() override { I2CManager.write(_I2CAddress, 3, REG_OUTPUT_P0, _portOutputState, _portOutputState>>8); } void _writePullups() override {} void _writePortModes() override { // Write 0 to REG_CONF_P0 & REG_CONF_P1 as all pins are output I2CManager.write(_I2CAddress, 3, REG_CONF_P0, 0, 0); } void _readGpioPort(bool immediate) override { (void) immediate; _portInputState = _portOutputState; } void _setupDevice() override { // HAL API calls _writeGpioPort(); } enum { REG_OUTPUT_P0 = 0x02, REG_OUTPUT_P1 = 0x03, REG_POL_INV_P0 = 0x04, REG_POL_INV_P1 = 0x05, REG_CONF_P0 = 0x06, REG_CONF_P1 = 0x07, }; }; #endif ================================================ FILE: IO_duinoNodes.h ================================================ /* * © 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 . */ #ifndef IO_duinoNodes_h #define IO_duinoNodes_h #include #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 ================================================ FILE: IO_trainbrains.h ================================================ /* * © 2023-2025, Chris Harlow. All rights reserved. * © 2021, Neil McKechnie. All rights reserved. * * This file is part of DCC++EX API * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef io_trainbrains_h #define io_trainbrains_h #include "IO_GPIOBase.h" #include "FSH.h" ///////////////////////////////////////////////////////////////////////////////////////////////////// /* * IODevice subclass for Trainbrains devices. * For details see * https://trainbrains.eu/wp-content/uploads/trainbrains-railroad-modules-communication-1.2-en.pdf */ // TODO - use non-blocking I2C // TODO - support for all-channels sensor read via new command code enum TrackUnoccupancy { TRACK_UNOCCUPANCY_UNKNOWN = 0, TRACK_OCCUPIED = 1, TRACK_UNOCCUPIED = 2 }; // generic class for self-identifying Trainbrains devices class Trainbrains : public IODevice { public: static void create(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress,bool debug=false) { if (checkNoOverlap(vpin, nPins, i2cAddress)) new Trainbrains(vpin, nPins, i2cAddress,debug); } private: static const byte DT_Unknown=0; static const byte DT_Signal=1; static const byte DT_Turnout=2; static const byte DT_Power=3; static const byte DT_Track=4; bool debugme; byte deviceType=0; // 0=none, 1=signal, 2=turnout, 3=power, 4=track uint8_t outputBuffer[10]; uint8_t inputBuffer[10]; // Constructor Trainbrains(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress, bool debug) { debugme=debug; _firstVpin = vpin; _nPins = nPins; _I2CAddress=i2cAddress; outputBuffer[2]=0; // will increment with each command addDevice(this); } void issueCommand(byte code, byte p0, byte dane0=0, byte dane1=0, byte dane2=0, byte dane3=0) { outputBuffer[0] = (uint8_t)_I2CAddress; // strips away the mux part. outputBuffer[1] = code; outputBuffer[2] ++; // increment the command counter outputBuffer[3] =p0; outputBuffer[4] =0; outputBuffer[5] =0; outputBuffer[6] =dane0; outputBuffer[7] =dane1; outputBuffer[8] =dane2; outputBuffer[9] =dane3; memset(inputBuffer, 0, sizeof(inputBuffer)); // clear input buffer auto status=I2CManager.read(_I2CAddress, inputBuffer, sizeof(inputBuffer), outputBuffer, sizeof(outputBuffer) ); if (status!=I2C_STATUS_OK) { DIAG(F("Trainbrains I2C:%s Error:%S"), _I2CAddress.toString(), I2CManager.getErrorMessage(status)); _deviceState = DEVSTATE_FAILED; } else { if (debugme) _dumpBuffers(); } } void _dumpBuffers() { StringFormatter::send(&USB_SERIAL,F("<* TB %s\n out:"),_I2CAddress.toString()); for (byte i=0;i\n")); } void _begin() override { issueCommand(20,0); // read device type deviceType=inputBuffer[6]; // 0=notFound 1=signal, 2=turnout, 3=power, 4=track if (deviceType == DT_Unknown) { // device not found _deviceState = DEVSTATE_FAILED; } else { issueCommand(20,3); // read channels supported if (_nPins>inputBuffer[6]) _nPins=inputBuffer[6]; // max channels supported } _display(); } // Display details of this device. void _display() { DIAG(F("Trainbrains type:%d I2C:%s Configured on Vpins:%u-%u %S"), deviceType, _I2CAddress.toString(), (int)_firstVpin, (int)_firstVpin+_nPins-1, (_deviceState==DEVSTATE_FAILED) ? F("OFFLINE") : F("")); } // Digital Write will be from a power set or a turnout set void _write(VPIN vpin,int value) override { if (deviceType!=DT_Turnout && deviceType!=DT_Power) return; int16_t pin=vpin-_firstVpin; issueCommand(12,pin+1,value?2:1); // write command } // Read will be from a sensor poll int _read(VPIN vpin) override { if (deviceType!=DT_Track) return 0; byte pin=vpin-_firstVpin; issueCommand(14,pin+1); // read channel status return (inputBuffer[6] == TRACK_OCCUPIED ); } // analog write is for signal mask and state. // parameters are arranged to be compatible with using // neopixel commands where R,G,B values are mapped to the // aspect, flashing and state values. void _writeAnalogue(VPIN vpin, int value, uint8_t param1=0, uint16_t param2=0) override { (void)param2; if (deviceType!=DT_Signal) return; int16_t pin=vpin-_firstVpin; issueCommand(13,pin+1,value>>8,value & 0xff,param1); // write command } }; // class retained for backward compatibility. Builds the generic class. class Trainbrains02 { public: static void create(VPIN vpin, uint8_t nPins, I2CAddress i2cAddress, bool debug=false) { Trainbrains::create(vpin, nPins, i2cAddress,debug); } }; #endif ================================================ FILE: KeywordHasher.h ================================================ /* * © 2024 Vincent Hamp and Chris Harlow * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ /* Reader be aware: This function implements the _hk data type so that a string keyword is hashed to the same value as the DCCEXParser uses to hash incoming keywords. Thus "MAIN"_hk generates exactly the same run time vakue as const int16_t HASH_KEYWORD_MAIN=11339 */ #ifndef KeywordHasher_h #define KeywordHasher_h #include constexpr uint16_t CompiletimeKeywordHasher(const char * sv, uint16_t running=0) { return (*sv==0) ? running : CompiletimeKeywordHasher(sv+1, (*sv >= '0' && *sv <= '9') ? (10*running+*sv-'0') // Numeric hash : ((running << 5) + running) ^ *sv ); // } constexpr int16_t operator""_hk(const char * keyword, size_t len) { return (int16_t) CompiletimeKeywordHasher(keyword,len*0); } /* Some historical values for testing: const int16_t HASH_KEYWORD_MAIN = 11339; const int16_t HASH_KEYWORD_SLOW = -17209; const int16_t HASH_KEYWORD_SPEED28 = -17064; const int16_t HASH_KEYWORD_SPEED128 = 25816; */ static_assert("MAIN"_hk == 11339,"Keyword hasher error"); static_assert("SLOW"_hk == -17209,"Keyword hasher error"); static_assert("SPEED28"_hk == -17064,"Keyword hasher error"); static_assert("SPEED128"_hk == 25816,"Keyword hasher error"); // Compile time converter from "abcd"_s7 to the 7 segment nearest equivalent constexpr uint8_t seg7Digits[]={ 0b00111111,0b00000110,0b01011011,0b01001111, // 0..3 0b01100110,0b01101101,0b01111101,0b00000111, // 4..7 0b01111111,0b01101111 // 8..9 }; constexpr uint8_t seg7Letters[]={ 0b01110111,0b01111100,0b00111001,0b01011110, // ABCD 0b01111001,0b01110001,0b00111101,0b01110110, // EFGH 0b00000100,0b00011110,0b01110010,0b00111000, //IJKL 0b01010101,0b01010100,0b01011100,0b01110011, // MNOP 0b10111111,0b01010000,0b01101101,0b01111000, // QRST 0b00111110,0b00011100,0b01101010,0b01001001, //UVWX 0b01100110,0b01011011 //YZ }; constexpr uint8_t seg7Space=0b00000000; constexpr uint8_t seg7Minus=0b01000000; constexpr uint8_t seg7Equals=0b01001000; constexpr uint32_t CompiletimeSeg7(const char * sv, uint32_t running, size_t rlen) { return (*sv==0 || rlen==0) ? running << (8*rlen) : CompiletimeSeg7(sv+1, (*sv >= '0' && *sv <= '9') ? (running<<8) | seg7Digits[*sv-'0'] : (*sv >= 'A' && *sv <= 'Z') ? (running<<8) | seg7Letters[*sv-'A'] : (*sv >= 'a' && *sv <= 'z') ? (running<<8) | seg7Letters[*sv-'a'] : (*sv == '-') ? (running<<8) | seg7Minus : (*sv == '=') ? (running<<8) | seg7Equals : (running<<8) | seg7Space, rlen-1 ); // } constexpr uint32_t operator""_s7(const char * keyword, size_t len) { return CompiletimeSeg7(keyword,0*len,4); } #endif ================================================ FILE: LCN.cpp ================================================ /* * © 2021, Chris Harlow. All rights reserved. * * This file is part of DCC-EX 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 . */ #include "LCN.h" #include "DIAG.h" #include "Turnouts.h" #include "Sensors.h" int LCN::id = 0; Stream * LCN::stream=NULL; bool LCN::firstLoop=true; void LCN::init(Stream & lcnstream) { stream=&lcnstream; DIAG(F("LCN connection setup")); } // Inbound LCN traffic is postfix notation... nnnX where nnn is an id, X is the opcode void LCN::loop() { if (!stream) return; if (firstLoop) { firstLoop=false; stream->println('X'); return; } while (stream->available()) { int ch = stream->read(); 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'); 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') { if (Diag::LCN) DIAG(F("LCN IN %d%c"),id,(char)ch); Sensor * ss = Sensor::get(id); if (!ss) ss = Sensor::create(id, VPIN_NONE, 0); // impossible pin ss->setState(ch == 'S'); id = 0; } else id = 0; // ignore any other garbage from LCN } } void LCN::send(char opcode, int id, bool state) { if (stream) { StringFormatter::send(stream,F("%c/%d/%d"), opcode, id , state); if (Diag::LCN) DIAG(F("LCN OUT %c/%d/%d"), opcode, id , state); } } ================================================ FILE: LCN.h ================================================ /* * © 2021 Harald Barth * © 2021 Fred Decker * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #ifndef LCN_h #define LCN_h #include class LCN { public: static void init(Stream & lcnstream); static void loop(); static void send(char opcode, int id, bool state); private : static bool firstLoop; static Stream * stream; static int id; }; #endif ================================================ FILE: LICENSE ================================================ GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The GNU General Public License is a free, copyleft license for software and other kinds of works. The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others. For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it. For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions. Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users. Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free. The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS 0. Definitions. "This License" refers to version 3 of the GNU General Public License. "Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. "The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations. To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work. A "covered work" means either the unmodified Program or a work based on the Program. To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. 1. Source Code. The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work. A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. The Corresponding Source for a work in source code form is that same work. 2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 3. Protecting Users' Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. 4. Conveying Verbatim Copies. You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. 5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: a) The work must carry prominent notices stating that you modified it, and giving a relevant date. b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices". c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. 6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. "Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. 7. Additional Terms. "Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or d) Limiting the use for publicity purposes of names of licensors or authors of the material; or e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. 8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10. 9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. 10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. 11. Patents. A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version". A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. 12. No Surrender of Others' Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. 13. Use with the GNU Affero General Public License. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such. 14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation. If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. 15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program 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. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . Also add information on how to contact you by electronic and paper mail. If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: Copyright (C) This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an "about box". You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see . The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read . ================================================ FILE: LiquidCrystal_I2C.cpp ================================================ /* * © 2021, Neil McKechnie. All rights reserved. * Based on the work by DFRobot, Frank de Brabander and Marco Schwartz. * * 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-EX. If not, see . */ #include #include "LiquidCrystal_I2C.h" #include "DIAG.h" // When the display powers up, it is configured as follows: // // 1. Display clear // 2. Function set: // DL = 1; 8-bit interface data // N = 0; 1-line display // F = 0; 5x8 dot character font // 3. Display on/off control: // D = 0; Display off // C = 0; Cursor off // B = 0; Blinking off // 4. Entry mode set: // I/D = 1; Increment by 1 // S = 0; No shift // // Note, however, that resetting the Arduino doesn't reset the LCD, so we // can't assume that its in that state when a sketch starts (and the // LiquidCrystal constructor is called). LiquidCrystal_I2C::LiquidCrystal_I2C(I2CAddress lcd_Addr, uint8_t lcd_cols, uint8_t lcd_rows) { _Addr = lcd_Addr; 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(_Addr)) { DIAG(F("%dx%d LCD configured on I2C:%s"), (int)lcdCols, (int)lcdRows, _Addr.toString()); _displayfunction = LCD_4BITMODE | LCD_1LINE | LCD_5x8DOTS; backlight(); } else { DIAG(F("LCD not found on I2C:%s"), _Addr.toString()); return false; } if (lcdRows > 1) { _displayfunction |= LCD_2LINE; } // according to datasheet, we need at least 40ms after power rises above 2.7V // before sending commands. Arduino can turn on way before 4.5V so we'll allow // 100 milliseconds after pulling both RS and R/W and backlight pin low expanderWrite( _backlightval); // reset expander and turn backlight off (Bit 8 =1) delay(100); // put the LCD into 4 bit mode // this is according to the hitachi HD44780 datasheet // figure 24, pg 46 // we start in 8bit mode, try to set 4 bit mode write4bits(0x03); delayMicroseconds(5000); // wait min 4.1ms // second try write4bits(0x03); delayMicroseconds(5000); // wait min 4.1ms // third go! write4bits(0x03); delayMicroseconds(5000); // finally, set to 4-bit interface write4bits(0x02); // set # lines, font size, etc. command(LCD_FUNCTIONSET | _displayfunction); // turn the display on with no cursor or blinking default _displaycontrol = LCD_DISPLAYON | LCD_CURSOROFF | LCD_BLINKOFF; display(); // Initialize to default text direction (for roman languages) _displaymode = LCD_ENTRYLEFT | LCD_ENTRYSHIFTDECREMENT; // set the entry mode command(LCD_ENTRYMODESET | _displaymode); 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 but allow plenty } void LiquidCrystal_I2C::setRowNative(byte row) { uint8_t row_offsets[] = {0x00, 0x40, 0x14, 0x54}; if (row >= lcdRows) { row = lcdRows - 1; // we count rows starting w/0 } command(LCD_SETDDRAMADDR | (row_offsets[row])); } void LiquidCrystal_I2C::display() { _displaycontrol |= LCD_DISPLAYON; command(LCD_DISPLAYCONTROL | _displaycontrol); } // Turn the (optional) backlight off/on void LiquidCrystal_I2C::noBacklight(void) { _backlightval &= ~LCD_BACKLIGHT; expanderWrite(0); } void LiquidCrystal_I2C::backlight(void) { _backlightval = LCD_BACKLIGHT; expanderWrite(0); } size_t LiquidCrystal_I2C::writeNative(uint8_t value) { send(value, Rs); return 1; } bool LiquidCrystal_I2C::isBusy() { return rb.isBusy(); } /*********** mid level commands, for sending data/cmds */ inline void LiquidCrystal_I2C::command(uint8_t value) { send(value, 0); } /************ low level data pushing commands **********/ /* According to the NXP Datasheet for the PCF8574 section 8.2: * "The master (microcontroller) sends the START condition and slave address * setting the last bit of the address byte to logic 0 for the write mode. * The PCF8574/74A acknowledges and the master then sends the data byte for * P7 to P0 to the port register. As the clock line goes HIGH, the 8-bit * data is presented on the port lines after it has been acknowledged by the * PCF8574/74A. [...] The master can then send a STOP or ReSTART condition * or continue sending data. The number of data bytes that can be sent * successively is not limited and the previous data is overwritten every * time a data byte has been sent and acknowledged." * * This driver takes advantage of this by sending multiple data bytes in succession * within a single I2C transmission. With a fast clock rate of 400kHz, the time * between successive updates of the PCF8574 outputs will be at least 2.5us. With * the default clock rate of 100kHz the time between updates will be at least 10us. * * The LCD controller HD44780, according to its datasheet, needs nominally 37us * (up to 50us) to execute a command (i.e. write to gdram, reposition, etc.). Each * command is sent in a separate I2C transmission here. The time taken to end a * transmission and start another one is a stop bit, a start bit, 8 address bits, * an ack, 8 data bits and another ack; this is at least 20 bits, i.e. >50us * at 400kHz and >200us at 100kHz. Therefore, we don't need additional delay. * * Similarly, the Enable must be set/reset for at least 450ns. This is * well within the I2C clock cycle time of 2.5us at 400kHz. Data is clocked in * to the HD44780 on the trailing edge of the Enable pin, so we set the Enable * as we present the data, then in the next byte we reset Enable without changing * the data. */ // write either command or data (8 bits) to the HD44780 LCD controller as // a single I2C transmission. void LiquidCrystal_I2C::send(uint8_t value, uint8_t mode) { mode |= _backlightval; uint8_t highnib = (((value >> 4) & 0x0f) << BACKPACK_DATA_BITS) | 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, &rb); // Write command asynchronously } // write 4 data bits to the HD44780 LCD controller. void LiquidCrystal_I2C::write4bits(uint8_t value) { uint8_t _data = ((value & 0x0f) << BACKPACK_DATA_BITS) | _backlightval; // Enable must be set/reset for at least 450ns. This is well within the // 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, &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, &rb); // Write command asynchronously } ================================================ FILE: LiquidCrystal_I2C.h ================================================ /* * © 2021, Neil McKechnie. All rights reserved. * Based on the work by DFRobot, Frank de Brabander and Marco Schwartz. * * 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 . */ #ifndef LiquidCrystal_I2C_h #define LiquidCrystal_I2C_h #include #include "Display.h" #include "I2CManager.h" // commands #define LCD_CLEARDISPLAY 0x01 #define LCD_ENTRYMODESET 0x04 #define LCD_DISPLAYCONTROL 0x08 #define LCD_FUNCTIONSET 0x20 #define LCD_SETCGRAMADDR 0x40 #define LCD_SETDDRAMADDR 0x80 // flags for display entry mode #define LCD_ENTRYRIGHT 0x00 #define LCD_ENTRYLEFT 0x02 #define LCD_ENTRYSHIFTINCREMENT 0x01 #define LCD_ENTRYSHIFTDECREMENT 0x00 // flags for display on/off control #define LCD_DISPLAYON 0x04 #define LCD_CURSOROFF 0x00 #define LCD_BLINKOFF 0x00 // flags for function set #define LCD_4BITMODE 0x00 #define LCD_2LINE 0x08 #define LCD_1LINE 0x00 #define LCD_5x8DOTS 0x00 // Bit mapping onto PCF8574 port #define BACKPACK_Rs_BIT 0 #define BACKPACK_Rw_BIT 1 #define BACKPACK_En_BIT 2 #define BACKPACK_BACKLIGHT_BIT 3 #define BACKPACK_DATA_BITS 4 // Bits 4-7 // Equivalent mask bits #define LCD_BACKLIGHT (1 << BACKPACK_BACKLIGHT_BIT) // Backlight enable #define En (1 << BACKPACK_En_BIT) // Enable bit #define Rw (1 << BACKPACK_Rw_BIT) // Read/Write bit #define Rs (1 << BACKPACK_Rs_BIT) // Register select bit class LiquidCrystal_I2C : public DisplayDevice { public: 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 lcdCols=0, lcdRows=0; I2CAddress _Addr; uint8_t _displayfunction; uint8_t _displaycontrol; uint8_t _displaymode; uint8_t _backlightval = 0; uint8_t outputBuffer[4]; I2CRB rb; }; #endif ================================================ FILE: LocoSlot.cpp ================================================ /* Copyright (c) 2023 Harald Barth * Copyright (c) 2025 Chris Harlow * This source 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. * * This source 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 this software. If not, see * . */ #include "LocoSlot.h" #include "StringFormatter.h" #include "DIAG.h" LocoSlot * LocoSlot::firstSlot = nullptr; LocoSlot * LocoSlot::recycler = nullptr; bool LocoSlot::chainModified = false; uint16_t LocoSlot::slotCount = 0; void LocoSlot::prepare(uint16_t locoId) { loco = locoId; speedCode=128; // default direction forward groupFlags=0; functions=0; momentum_base=0; momentumA=MOMENTUM_USE_DEFAULT; momentumD=MOMENTUM_USE_DEFAULT; targetSpeed=128; savedSpeedCode=0; snifferSpeedCode=128; // default direction forward snifferFunctions=0; consistLead=nullptr; consistNext =nullptr; consistReverse=false; // Add to start of list next = firstSlot; firstSlot = this; chainModified=true; }; /* static */ LocoSlot * LocoSlot::getSlot(uint16_t locoId, bool autoCreate) { if (locoId==0) { DIAG(F("LocoSlot::getSlot called with locoId 0")); return nullptr; } auto slot=firstSlot; for(;slot;slot=slot->next){ if (slot->loco==locoId) return slot; } if (!autoCreate) return nullptr; if (recycler) { slot=recycler; recycler=recycler->next; // slot will be rechained into list in prepare() } else { if (slotCount>=MAX_LOCOS) { DIAG(F("MAX_LOCOS %d EXCEEDED"),MAX_LOCOS); return nullptr; // Too many locos } slot=new LocoSlot(); if (!slot) return nullptr; // allocation failure slotCount++; } slot->prepare(locoId); return slot; } void LocoSlot::forget() { // remove from list if (firstSlot==this) { firstSlot=next; } else { LocoSlot * prev; for(prev=firstSlot; prev && prev->next!=this; prev=prev->next); if (prev) prev->next=next; } // add to recycler next=recycler; recycler=this; chainModified=true; } /* static */ void LocoSlot::forgetAll() { // remove entire list LocoSlot * killnext=nullptr; for (auto slot=firstSlot;slot;slot=killnext) { killnext=slot->next; delete(slot); } firstSlot=nullptr; // remove recycler killnext=nullptr; for (auto slot=recycler;slot;slot=killnext) { killnext=slot->next; delete(slot); } recycler=nullptr; chainModified=true; slotCount=0; } /* static */ void LocoSlot::dumpTable(Print * output) { StringFormatter::send(output, F("\n<* LocoSlots %d/%d size=%db"), slotCount,MAX_LOCOS,sizeof(LocoSlot)); for (auto slot=firstSlot; slot; slot=slot->next) { StringFormatter::send(output, F("\n Loco=%-5d s=%-3d f=%-11l t=%-3d"), slot->loco,slot->speedCode,slot->functions, slot->targetSpeed); if (slot->isConsistFollower()) { StringFormatter::send(output, F(" (Follows %d %s)"), slot->getConsistLead()->getLoco(), slot->isConsistReverse() ? "Reversed":"Normal"); } else { StringFormatter::send(output, F(" mA=%-3d mD=%-3d"), slot->momentumA,slot->momentumD); #ifdef ARDUINO_ARCH_ESP32 StringFormatter::send(output, F(" Ss=%-3d Sf=%-11l"), slot->snifferSpeedCode,slot->snifferFunctions); #endif } } output->print(F("\n*>\n")); } void LocoSlot::saveSpeed() { savedSpeedCode=targetSpeed; } byte LocoSlot::getSavedSpeedCode() { return savedSpeedCode; } ================================================ FILE: LocoSlot.h ================================================ /* Copyright (c) 2023 Harald Barth * Copyright (c) 2025 Chris Harlow * * This source 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. * * This source 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 this software. If not, see * . */ /* this represents a slot in the loco lookup table where various loco-specific values are stored. */ #ifndef LocoSlot_h #define LocoSlot_h #include const byte MOMENTUM_USE_DEFAULT=255; class LocoSlot { private: LocoSlot() {}; void prepare(uint16_t locoId); static LocoSlot* firstSlot; static LocoSlot* recycler; static uint16_t slotCount; // Member veriables here are arranged to reduce padding waste uint32_t functions; // DCC function map uint32_t snifferFunctions; // sniffer function map uint32_t momentum_base; // millis() when speed modified under momentum LocoSlot* next; LocoSlot* consistLead; LocoSlot* consistNext; // DCC data for this loco uint16_t loco; // DCC loco id byte targetSpeed; // speed set by throttle byte speedCode; // current DCC speed and direction byte snifferSpeedCode; // sniffer speed and direction byte savedSpeedCode; // speed code saved by EXRAIL SAVE_SPEED byte momentumA; // momentum accelerating byte momentumD; // momentum decelerating byte groupFlags; // function groups acivated bool consistReverse; // true if loco is reversed in consist // SNIFFER data for each loco exists to allow sniffer to detect and ignore // sniffed reminders for locos that have been taken over // by DCCEX. These bytes will be dropped on a Mega. public: // set chainModified true when the chain of locos is modified // so that reminders can restart from the beginning. static bool chainModified; static LocoSlot * getFirst(){return firstSlot;} static void forgetAll(); static LocoSlot * getSlot(uint16_t locoId, bool autoCreate); static void dumpTable(Print *output); LocoSlot * getNext() {return next;} uint16_t getLoco() { return loco; } byte getSnifferSpeedCode() { return snifferSpeedCode; } unsigned long getSnifferFunctions() { return snifferFunctions; } void setSnifferSpeedCode(byte v) { snifferSpeedCode=v; } void setSnifferFunctions(unsigned long v) { snifferFunctions=v; } byte getMomentumA() { return momentumA; } byte getMomentumD() { return momentumD; } void setMomentumA(byte v) { momentumA=v; } void setMomentumD(byte v) { momentumD=v; } uint32_t getMomentumBase() { return momentum_base; } void setMomentumBase(uint32_t v) { momentum_base=v; } byte getTargetSpeed() { return targetSpeed; } void setTargetSpeed(byte v) { targetSpeed=v; } byte getSpeedCode() { return speedCode; } void setSpeedCode(byte v) { speedCode=v; } byte getGroupFlags() { return groupFlags; } void setGroupFlags(byte v) { groupFlags=v; } uint32_t getFunctions() { return functions; } void setFunctions(uint32_t v) { functions=v; } void forget(); void saveSpeed(); byte getSavedSpeedCode() ; LocoSlot * getConsistLead() { return consistLead; } LocoSlot * getConsistNext() { return consistNext; } void setConsistLead(LocoSlot * lead) { consistLead=lead; } void setConsistNext(LocoSlot * nextInConsist) { consistNext=nextInConsist; } bool isConsistReverse() { return consistReverse; } void setConsistReverse(bool rev) { consistReverse=rev; } bool isConsistLead() {return (consistNext != nullptr) && consistLead==nullptr; } bool isConsistFollower() {return (consistLead != nullptr); } }; #endif ================================================ FILE: MotorDriver.cpp ================================================ /* * © 2022-2024 Paul M Antoine * © 2024 Herb Morton * © 2021 Mike S * © 2021 Fred Decker * © 2020-2023 Harald Barth * © 2020-2021 Chris Harlow * © 2023 Colin Murdoch * All rights reserved. * * This file is part of CommandStation-EX * * This is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * It is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with CommandStation. If not, see . */ #include #include "MotorDriver.h" #include "DCCWaveform.h" #include "DCCTimer.h" #include "DIAG.h" #include "EXRAIL2.h" unsigned long MotorDriver::globalOverloadStart = 0; volatile portreg_t shadowPORTA; volatile portreg_t shadowPORTB; volatile portreg_t shadowPORTC; #if defined(ARDUINO_ARCH_STM32) volatile portreg_t shadowPORTD; volatile portreg_t shadowPORTE; volatile portreg_t shadowPORTF; volatile portreg_t shadowPORTG; volatile portreg_t shadowPORTH; #endif MotorDriver::MotorDriver(int16_t power_pin, byte signal_pin, byte signal_pin2, int16_t brake_pin, byte current_pin, float sense_factor, unsigned int trip_milliamps, int16_t fault_pin) { const FSH * warnString = F("** WARNING **"); 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; } if (HAVE_PORTD(fastSignalPin.inout == &PORTD)) { DIAG(F("Found PORTD pin %d"),signalPin); fastSignalPin.shadowinout = fastSignalPin.inout; fastSignalPin.inout = &shadowPORTD; } if (HAVE_PORTE(fastSignalPin.inout == &PORTE)) { DIAG(F("Found PORTE pin %d"),signalPin); fastSignalPin.shadowinout = fastSignalPin.inout; fastSignalPin.inout = &shadowPORTE; } if (HAVE_PORTF(fastSignalPin.inout == &PORTF)) { DIAG(F("Found PORTF pin %d"),signalPin); fastSignalPin.shadowinout = fastSignalPin.inout; fastSignalPin.inout = &shadowPORTF; } if (HAVE_PORTG(fastSignalPin.inout == &PORTG)) { DIAG(F("Found PORTG pin %d"),signalPin); fastSignalPin.shadowinout = fastSignalPin.inout; fastSignalPin.inout = &shadowPORTG; } if (HAVE_PORTH(fastSignalPin.inout == &PORTH)) { DIAG(F("Found PORTH pin %d"),signalPin); fastSignalPin.shadowinout = fastSignalPin.inout; fastSignalPin.inout = &shadowPORTH; } 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; } if (HAVE_PORTD(fastSignalPin2.inout == &PORTD)) { DIAG(F("Found PORTD pin %d"),signalPin2); fastSignalPin2.shadowinout = fastSignalPin2.inout; fastSignalPin2.inout = &shadowPORTD; } if (HAVE_PORTE(fastSignalPin2.inout == &PORTE)) { DIAG(F("Found PORTE pin %d"),signalPin2); fastSignalPin2.shadowinout = fastSignalPin2.inout; fastSignalPin2.inout = &shadowPORTE; } if (HAVE_PORTF(fastSignalPin2.inout == &PORTF)) { DIAG(F("Found PORTF pin %d"),signalPin2); fastSignalPin2.shadowinout = fastSignalPin2.inout; fastSignalPin2.inout = &shadowPORTF; } if (HAVE_PORTG(fastSignalPin2.inout == &PORTG)) { DIAG(F("Found PORTG pin %d"),signalPin2); fastSignalPin2.shadowinout = fastSignalPin2.inout; fastSignalPin2.inout = &shadowPORTG; } if (HAVE_PORTH(fastSignalPin2.inout == &PORTH)) { DIAG(F("Found PORTH pin %d"),signalPin2); fastSignalPin2.shadowinout = fastSignalPin2.inout; fastSignalPin2.inout = &shadowPORTH; } } else dualSignal=false; if (brake_pin!=UNUSED_PIN){ invertBrake=brake_pin < 0; if (invertBrake) brake_pin = 0-brake_pin; if (brake_pin > MAX_PIN) DIAG(F("%S Brake pin %d > %d"), warnString, brake_pin, MAX_PIN); brakePin=(byte)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(true); // start with brake on in case we hace DC stuff going on } else { brakePin=UNUSED_PIN; } currentPin=current_pin; if (currentPin!=UNUSED_PIN) { int ret = ADCee::init(currentPin); if (ret < -1010) { // XXX give value a name later DIAG(F("ADCee::init error %d, disable current pin %d"), ret, currentPin); currentPin = UNUSED_PIN; } } senseOffset=0; // value can not be obtained until waveform is activated if (fault_pin != UNUSED_PIN) { invertFault=fault_pin < 0; if (invertFault) fault_pin = 0-fault_pin; if (fault_pin > MAX_PIN) DIAG(F("%S Fault pin %d > %d"), warnString, fault_pin, MAX_PIN); faultPin=(byte)fault_pin; DIAG(F("Fault pin = %d invert %d"), faultPin, invertFault); getFastPin(F("FAULT"),faultPin, 1 /*input*/, fastFaultPin); pinMode(faultPin, INPUT); } else { faultPin=UNUSED_PIN; } // 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; #ifdef MAX_CURRENT if (MAX_CURRENT > 0 && MAX_CURRENT < tripMilliamps) tripMilliamps = MAX_CURRENT; #endif rawCurrentTripValue=mA2raw(tripMilliamps); 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("%S No current or short detection"), warnString); else { DIAG(F("Pin %d Max %dmA (%d)"), currentPin, raw2mA(rawCurrentTripValue), 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)); } progTripValue = mA2raw(TRIP_CURRENT_PROG); } bool MotorDriver::isPWMCapable() { return (!dualSignal) && DCCTimer::isPWMPin(signalPin); } void MotorDriver::setPower(POWERMODE mode) { if (powerMode == mode) return; //DIAG(F("Track %c POWERMODE=%d"), trackLetter, (int)mode); lastPowerChange[(int)mode] = micros(); if (mode == POWERMODE::OVERLOAD) globalOverloadStart = lastPowerChange[(int)mode]; bool on=(mode==POWERMODE::ON || mode ==POWERMODE::ALERT); if (on) { // 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); if (Diag::ACK) DIAG(F("Track %c sensOffset=%d"),trackLetter,senseOffset); } IODevice::write(powerPin,invertPower ? LOW : HIGH); if (isProgTrack) DCCWaveform::progTrack.clearResets(); } else { IODevice::write(powerPin,invertPower ? HIGH : LOW); } powerMode=mode; } // setBrake applies brake if on == true. So to get // voltage from the motor bride one needs to do a // setBrake(false). // If the brakePin is negative that means the sense // of the brake pin on the motor bridge is inverted // (HIGH == release brake) and setBrake does // compensate for that. // void MotorDriver::setBrake(bool on, bool interruptContext) { if (brakePin == UNUSED_PIN) return; if (!interruptContext) {noInterrupts();} if (on ^ invertBrake) setHIGH(fastBrakePin); else setLOW(fastBrakePin); if (!interruptContext) {interrupts();} } bool MotorDriver::canMeasureCurrent() { return currentPin!=UNUSED_PIN; } /* * Return the current reading as pin reading 0 to max resolution (1024 or 4096). * If the fault pin is activated return a negative current to show active fault pin. * 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(bool fromISR) { (void)fromISR; if (currentPin==UNUSED_PIN) return 0; int current; current = ADCee::read(currentPin, fromISR); // here one can diag raw value // if (fromISR == false) DIAG(F("%c: %d"), trackLetter, current); current = current-senseOffset; // adjust with offset if (current<0) current=0-current; // current >= 0 here, we use negative current as fault pin flag if ((faultPin != UNUSED_PIN) && powerPin) { if (invertFault ? isHIGH(fastFaultPin) : isLOW(fastFaultPin)) return (current == 0 ? -1 : -current); } return current; } #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<= 127) brake = 0; else brake = 2 * (128-tSpeed); { // new block because of variable f #if defined(ARDUINO_ARCH_ESP32) || defined(ARDUINO_ARCH_STM32) int f = frequency; #ifdef VARIABLE_TONES if (tSpeed > 2) { if (tSpeed <= 58) { f = taurustones[ (tSpeed-2)/2 ] ; } } #endif //DIAG(F("Brake pin %d value %d freqency %d"), brakePin, brake, f); DCCTimer::DCCEXanalogWrite(brakePin, brake, invertBrake); DCCTimer::DCCEXanalogWriteFrequency(brakePin, f); // set DC PWM frequency #else // all AVR here DCCTimer::DCCEXanalogWriteFrequency(brakePin, frequency); // frequency steps analogWrite(brakePin, invertBrake ? 255-brake : 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 if (HAVE_PORTD(fastSignalPin.shadowinout == &PORTD)) { noInterrupts(); HAVE_PORTD(shadowPORTD=PORTD); setSignal(tDir); HAVE_PORTD(PORTD=shadowPORTD); interrupts(); } else if (HAVE_PORTE(fastSignalPin.shadowinout == &PORTE)) { noInterrupts(); HAVE_PORTE(shadowPORTE=PORTE); setSignal(tDir); HAVE_PORTE(PORTE=shadowPORTE); interrupts(); } else if (HAVE_PORTF(fastSignalPin.shadowinout == &PORTF)) { noInterrupts(); HAVE_PORTF(shadowPORTF=PORTF); setSignal(tDir); HAVE_PORTF(PORTF=shadowPORTF); interrupts(); } else if (HAVE_PORTG(fastSignalPin.shadowinout == &PORTG)) { noInterrupts(); HAVE_PORTG(shadowPORTG=PORTG); setSignal(tDir); HAVE_PORTG(PORTG=shadowPORTG); interrupts(); } else if (HAVE_PORTH(fastSignalPin.shadowinout == &PORTH)) { noInterrupts(); HAVE_PORTH(shadowPORTH=PORTH); setSignal(tDir); HAVE_PORTH(PORTH=shadowPORTH); interrupts(); } else { noInterrupts(); setSignal(tDir); interrupts(); } } void MotorDriver::throttleInrush(bool on) { if (brakePin == UNUSED_PIN) return; if ( !(trackMode & (TRACK_MODE_MAIN | TRACK_MODE_PROG | TRACK_MODE_EXT | TRACK_MODE_BOOST))) return; byte duty = on ? 207 : 0; // duty of 81% at 62500Hz this gives pauses of 3usec #if defined(ARDUINO_ARCH_ESP32) if(on) { DCCTimer::DCCEXInrushControlOn(brakePin, duty, invertBrake); } else { ledcDetachPin(brakePin); // not DCCTimer::DCCEXledcDetachPin() as we have not // registered the pin in the pin to channel array } #elif defined(ARDUINO_ARCH_STM32) if(on) { DCCTimer::DCCEXanalogWriteFrequency(brakePin, 7); // 7 means max DCCTimer::DCCEXanalogWrite(brakePin,duty,invertBrake); } else { pinMode(brakePin, OUTPUT); } #else // all AVR here if (invertBrake) duty = 255-duty; if(on){ DCCTimer::DCCEXanalogWriteFrequency(brakePin, 7); // 7 means max } analogWrite(brakePin,duty); #endif } unsigned int MotorDriver::raw2mA( int raw) { //DIAG(F("%d = %d * %d / %d"), (int32_t)raw * senseFactorInternal / senseScale, raw, senseFactorInternal, senseScale); return (int32_t)raw * senseFactorInternal / senseScale; } 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. #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 result.inout = portOutputRegister(port); result.maskHIGH = digitalPinToBitMask(pin); result.maskLOW = ~result.maskHIGH; // DIAG(F(" port=0x%x, inoutpin=0x%x, isinput=%d, mask=0x%x"),port, result.inout,input,result.maskHIGH); } /////////////////////////////////////////////////////////////////////////////////////////// // checkPowerOverload(useProgLimit, trackno) // bool useProgLimit: Trackmanager knows if this track is in prog mode or in main mode // byte trackno: trackmanager knows it's number (could be skipped?) // // Short ciruit handling strategy: // // There are the following power states: ON ALERT OVERLOAD OFF // OFF state is only changed to/from manually. Power is on // during ON and ALERT. Power is off during OVERLOAD and OFF. // The overload mechanism changes between the other states like // // ON -1-> ALERT -2-> OVERLOAD -3-> ALERT -4-> ON // or // ON -1-> ALERT -4-> ON // // Times are in class MotorDriver (MotorDriver.h). // // 1. ON to ALERT: // Transition on fault pin condition or current overload // // 2. ALERT to OVERLOAD: // Transition happens if different timeouts have elapsed. // If only the fault pin is active, timeout is // POWER_SAMPLE_IGNORE_FAULT_LOW (100ms) // If only overcurrent is detected, timeout is // POWER_SAMPLE_IGNORE_CURRENT (100ms) // If fault pin and overcurrent are active, timeout is // POWER_SAMPLE_IGNORE_FAULT_HIGH (5ms) // Transition to OVERLOAD turns off power to the affected // output (unless fault pins are shared) // If the transition conditions are not fullfilled, // transition according to 4 is tested. // // 3. OVERLOAD to ALERT // Transiton happens when timeout has elapsed, timeout // is named power_sample_overload_wait. It is started // at POWER_SAMPLE_OVERLOAD_WAIT (40ms) at first entry // to OVERLOAD and then increased by a factor of 2 // at further entries to the OVERLOAD condition. This // happens until POWER_SAMPLE_RETRY_MAX (10sec) is reached. // power_sample_overload_wait is reset by a poweroff or // a POWER_SAMPLE_ALL_GOOD (5sec) period during ON. // After timeout power is turned on again and state // goes back to ALERT. // // 4. ALERT to ON // Transition happens by watching the current and fault pin // samples during POWER_SAMPLE_ALERT_GOOD (20ms) time. If // values have been good during that time, transition is // made back to ON. Note that even if state is back to ON, // the power_sample_overload_wait time is first reset // later (see above). // // The time keeping is handled by timestamps lastPowerChange[] // which are set by each power change and by lastBadSample which // keeps track if conditions during ALERT have been good enough // to go back to ON. The time differences are calculated by // microsSinceLastPowerChange(). // void MotorDriver::checkPowerOverload(bool useProgLimit, byte trackno) { switch (powerMode) { case POWERMODE::OFF: { lastPowerMode = POWERMODE::OFF; power_sample_overload_wait = POWER_SAMPLE_OVERLOAD_WAIT; break; } case POWERMODE::ON: { lastPowerMode = POWERMODE::ON; bool cF = checkFault(); bool cC = checkCurrent(useProgLimit); if(cF || cC ) { if (cC) { unsigned int mA=raw2mA(lastCurrent); DIAG(F("TRACK %c ALERT %s %dmA"), trackno + 'A', cF ? "FAULT" : "", mA); } else { DIAG(F("TRACK %c ALERT FAULT"), trackno + 'A'); } setPower(POWERMODE::ALERT); if ((trackMode & TRACK_MODIFIER_AUTO) && (trackMode & (TRACK_MODE_MAIN|TRACK_MODE_EXT|TRACK_MODE_BOOST))){ DIAG(F("TRACK %c INVERT"), trackno + 'A'); invertOutput(); } break; } // all well if (microsSinceLastPowerChange(POWERMODE::ON) > POWER_SAMPLE_ALL_GOOD) { power_sample_overload_wait = POWER_SAMPLE_OVERLOAD_WAIT; } break; } case POWERMODE::ALERT: { // set local flags that handle how much is output to diag (do not output duplicates) bool notFromOverload = (lastPowerMode != POWERMODE::OVERLOAD); bool powerModeChange = (powerMode != lastPowerMode); unsigned long now = micros(); if (powerModeChange) lastBadSample = now; lastPowerMode = POWERMODE::ALERT; // check how long we have been in this state unsigned long mslpc = microsSinceLastPowerChange(POWERMODE::ALERT); if(checkFault()) { throttleInrush(true); lastBadSample = now; unsigned long timeout = checkCurrent(useProgLimit) ? POWER_SAMPLE_IGNORE_FAULT_HIGH : POWER_SAMPLE_IGNORE_FAULT_LOW; if ( mslpc < timeout) { if (powerModeChange) DIAG(F("TRACK %c FAULT PIN (%M ignore)"), trackno + 'A', timeout); break; } DIAG(F("TRACK %c FAULT PIN detected after %4M. Pause %4M)"), trackno + 'A', mslpc, power_sample_overload_wait); throttleInrush(false); setPower(POWERMODE::OVERLOAD); break; } if (checkCurrent(useProgLimit)) { lastBadSample = now; if (mslpc < POWER_SAMPLE_IGNORE_CURRENT) { if (powerModeChange) { unsigned int mA=raw2mA(lastCurrent); DIAG(F("TRACK %c CURRENT (%M ignore) %dmA"), trackno + 'A', POWER_SAMPLE_IGNORE_CURRENT, mA); } break; } unsigned int mA=raw2mA(lastCurrent); unsigned int maxmA=raw2mA(tripValue); DIAG(F("TRACK %c POWER OVERLOAD %4dmA (max %4dmA) detected after %4M. Pause %4M"), trackno + 'A', mA, maxmA, mslpc, power_sample_overload_wait); throttleInrush(false); setPower(POWERMODE::OVERLOAD); break; } // all well unsigned long goodtime = micros() - lastBadSample; if (goodtime > POWER_SAMPLE_ALERT_GOOD) { if (true || notFromOverload) { // we did a RESTORE message XXX unsigned int mA=raw2mA(lastCurrent); DIAG(F("TRACK %c NORMAL (after %M/%M) %dmA"), trackno + 'A', goodtime, mslpc, mA); } throttleInrush(false); setPower(POWERMODE::ON); break; } if (goodtime > POWER_SAMPLE_ALERT_GOOD/2) { throttleInrush(false); } break; } case POWERMODE::OVERLOAD: { lastPowerMode = POWERMODE::OVERLOAD; unsigned long mslpc = (commonFaultPin ? (micros() - globalOverloadStart) : microsSinceLastPowerChange(POWERMODE::OVERLOAD)); if (mslpc > power_sample_overload_wait) { // adjust next wait time power_sample_overload_wait *= 2; if (power_sample_overload_wait > POWER_SAMPLE_RETRY_MAX) power_sample_overload_wait = POWER_SAMPLE_RETRY_MAX; #ifdef EXRAIL_ACTIVE DIAG(F("Calling EXRAIL")); RMFT2::powerEvent(trackno, true); // Tell EXRAIL we have an overload #endif // power on test DIAG(F("TRACK %c POWER RESTORE (after %4M)"), trackno + 'A', mslpc); setPower(POWERMODE::ALERT); } break; } default: break; } } ================================================ FILE: MotorDriver.h ================================================ /* * © 2022-2024 Paul M. Antoine * © 2021 Mike S * © 2021 Fred Decker * © 2020 Chris Harlow * © 2022,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 . */ #ifndef MotorDriver_h #define MotorDriver_h #include "FSH.h" #include "IODevice.h" #include "DCCTimer.h" #include #include "TemplateForEnums.h" // use powers of two so we can do logical and/or on the track modes in if clauses. // For example TRACK_MODE_DC_INV is (TRACK_MODE_DC|TRACK_MODIFIER_INV) enum TRACK_MODE : byte { // main modes TRACK_MODE_NONE = 1, TRACK_MODE_MAIN = 2, TRACK_MODE_PROG = 4, TRACK_MODE_DC = 8, TRACK_MODE_EXT = 16, // modifiers TRACK_MODIFIER_INV = 64, TRACK_MODIFIER_AUTO = 128, #ifdef ARDUINO_ARCH_ESP32 TRACK_MODE_BOOST = 32, TRACK_MODE_BOOST_INV = TRACK_MODE_BOOST|TRACK_MODIFIER_INV, TRACK_MODE_BOOST_AUTO = TRACK_MODE_BOOST|TRACK_MODIFIER_AUTO, #else TRACK_MODE_BOOST = 0, TRACK_MODE_BOOST_INV = 0, TRACK_MODE_BOOST_AUTO = 0, #endif // derived modes; TRACK_ALL is calles that so it does not match TRACK_MODE_* TRACK_ALL = TRACK_MODE_MAIN|TRACK_MODE_PROG|TRACK_MODE_DC|TRACK_MODE_EXT|TRACK_MODE_BOOST, TRACK_MODE_MAIN_INV = TRACK_MODE_MAIN|TRACK_MODIFIER_INV, TRACK_MODE_MAIN_AUTO = TRACK_MODE_MAIN|TRACK_MODIFIER_AUTO, TRACK_MODE_DC_INV = TRACK_MODE_DC|TRACK_MODIFIER_INV, TRACK_MODE_DCX = TRACK_MODE_DC_INV // DCX is other name for historical reasons }; #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 #define PORTD GPIOD->ODR #define HAVE_PORTD(X) X #if defined(GPIOE) #define PORTE GPIOE->ODR #define HAVE_PORTE(X) X #endif #if defined(GPIOF) #define PORTF GPIOF->ODR #define HAVE_PORTF(X) X #endif #if defined(GPIOG) #define PORTG GPIOG->ODR #define HAVE_PORTG(X) X #endif #if defined(GPIOH) #define PORTH GPIOH->ODR #define HAVE_PORTH(X) X #endif #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 #ifndef HAVE_PORTD #define HAVE_PORTD(X) byte TOKENPASTE2(Unique_, __LINE__) __attribute__((unused)) =0 #endif #ifndef HAVE_PORTE #define HAVE_PORTE(X) byte TOKENPASTE2(Unique_, __LINE__) __attribute__((unused)) =0 #endif #ifndef HAVE_PORTF #define HAVE_PORTF(X) byte TOKENPASTE2(Unique_, __LINE__) __attribute__((unused)) =0 #endif #ifndef HAVE_PORTG #define HAVE_PORTG(X) byte TOKENPASTE2(Unique_, __LINE__) __attribute__((unused)) =0 #endif #ifndef HAVE_PORTH #define HAVE_PORTH(X) byte TOKENPASTE2(Unique_, __LINE__) __attribute__((unused)) =0 #endif // Virtualised Motor shield 1-track hardware Interface #ifndef UNUSED_PIN // sync define with the one in MotorDrivers.h #define UNUSED_PIN 255 // inside uint8_t #endif #define MAX_PIN 254 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 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; extern volatile portreg_t shadowPORTD; extern volatile portreg_t shadowPORTE; extern volatile portreg_t shadowPORTF; extern volatile portreg_t shadowPORTG; extern volatile portreg_t shadowPORTH; enum class POWERMODE : byte { OFF, ON, OVERLOAD, ALERT }; class MotorDriver { public: MotorDriver(int16_t power_pin, byte signal_pin, byte signal_pin2, int16_t brake_pin, byte current_pin, float senseFactor, unsigned int tripMilliamps, int16_t fault_pin); 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) { #ifndef ARDUINO_ARCH_ESP32 if (invertPhase) high = !high; #endif 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); if (signalPin2 != UNUSED_PIN) { if (on) pinMode(signalPin2, OUTPUT); else pinMode(signalPin2, INPUT); } }; inline pinpair getSignalPin() { return pinpair(signalPin,signalPin2); }; inline int8_t getBrakePinSigned() { return invertBrake ? -brakePin : brakePin; }; void setDCSignal(byte speedByte, uint8_t frequency=0); void throttleInrush(bool on); inline void detachDCSignal() { #if defined(__arm__) pinMode(brakePin, OUTPUT); #elif defined(ARDUINO_ARCH_ESP32) DCCTimer::DCCEXledcDetachPin(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) return (brakePin != UNUSED_PIN); // This was just (true) but we probably do need to check for UNUSED_PIN! #elif defined(__arm__) // On ARM we can use digitalPinHasPWM return ((brakePin!=UNUSED_PIN) && (digitalPinHasPWM(brakePin))); #elif defined(digitalPinToTimer) return ((brakePin!=UNUSED_PIN) && (digitalPinToTimer(brakePin))); #else return (brakePin<14 && brakePin >1); #endif } inline int getRawCurrentTripValue() { return rawCurrentTripValue; } bool isPWMCapable(); bool canMeasureCurrent(); bool trackPWM = false; // this track uses PWM timer to generate the DCC waveform bool commonFaultPin = false; // This is a stupid motor shield which has only a common fault pin for both outputs inline byte setCommonFaultPin() { return commonFaultPin = true; } 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; }; // this returns how much time has passed since the last power change. If it // was really long ago (approx > 52min) advance counter approx 35 min so that // we are at 18 minutes again. Times for 32 bit unsigned long. inline unsigned long microsSinceLastPowerChange(POWERMODE mode) { unsigned long now = micros(); unsigned long diff = now - lastPowerChange[(int)mode]; if (diff > (1UL << (7 *sizeof(unsigned long)))) // 2^(4*7)us = 268.4 seconds lastPowerChange[(int)mode] = now - 30000000UL; // 30 seconds ago return diff; }; #ifdef ANALOG_READ_INTERRUPT bool sampleCurrentFromHW(); void startCurrentFromHW(); #endif inline void setMode(TRACK_MODE m) { trackMode = m; invertOutput(trackMode & TRACK_MODIFIER_INV); }; inline void invertOutput() { // toggles output inversion invertPhase = !invertPhase; invertOutput(invertPhase); }; inline void invertOutput(bool b) { // sets output inverted or not if (b) invertPhase = 1; else invertPhase = 0; #if defined(ARDUINO_ARCH_ESP32) pinpair p = getSignalPin(); uint32_t *outreg = (uint32_t *)(GPIO_FUNC0_OUT_SEL_CFG_REG + 4*p.pin); if (invertPhase) // set or clear the invert bit in the gpio out register *outreg |= ((uint32_t)0x1 << GPIO_FUNC0_OUT_INV_SEL_S); else *outreg &= ~((uint32_t)0x1 << GPIO_FUNC0_OUT_INV_SEL_S); if (p.invpin != UNUSED_PIN) { outreg = (uint32_t *)(GPIO_FUNC0_OUT_SEL_CFG_REG + 4*p.invpin); if (invertPhase) // clear or set the invert bit in the gpio out register *outreg &= ~((uint32_t)0x1 << GPIO_FUNC0_OUT_INV_SEL_S); else *outreg |= ((uint32_t)0x1 << GPIO_FUNC0_OUT_INV_SEL_S); } #endif }; inline TRACK_MODE getMode() { return trackMode; }; 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); inline void getFastPin(const FSH* type,int pin, FASTPIN & result) { getFastPin(type, pin, 0, result); }; // side effect sets lastCurrent and tripValue inline bool checkCurrent(bool useProgLimit) { tripValue= useProgLimit?progTripValue:getRawCurrentTripValue(); lastCurrent = getCurrentRaw(); if (lastCurrent < 0) lastCurrent = -lastCurrent; return lastCurrent >= tripValue; }; // side effect sets lastCurrent inline bool checkFault() { lastCurrent = getCurrentRaw(); return lastCurrent < 0; }; 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 bool invertPower; // power pin passed as negative means pin is inverted bool invertFault; // fault pin passed as negative means pin is inverted bool invertPhase = 0; // phase of out 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; // current sampling POWERMODE powerMode; POWERMODE lastPowerMode; unsigned long lastPowerChange[4]; // timestamp in microseconds unsigned long lastBadSample; // timestamp in microseconds // used to sync restore time when common Fault pin detected static unsigned long globalOverloadStart; // timestamp in microseconds int progTripValue; int lastCurrent; //temp value int tripValue; //temp value #ifdef ANALOG_READ_INTERRUPT volatile unsigned long sampleCurrentTimestamp; volatile uint16_t sampleCurrent; #endif int maxmA; int tripmA; // Times for overload management. Unit: microseconds. // Base for wait time until power is turned on again static const unsigned long POWER_SAMPLE_OVERLOAD_WAIT = 40000UL; // Time after we consider all faults old and forgotten static const unsigned long POWER_SAMPLE_ALL_GOOD = 5000000UL; // Time after which we consider a ALERT over static const unsigned long POWER_SAMPLE_ALERT_GOOD = 20000UL; // How long to ignore fault pin if current is under limit static const unsigned long POWER_SAMPLE_IGNORE_FAULT_LOW = 100000UL; // How long to ignore fault pin if current is higher than limit static const unsigned long POWER_SAMPLE_IGNORE_FAULT_HIGH = 5000UL; // How long to wait between overcurrent and turning off static const unsigned long POWER_SAMPLE_IGNORE_CURRENT = 100000UL; // Upper limit for retry period static const unsigned long POWER_SAMPLE_RETRY_MAX = 10000000UL; // 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; TRACK_MODE trackMode = TRACK_MODE_NONE; // we assume track not assigned at startup }; #endif ================================================ FILE: MotorDrivers.h ================================================ /* * © 2022-2023 Paul M. Antoine * © 2021 Fred Decker * © 2020-2024 Harald Barth * (c) 2020 Chris Harlow. All rights reserved. * (c) 2021 Fred Decker. All rights reserved. * (c) 2020 Harald Barth. All rights reserved. * (c) 2020 Anthony W - Dayton. 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 . */ #ifndef MotorDrivers_h #define MotorDrivers_h #include // *** PLEASE NOTE *** THIS FILE IS **NOT** INTENDED TO BE EDITED WHEN CONFIGURING A SYSTEM. // It will be overwritten if the library is updated. // This file contains configurations for known/supported motor shields. // A configuration defined by macro here can be used in your sketch. // A custom hardware setup will require your sketch to create MotorDriver instances // similar to those defined here, WITHOUT editing this file. You can put your // custom defines in config.h. #ifndef UNUSED_PIN // sync define with the one in MotorDriver.h #define UNUSED_PIN 255 // inside uint8_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); // // 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) // You can have a CS wihout any possibility to do any track signal. // That's strange but possible. #define NO_SHIELD F("No shield at all") // Arduino STANDARD Motor Shield, used on different architectures: #if defined(ARDUINO_ARCH_SAMD) || defined(ARDUINO_ARCH_STM32) // Standard Motor Shield definition for 3v3 processors (other than the ESP32) // Setup for SAMD21 Sparkfun DEV board MUST use Arduino 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, 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 #if defined(ARDUINO_NUCLEO_F429ZI) || defined(ARDUINO_NUCLEO_F439ZI) || defined(ARDUINO_NUCLEO_F4X9ZI) // EX 8874 based shield connected to a 3V3 system with 12-bit (4096) ADC // The Ethernet capable STM32 models cannot use Channel B BRAKE on D8, and must use the ALT pin of D6, // AND cannot use Channel B PWN on D11, but must use the ALT pin of D5 #define EX8874_SHIELD F("EX8874"), \ new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 1.27, 5000, A4), \ new MotorDriver( 5, 13, UNUSED_PIN, 6, A1, 1.27, 5000, A5) #else // EX 8874 based shield connected to a 3V3 system with 12-bit (4096) ADC #define EX8874_SHIELD F("EX8874"), \ new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 1.27, 5000, A4), \ new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 1.27, 5000, A5) #endif #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) // EX 8874 based shield connected to a 3.3V system (like ESP32) and 12bit (4096) ADC // numbers are GPIO numbers. comments are UNO form factor shield pin numbers #define EX8874_SHIELD F("EX8874"),\ new MotorDriver(25/* 3*/, 19/*12*/, UNUSED_PIN, 13/*9*/, 35/*A2*/, 1.27, 5000, 36 /*A4*/), \ new MotorDriver(23/*11*/, 18/*13*/, UNUSED_PIN, 12/*8*/, 34/*A3*/, 1.27, 5000, 39 /*A5*/) // EX-CSB1 with integrated motor driver definition #define EXCSB1 F("EXCSB1"),\ new MotorDriver(25, 0, UNUSED_PIN, -14, 34, 2.23, 5000, 19), \ new MotorDriver(27, 15, UNUSED_PIN, -2, 35, 2.23, 5000, 23) // EX-CSB1 with EX-8874 stacked on top for 4 outputs #define EXCSB1_WITH_EX8874 F("EXCSB1_WITH_EX8874"),\ new MotorDriver(25, 0, UNUSED_PIN, -14, 34, 2.23, 5000, 19), \ new MotorDriver(27, 15, UNUSED_PIN, -2, 35, 2.23, 5000, 23), \ new MotorDriver(26, 5, UNUSED_PIN, 13, 36, 1.52, 5000, 18), \ new MotorDriver(16, 4, UNUSED_PIN, 12, 39, 1.52, 5000, 17) #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) // EX 8874 based shield connected to a 5V system (like Arduino) and 10bit (1024) ADC #define EX8874_SHIELD F("EX8874"), \ new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 5.08, 5000, A4), \ new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 5.08, 5000, A5) #endif // Pololu Motor Shield #define POLOLU_MOTOR_SHIELD F("POLOLU_MOTOR_SHIELD"), \ new MotorDriver( 9, 7, UNUSED_PIN, -4, A0, 18, 3000, 12), \ new MotorDriver(10, 8, UNUSED_PIN, UNUSED_PIN, A1, 18, 3000, 12) // // Actually, on the Pololu MC33926 shield the enable lines are tied together on pin 4 and the // pins 9 and 10 work as "inverted brake" but as we turn on and off the tracks individually // via the power pins we above use 9 and 10 as power pins and 4 as "inverted brake" which in this // version of the code always will be high. That means this config is not usable for generating // a railcom cuotout in the future. For that one must wire the second ^D2 to pin 2 and define // the motor driver like this: // new MotorDriver(4, 7, UNUSED_PIN, -9, A0, 18, 3000, 12) // 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), \ new MotorDriver(4, 8, 9, UNUSED_PIN, A1, 5.00, 1000, UNUSED_PIN) // Firebox Mk1S #define FIREBOX_MK1S F("FIREBOX_MK1A"), \ new MotorDriver(24, 21, 22, 25, 23, 9.766, 5500, UNUSED_PIN), \ new MotorDriver(30, 27, 28, 31, 29, 5.00, 1000, UNUSED_PIN) // FunduMoto Motor Shield #define FUNDUMOTO_SHIELD F("FUNDUMOTO_SHIELD"), \ 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, 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, 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 ================================================ FILE: Outputs.cpp ================================================ /* * © 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 * * 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 . */ /********************************************************************** DCC++ BASE STATION supports optional OUTPUT control of any unused Arduino Pins for custom purposes. Pins can be activited or de-activated. The default is to set ACTIVE pins HIGH and INACTIVE pins LOW. However, this default behavior can be inverted for any pin in which case ACTIVE=LOW and INACTIVE=HIGH. Definitions and state (ACTIVE/INACTIVE) for pins are retained in EEPROM and restored on power-up. The default is to set each defined pin to active or inactive according to its restored state. However, the default behavior can be modified so that any pin can be forced to be either active or inactive upon power-up regardless of its previous state before power-down. To have this sketch utilize one or more Arduino pins as custom outputs, first define/edit/delete output definitions using the following variation of the "Z" command: : creates a new output ID, with specified PIN and IFLAG values. if output ID already exists, it is updated with specificed PIN and IFLAG. note: output state will be immediately set to ACTIVE/INACTIVE and pin will be set to HIGH/LOW according to IFLAG value specifcied (see below). returns: if successful and if unsuccessful (e.g. out of memory) : deletes definition of output ID returns: if successful and if unsuccessful (e.g. ID does not exist) : lists all defined output pins returns: for each defined output pin or if no output pins defined where ID: the numeric ID (0-32767) of the output PIN: the arduino pin number to use for the output STATE: the state of the output (0=INACTIVE / 1=ACTIVE) IFLAG: defines the operational behavior of the output based on bits 0, 1, and 2 as follows: IFLAG, bit 0: 0 = forward operation (ACTIVE=HIGH / INACTIVE=LOW) 1 = inverted operation (ACTIVE=LOW / INACTIVE=HIGH) IFLAG, bit 1: 0 = state of pin restored on power-up to either ACTIVE or INACTIVE depending on state before power-down; state of pin set to INACTIVE when first created 1 = state of pin set on power-up, or when first created, to either ACTIVE of INACTIVE depending on IFLAG, bit 2 IFLAG, bit 2: 0 = state of pin set to INACTIVE uponm power-up or when first created 1 = state of pin set to ACTIVE uponm power-up or when first created Once all outputs have been properly defined, use the command to store their definitions to EEPROM. If you later make edits/additions/deletions to the output definitions, you must invoke the command if you want those new definitions updated in the EEPROM. You can also clear everything stored in the EEPROM by invoking the command. To change the state of outputs that have been defined use: : sets output ID to either ACTIVE or INACTIVE state returns: , or if turnout ID does not exist where ID: the numeric ID (0-32767) of the turnout to control STATE: the state of the output (0=INACTIVE / 1=ACTIVE) When controlled as such, the Arduino updates and stores the direction of each output in EEPROM so that it is retained even without power. A list of the current states of each output in the form is generated by this sketch whenever the status command is invoked. This provides an efficient way of initializing the state of any outputs being monitored or controlled by a separate interface or GUI program. **********************************************************************/ #include "Outputs.h" #ifndef DISABLE_EEPROM #include "EEStore.h" #endif #include "StringFormatter.h" #include "IODevice.h" /////////////////////////////////////////////////////////////////////////////// // Static function to print all output states to stream in the form "" void Output::printAll(Print *stream){ for (Output *tt = Output::firstOutput; tt != NULL; tt = tt->nextOutput) StringFormatter::send(stream, F("\n"), tt->data.id, tt->data.active); } // Output::printAll /////////////////////////////////////////////////////////////////////////////// // Object method to activate / deactivate the Output state. void Output::activate(uint16_t s){ s = (s>0); // Make 0 or 1 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 } /////////////////////////////////////////////////////////////////////////////// // Static function to locate Output object specified by ID 'n'. // Return NULL if not found. Output* Output::get(uint16_t n){ Output *tt; for(tt=firstOutput;tt!=NULL && tt->data.id!=n;tt=tt->nextOutput); return(tt); } /////////////////////////////////////////////////////////////////////////////// // Static function to delete Output object specified by ID 'n'. // Return false if not found. bool Output::remove(uint16_t n){ Output *tt,*pp=NULL; for(tt=firstOutput;tt!=NULL && tt->data.id!=n;pp=tt,tt=tt->nextOutput); if(tt==NULL) return false; if(tt==firstOutput) firstOutput=tt->nextOutput; else pp->nextOutput=tt->nextOutput; free(tt); return true; } /////////////////////////////////////////////////////////////////////////////// // Static function to load configuration and state of all Outputs from EEPROM #ifndef DISABLE_EEPROM void Output::load(){ struct OutputData data; Output *tt; for(uint16_t i=0;idata.nOutputs;i++){ EEPROM.get(EEStore::pointer(),data); // Create new object, set current state to default or to saved state from eeprom. tt=create(data.id, data.pin, data.flags); uint8_t state = data.setDefault ? data.defaultValue : data.active; tt->activate(state); if (tt) tt->num=EEStore::pointer() + offsetof(OutputData, oStatus); // Save pointer to flags within EEPROM EEStore::advance(sizeof(tt->data)); } } /////////////////////////////////////////////////////////////////////////////// // Static function to store configuration and state of all Outputs to EEPROM void Output::store(){ Output *tt; tt=firstOutput; EEStore::eeStore->data.nOutputs=0; while(tt!=NULL){ EEPROM.put(EEStore::pointer(),tt->data); tt->num=EEStore::pointer() + offsetof(OutputData, oStatus); // Save pointer to flags within EEPROM EEStore::advance(sizeof(tt->data)); tt=tt->nextOutput; EEStore::eeStore->data.nOutputs++; } } #endif /////////////////////////////////////////////////////////////////////////////// // Static function to create an Output object // The obscurely named parameter 'v' is 0 if called from the load() function // and 1 if called from the command processing. Output *Output::create(uint16_t id, VPIN pin, int iFlag, int v){ Output *tt; if (pin > VPIN_MAX) return NULL; if(firstOutput==NULL){ firstOutput=(Output *)calloc(1,sizeof(Output)); tt=firstOutput; } else if((tt=get(id))==NULL){ tt=firstOutput; while(tt->nextOutput!=NULL) tt=tt->nextOutput; tt->nextOutput=(Output *)calloc(1,sizeof(Output)); tt=tt->nextOutput; } if(tt==NULL) return tt; tt->num = 0; // make sure new object doesn't get written to EEPROM until store() command tt->data.id=id; tt->data.pin=pin; tt->data.flags=iFlag; if(v==1){ // sets status to 0 (INACTIVE) is bit 1 of iFlag=0, otherwise set to value of bit 2 of iFlag if (tt->data.setDefault) tt->data.active = tt->data.defaultValue; else tt->data.active = 0; } IODevice::write(tt->data.pin, tt->data.active ^ tt->data.invert); return(tt); } /////////////////////////////////////////////////////////////////////////////// Output *Output::firstOutput=NULL; ================================================ FILE: Outputs.h ================================================ /* * © 2021 Harald Barth * © 2021 Fred Decker * © 2020 Chris Harlow * 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 . */ #ifndef Outputs_h #define Outputs_h #include #include "IODevice.h" struct OutputData { union { uint8_t oStatus; // (Bit 0=Invert, Bit 1=Set state to default, Bit 2=default state, Bit 7=active) struct { unsigned int flags : 7; // Bit 0=Invert, Bit 1=Set state to default, Bit 2=default state unsigned int : 1; }; struct { unsigned int invert : 1; unsigned int setDefault : 1; unsigned int defaultValue : 1; unsigned int: 4; unsigned int active : 1; }; }; uint16_t id; VPIN pin; }; class Output{ public: void activate(uint16_t s); 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; Output *nextOutput; static void printAll(Print *); private: uint16_t num; // EEPROM address of oStatus in OutputData struct, or zero if not stored. }; // Output #endif ================================================ FILE: README.md ================================================ # What is DCC-EX? DCC-EX is a team of dedicated enthusiasts producing open source DCC & DC solutions for you to run your complete model railroad layout. Our easy to use, do-it-yourself, and free open source products run on off-the-shelf Arduino technology and are supported by numerous third party hardware and apps like JMRI, Engine Driver, wiThrottle, Rocrail and more. Currently, our products include the following: * [EX-CommandStation](https://github.com/DCC-EX/CommandStation-EX/releases) * [EX-WebThrottle](https://github.com/DCC-EX/exWebThrottle) * [EX-Installer](https://github.com/DCC-EX/EX-Installer) * [EX-MotoShield8874](https://dcc-ex.com/reference/hardware/motorboards/ex-motor-shield-8874.html#gsc.tab=0) * [EX-DCCInspector](https://github.com/DCC-EX/DCCInspector-EX) * [EX-Toolbox](https://github.com/DCC-EX/EX-Toolbox) * [EX-Turntable](https://github.com/DCC-EX/EX-Turntable) * [EX-IOExpander](https://github.com/DCC-EX/EX-IOExpander) * [EX-FastClock](https://github.com/DCC-EX/EX-FastClock) * [DCCEXProtocol](https://github.com/DCC-EX/DCCEXProtocol) Details of these projects can be found on [our web site](https://dcc-ex.com/). # What’s in this Repository? This repository, CommandStation-EX, contains a complete DCC-EX *EX-CommmandStation* sketch designed for compiling and uploading into an Arduino Uno, Mega, or Nano. To utilize this sketch, you can use the following: 1. (recommended for all levels of user) our [automated installer](https://github.com/DCC-EX/EX-Installer) 2. (intermediate) download the latest version from the [releases page](https://github.com/DCC-EX/CommandStation-EX/releases) 3. (advanced) use git clone on this repository Refer to [our web site](https://https://dcc-ex.com/ex-commandstation/get-started/index.html#/) for the hardware required for this project. **We seriously recommend using the EX-Installer**, however if you choose not to use the installer... * Open the file ``CommandStation-EX.ino`` in the Arduino IDE or Visual Studio Code (VSC). Please do not rename the folder containing the sketch code, nor add any files in that folder. The Arduino IDE relies on the structure and name of the folder to properly display and compile the code. * Rename or copy ``config.example.h`` to ``config.h``. * You must edit ``config.h`` according to the help texts in ``config.h``. # More information You can learn more at the [DCC-EX website](https://dcc-ex.com/) ================================================ FILE: Railcom.cpp ================================================ /* * © 2025 Chris Harlow * All rights reserved. * * 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 . */ /* This class acts as a 3 way coordinator between - the DCC waveform cutout generator, - the incoming railcom collector notifications - and the EXRAIL2 block enter/exit system */ #include "Railcom.h" #include "DCC.h" #include "DCCWaveform.h" #include "EXRAIL2.h" uint16_t Railcom::expectLoco=0; uint16_t Railcom::nextLoco=0; uint16_t Railcom::expectCV=0; unsigned long Railcom::expectWait=0; ACK_CALLBACK Railcom::expectCallback=0; enum ResponseType: byte { ENTER_BLOCK=0x00, // loco entering block, block id and loco id follow EXIT_BLOCK=0x80, // loco exiting block, block id and loco id follow CV_VALUE=0x40, // cv value read from a POM, cv value follow CV_VALUE_LIST=0xC0, // list of cv values read from a POM, cv id and 4 values follow }; // anticipate is used when waiting for a CV read from a railcom loco void Railcom::anticipate(uint16_t loco, uint16_t cv, ACK_CALLBACK callback) { expectLoco=loco; expectCV=cv; expectWait=millis(); // start of timeout expectCallback=callback; } // process is called to handle data buffer sent by collector void Railcom::process(int16_t firstVpin,byte * buffer, byte length) { // block,locohi,locolow // block|0x80,data pom read cv byte i=0; while (i POM_READ_TIMEOUT) { // still waiting expectCallback(-1); expectCallback=0; } } byte Railcom::cutoutCounter=0; void Railcom::incCutout() {cutoutCounter++;}; byte Railcom::getCutout() {return cutoutCounter;}; ================================================ FILE: Railcom.h ================================================ /* * © 202 5Chris Harlow * All rights reserved. * * 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 . */ #ifndef Railcom_h #define Railcom_h #include "Arduino.h" typedef void (*ACK_CALLBACK)(int16_t result); class Railcom { public: static void anticipate(uint16_t loco, uint16_t cv, ACK_CALLBACK callback); static void process(int16_t firstVpin,byte * buffer, byte length ); static void loop(); static void incCutout(); static byte getCutout(); private: static const unsigned long POM_READ_TIMEOUT=500; // as per spec static uint16_t expectCV,expectLoco, nextLoco; static unsigned long expectWait; static ACK_CALLBACK expectCallback; static byte cutoutCounter; // cyclic cutout static const byte MAX_WAIT_FOR_GLITCH=20; // number of dead or empty packets before assuming loco=0 }; #endif ================================================ FILE: Release - Architecture Doc/Prod-Release-Notes.md ================================================ The DCC-EX Team is pleased to release CommandStation-EX-v3.0.0 as a Production Release. This release is a major re-write of earlier versions. We've re-architected the code-base so that it can better handle new features going forward. **Known Bugs:** - **Consisting through JMRI** - currently does not work in this release. You may use the command to do this manually. - **Wi-Fi** - works, but can be challenging to use if you want to switch between AP mode and STA station mode. - **Pololu Motor Shield** - is supported with this release, but the user may have to play around with some timings to enable programming mode due to limitation in its current sensing circuitry **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 ```` 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 `````` command output** **Summary of the key new features added to CommandStation-EX V3.0.0:** - **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** - `````` command allows setting functions based on their number, not based on a code as in `````` - **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 `````` 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 managment** - slot variable in throttle/function commands are ignored and slot management is taken care of automatically. `````` command added to release locos from memory. **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) - Fred Decker - Holly Springs, North Carolina, USA (FlightRisk) - Dave Cutting - Logan, Utah, USA (Dave Cutting/ David Cutting) - M Steve Todd - - Engine Driver and JMRI Interface - Scott Catalanno - Pennsylvania - Gregor Baues - Île-de-France, France (grbba) **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 - (KCSmith) **WebThrotle-EX** - Fred Decker - Holly Springs, NC (FlightRisk/FrightRisk) - Mani Kumar - Bangalor, India (Mani /Mani Kumar) - Matt H - **Beta Testing / Release Management / Support** - Larry Dribin - Release Management - Keith Ledbetter - BradVan der Elst - Andrew Pye - Mike Bowers - Randy McKenzie - Roberto Bravin - Sim Brigden - Alan Lautenslager - Martin Bafver - Mário André Silva - Anthony Kochevar - Gajanatha Kobbekaduwe - Sumner Patterson - Paul - Virginia, USA ================================================ FILE: Release - Architecture Doc/Rough Release-Notes.md ================================================ # CommandStation-EX Release Notes ## v3.0.0 - **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 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** - `````` command allows setting functions based on their number, not based on a code as in `````` - **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 - **Diagnostic `````` 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** - **Support for more decoders** - Support for 20 (Uno) or 50 (Mega) mobile decoders, number automaticlaly recognized by JMRI. - **Automatic slot managment** - slot variable in throttle/function commands are ignored and slot management is taken care of automatically. `````` command added to release locos from memory. ================================================ FILE: Release_Notes/CommandRef.md ================================================ This file is being used to consolidate the command reference information. General points: - Commands below have a single character opcode and parameters. Even is actually read as - 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 Return status like also returns defined turnout list: 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 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 Set loco function 1=ON, 0-OFF For response see broadcast emergency stop all locos Control turnout id, 0=C=Closed, 1=T=Thrown response broadcast DCC accessory control 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. Valid commands respond with Direct pin manipulation (replaces Set pin HIGH Set pin LOW Set pin analog value Set pin analog with profile set pin analog with profile and value Sensors (Used by JMRI, not required by EXRAIL) define a sensor to be monitored. Responses and as sensor changes Decoder programming - main track POM write value to cv on loco POM write bit to cv on loco Decoder Programming - prog track Clear consist and write new cab id (includes long/short settings) Responds or for error Write value to cv Read cv value, much faster if prediction is correct. Read CV bit Read drive-away loco id. (May be a consist id) Advanced DCC control