From 88d57737c3934a10677069c86ea6b6ba3731393a Mon Sep 17 00:00:00 2001 From: Peter Akers Date: Sun, 10 May 2026 14:20:58 +1000 Subject: [PATCH 1/7] Update index.rst --- docs/ex-commandstation/advanced-setup/index.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/ex-commandstation/advanced-setup/index.rst b/docs/ex-commandstation/advanced-setup/index.rst index 847d45c7d9..095dc4b3ac 100644 --- a/docs/ex-commandstation/advanced-setup/index.rst +++ b/docs/ex-commandstation/advanced-setup/index.rst @@ -208,10 +208,7 @@ Manual Configuration of the EX-CommandStation DCC-EX Commands =============== -.. toctree:: - :maxdepth: 1 - - Native Commands Summary + :doc:`Native Commands Summary ` ---- From ac449464b9e53d295664b404114bd7f20bad9fe9 Mon Sep 17 00:00:00 2001 From: Peter Akers Date: Mon, 11 May 2026 10:04:17 +1000 Subject: [PATCH 2/7] clean up the navigation a bit --- docs/begin/what-to-know.rst | 58 +-- docs/include/include-l3_x.rst | 322 ++++++++++++ docs/include/include_x.rst | 310 ++++++++++++ docs/products.rst | 41 +- .../motorboards/ex-motor-shield-8874.rst | 472 +---------------- .../motorboards/ex-motor-shield-8874_2.rst | 11 + .../include__ex-motor-shield-8874.rst | 474 ++++++++++++++++++ .../wifi-boards/ex-wifi-shield-8266.rst | 53 +- .../wifi-boards/ex-wifi-shield-8266_2.rst | 11 + .../include__ex-wifi-shield-8266.rst | 52 ++ 10 files changed, 1233 insertions(+), 571 deletions(-) create mode 100644 docs/include/include-l3_x.rst create mode 100644 docs/include/include_x.rst create mode 100644 docs/reference/hardware/motorboards/ex-motor-shield-8874_2.rst create mode 100644 docs/reference/hardware/motorboards/include__ex-motor-shield-8874.rst create mode 100644 docs/reference/hardware/wifi-boards/ex-wifi-shield-8266_2.rst create mode 100644 docs/reference/hardware/wifi-boards/include__ex-wifi-shield-8266.rst diff --git a/docs/begin/what-to-know.rst b/docs/begin/what-to-know.rst index 76f39b9be9..0d565c38a4 100644 --- a/docs/begin/what-to-know.rst +++ b/docs/begin/what-to-know.rst @@ -39,6 +39,35 @@ What is DCC-EX? Our Free and Open Source Products ================================= +Our Open Source Hardware +------------------------ + +Our *open source* hardware products currently include: + +.. list-table:: + :widths: 33 33 33 + :header-rows: 0 + :class: table-grid-homepage + + * - |EX-CSB1-LOGO-SMALL| + - |EX-MS-LOGO-SMALL| + - |EX-WS-LOGO-SMALL| + * - Our ready-to-run |DCC| & |DC| command station / booster for controlling your model railroad. Preloaded with our |EX-CS| software. + - Our dual 5A output |motor shield| for DIY command stations and adding additional power districts to the |EX-CSB1-SHORT| + - Our WiFi add-on board for DIY command stations + +.. list-table:: + :widths: 50 50 + :header-rows: 0 + :class: table-list-homepage + + * - |EX-CSB1-LOGO-SMALL| + - Our ready-to-run |DCC| & |DC| command station / booster for controlling your model railroad. Preloaded with our |EX-CS| software. + * - |EX-MS-LOGO-SMALL| + - Our dual 5A output |motor shield| for DIY command stations and adding additional power districts to the |EX-CSB1-SHORT| + * - |EX-WS-LOGO-SMALL| + - Our WiFi add-on board for DIY command stations + Our Free, Open Source Software ------------------------------ @@ -92,35 +121,6 @@ Our *free*, *open source* software products currently include: * - |EX-TB-LOGO-SMALL| - An Android app to help configure your EX-CommandStation -Our Open Source Hardware ------------------------- - -Our *open source* hardware products currently include: - -.. list-table:: - :widths: 33 33 33 - :header-rows: 0 - :class: table-grid-homepage - - * - |EX-CSB1-LOGO-SMALL| - - |EX-MS-LOGO-SMALL| - - |EX-WS-LOGO-SMALL| - * - Our ready-to-run |DCC| & |DC| command station / booster for controlling your model railroad - - Our dual 5A output |motor shield| for DIY command stations and adding additional power districts to the |EX-CSB1-SHORT| - - Our WiFi add-on board for DIY command stations - -.. list-table:: - :widths: 50 50 - :header-rows: 0 - :class: table-list-homepage - - * - |EX-CSB1-LOGO-SMALL| - - Our ready-to-run |DCC| & |DC| command station / booster for controlling your model railroad - * - |EX-MS-LOGO-SMALL| - - Our dual 5A output |motor shield| for DIY command stations and adding additional power districts to the |EX-CSB1-SHORT| - * - |EX-WS-LOGO-SMALL| - - Our WiFi add-on board for DIY command stations - ---- What is EX-CommandStation? diff --git a/docs/include/include-l3_x.rst b/docs/include/include-l3_x.rst new file mode 100644 index 0000000000..3be6c9d48e --- /dev/null +++ b/docs/include/include-l3_x.rst @@ -0,0 +1,322 @@ +.. ................................................ +.. +.. |DCC-EXx| raw:: html + + DCC-EX +.. +.. |EX-CSx| raw:: html + + EX‑CommandStation +.. +.. |EX-WSx| raw:: html + + EX‑WiFiShield 8874 +.. +.. |EX-WTx| raw:: html + + EX‑WebThrottle +.. +.. |EX-Rx| raw:: html + + EXRAIL +.. +.. |EX-Ix| raw:: html + + EX‑Installer +.. +.. |EX-TTx| raw:: html + + EX‑Turntable +.. +.. |EX-FCx| raw:: html + + EX‑FastClock +.. +.. |EX-DCCIx| raw:: html + + EX‑DCCInspector +.. +.. |EX-IOx| raw:: html + + EX‑IOExpander +.. +.. |EX-TBx| raw:: html + + EX‑Toolbox +.. +.. |EX-MSx| raw:: html + + EX‑MotorShield8874 +.. +.. |EX-CSB1x| raw:: html + + EX‑CommandStation / Booster One Express +.. +.. |EX-CSB1-SHORTx| raw:: html + + EX‑CSB1 +.. +.. |BSCx| raw:: html + + BaseStationClassic (DCC++) +.. +.. |TMx| raw:: html + + TrackManager +.. +.. |DCC-EXPx| raw:: html + + DCCEXProtocol +.. +.. ................................................ +.. +.. |EX-CSB1-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-csb1.png + :alt: EX-CSB1 Logo + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-commandstation/rtr-index.html +.. +.. |EX-CS-DIY-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-cs-diy.png + :alt: EX-CS-DIY Logo + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-commandstation/diy/index.html +.. +.. |EX-CS-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-commandstation.png + :alt: EX-CommandStation + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-commandstation/index.html +.. +.. |EX-I-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-installer.png + :alt: EX-Installer + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-installer/index.html +.. +.. |EX-WT-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-webthrottle.png + :alt: EX-WebThrottle + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-webthrottle/index.html +.. +.. |EX-R-LOGO-SMALLx| image:: /_static/images/logos/product-logo-exrail.png + :alt: EXRAIL + :scale: 30% + :class: image-min-width-144 + :target: ../../../exrail/index.html +.. +.. |EX-TT-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-turntable.png + :alt: EX-Turntable + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-turntable/index.html +.. +.. |EX-FC-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-fastclock.png + :alt: EX-FastClock + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-fastclock/index.html +.. +.. |EX-DCCI-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-dccinspector.png + :alt: EX-DCCInspector + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-dccinspector/index.html +.. +.. |EX-IO-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-ioexpander.png + :alt: EX-IOExpander + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-ioexpander/index.html +.. +.. |EX-BSC-LOGO-SMALLx| image:: /_static/images/logos/product-logo-basestationclassic.png + :alt: baseStationClassic + :scale: 30% + :class: image-min-width-144 + :target: ../../../download/ex-commandstation.html#getting-basestation-classic +.. +.. |EX-TB-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-toolbox.png + :alt: EX-Toolbox + :scale: 30% + :class: image-min-width-144 + :target: ../../../ex-toolbox/index.html +.. +.. |EX-MS-LOGO-SMALLx| image:: /_static/images/logos/product-logo-ex-motorshield8874.png + :alt: EX-MotorShield8874 + :scale: 30% + :class: image-min-width-144 + :target: ../../../reference/hardware/motorboards/ex-motor-shield-8874.html +.. +.. |TRACKMANAGER-LOGO-SMALLx| image:: /_static/images/logos/product-logo-trackmanager.png + :alt: DCC-EX TrackManager + :scale: 30% + :class: image-min-width-144 + :target: ../../../trackmanager/index.html +.. +.. |NEW-IN-V5-LOGO-SMALLx| image:: /_static/images/logos/new_in_version_5.png + :alt: New in Version 5 + :scale: 30% + :class: image-min-width-144 + :target: ../../../news/posts/20230807.html +.. +.. |NEW-IN-V5-4-LOGO-SMALLx| image:: /_static/images/logos/new_in_version_5_4.png + :alt: New in Version 5.4 + :scale: 30% + :class: image-min-width-144 show_light + :target: ../../../news/posts/20230807.html +.. +.. |NEW-IN-V5-4-LOGO-SMALL-DARKx| image:: /_static/images/logos/new_in_version_5_4_dark.png + :alt: New In Version 5.4 + :scale: 30% + :class: image-min-width-144 show_dark + :target: ../../../news/posts/20230807.html +.. +.. ................................................ +.. +.. |donate-buttonx| image:: /_static/images/icons/donate_button_blue.png + :alt: Donate Button + :class: float-right + :scale: 25% + :target: ../../../about/contributing/donate.html +.. +.. |conductorx| image:: /_static/images/level_icons/conductor-level.png + :alt: Conductor Hat + :scale: 40% + :target: ../../../begin/levels.html#conductor +.. +.. |tinkererx| image:: /_static/images/level_icons/tinkerer-level.png + :alt: Propeller Beanie + :scale: 40% + :target: ../../../begin/levels.html#tinkerer +.. +.. |engineerx| image:: /_static/images/level_icons/engineer-level.png + :alt: Engineer Hat + :scale: 40% + :target: ../../../begin/levels.html#engineer +.. +.. |conductor-no-textx| image:: /_static/images/level_icons/conductor.png + :alt: Conductor Hat + :scale: 40% + :class: image-min-width-144 + :target: ../../../begin/levels.html#conductor +.. +.. |tinkerer-no-textx| image:: /_static/images/level_icons/tinkerer.png + :alt: Propeller Beanie + :scale: 40% + :class: image-min-width-144 + :target: ../../../begin/levels.html#tinkerer +.. +.. |engineer-no-textx| image:: /_static/images/level_icons/engineer.png + :alt: Engineer Hat + :scale: 40% + :class: image-min-width-144 + :target: ../../../begin/levels.html#engineer +.. +.. |conductor-textx| raw:: html + + Conductor +.. +.. |tinkerer-textx| raw:: html + + Tinkerer +.. +.. |engineer-textx| raw:: html + + Engineer +.. +.. ............................................... +.. +.. |suitablex| image:: /_static/images/level_icons/level-suitable-for.png + :alt: Suitable For Level: + :scale: 40% + :target: ../../../begin/levels.html#levels-of-difficulty-or-technical-complexity +.. +.. ................................................ +.. +.. |support-buttonx| raw:: html + + +.. +.. |support-button-largex| raw:: html + + +.. +.. ................................................ +.. +.. |EXTERNAL-LINKx| raw:: html + + +.. +.. ................................................ +.. +.. |githublink-ex-turntable-button-smallx| raw:: html + + +.. +.. |githublink-ex-dccinspector-button-smallx| raw:: html + + +.. +.. |githublink-ex-webthrottle-button-smallx| raw:: html + + +.. +.. |githublink-ex-installer-button-smallx| raw:: html + + +.. +.. |githublink-ex-commandstation-button-smallx| raw:: html + + +.. +.. |githublink-ex-csb1-button-smallx| raw:: html + + +.. +.. |githublink-ex-ioexpander-button-smallx| raw:: html + + +.. +.. |githublink-ex-fastclock-button-smallx| raw:: html + + +.. +.. ............................................... +.. +.. |githublink-ex-turntablex| raw:: html + + +.. +.. |githublink-ex-turntable-buttonx| raw:: html + + +.. +.. |githublink-ex-dccinspector-buttonx| raw:: html + + +.. +.. |githublink-ex-webthrottle-buttonx| raw:: html + + +.. +.. |githublink-ex-installer-buttonx| raw:: html + + +.. +.. |githublink-ex-commandstation-buttonx| raw:: html + + +.. +.. |githublink-ex-csb1-buttonx| raw:: html + + +.. +.. |githublink-ex-ioexpander-buttonx| raw:: html + + +.. +.. |githublink-ex-fastclock-buttonx| raw:: html + + +.. \ No newline at end of file diff --git a/docs/include/include_x.rst b/docs/include/include_x.rst new file mode 100644 index 0000000000..ad9012a7d8 --- /dev/null +++ b/docs/include/include_x.rst @@ -0,0 +1,310 @@ +.. meta:: + :keywords: DCC-EX DCC DCC++ EX DCC++EX +.. +.. +.. |brx| raw:: html + +
+.. +.. role:: dcc-ex-red +.. role:: dcc-ex-red-bold +.. role:: dcc-ex-red-bold-italic +.. role:: dcc-ex-code +.. +.. role:: dcc-ex-text-size-80pct +.. role:: dcc-ex-text-size-60pct +.. role:: dcc-ex-text-size-200pct +.. +.. |small-startx| raw:: html + + +.. +.. |small-endx| raw:: html + + +.. +.. |_x| unicode:: 0xA0 + :trim: +.. +.. |force-breakx| raw:: html + +
+.. +.. |image-notex| raw:: html + + Note that you can click on any of the images to make them larger. +.. +.. |NOT-IN-PROD-VERSIONx| raw:: html + + This feature is not available in the current 'Production' version
It is available in the 'development' (DEVEL) releases. +.. +.. |NEW-IN-V5x| raw:: html + + New in version 5 +.. +.. |NEW-IN-V5-4x| raw:: html + + New in version 5.4 +.. +.. |DEPRECATEDx| raw:: html + + Deprecated +.. +.. |I2Cx| replace:: I\ :sup:`2`\ C +.. +.. ................................................ +.. +.. |EX-PLACEHOLDERx| image:: /_static/images/logos/placeholder.png + :alt: Dummy Placeholder + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-CS-LOGOx| image:: /_static/images/logos/product-logo-ex-commandstation.png + :alt: EX-CommandStation + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-I-LOGOx| image:: /_static/images/logos/product-logo-ex-installer.png + :alt: EX-Installer + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-WT-LOGOx| image:: /_static/images/logos/product-logo-ex-webthrottle.png + :alt: EX-WebThrottle + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-R-LOGOx| image:: /_static/images/logos/product-logo-exrail.png + :alt: EXRAIL + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-TT-LOGOx| image:: /_static/images/logos/product-logo-ex-turntable.png + :alt: EX-Turntable + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-FC-LOGOx| image:: /_static/images/logos/product-logo-ex-fastclock.png + :alt: EX-FastClock + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-DCCI-LOGOx| image:: /_static/images/logos/product-logo-ex-dccinspector.png + :alt: EX-DCCInspector + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-BSC-LOGOx| image:: /_static/images/logos/product-logo-basestationclassic.png + :alt: BaseStationClassic + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-TB-LOGOx| image:: /_static/images/logos/product-logo-ex-toolbox.png + :alt: EX-Toolbox + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-MS-LOGOx| image:: /_static/images/logos/product-logo-ex-motorshield8874.png + :alt: EX-MotorShield8874 + :scale: 40% + :class: image-product-logo-float-right +.. +.. ................................................ +.. +.. |EX-BP-LOGOx| image:: /_static/images/logos/product-logo-bigpicture.png + :alt: The Big Picture + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-AN-LOGOx| image:: /_static/images/logos/product-logo-announcements.png + :alt: Announcements + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-DL-LOGOx| image:: /_static/images/logos/product-logo-download.png + :alt: Downloads + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-REF-LOGOx| image:: /_static/images/logos/product-logo-reference.png + :alt: Reference + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-THROTTLES-LOGOx| image:: /_static/images/logos/product-logo-throttles.png + :alt: Throttles + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-CONTRIBUTING-LOGOx| image:: /_static/images/logos/product-logo-contributing.png + :alt: Contributing + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-SUPPORT-LOGOx| image:: /_static/images/logos/product-logo-ex-support.png + :alt: EX-Support + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-IO-LOGOx| image:: /_static/images/logos/product-logo-ex-ioexpander.png + :alt: EX-FastClock + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-NEWS-LOGOx| image:: /_static/images/logos/product-logo-news.png + :alt: DCC-EX News + :scale: 40% + :class: image-product-logo-float-right +.. +.. |EX-SUPPLIERS-LOGOx| image:: /_static/images/logos/product-logo-suppliers.png + :alt: DCC-EX Suppliers + :scale: 40% + :class: image-product-logo-float-right +.. +.. |TRACKMANAGER-LOGOx| image:: /_static/images/logos/product-logo-trackmanager.png + :alt: DCC-EX Track Manager + :scale: 40% + :class: image-product-logo-float-right +.. +.. |NATIVE-PROTOCOL_LIBRARY-LOGOx| image:: /_static/images/logos/product-logo-native-protocol-library.png + :alt: DCC-EX Native Protocol Library + :scale: 40% + :class: image-product-logo-float-right +.. +.. ................................................ +.. +.. |EX-BP-LOGO-SMALLx| image:: /_static/images/logos/product-logo-bigpicture.png + :alt: The Big Picture + :scale: 30% + :class: image-float-right +.. +.. ............................................... +.. +.. |EX-R-FULLx| raw:: html + + EXtended + Railroad + Automation + Instruction + Language +.. +.. |Motor Driverx| replace:: + + :doc:`Motor Driver ` +.. +.. |JMRIx| replace:: + + :doc:`JMRI ` +.. +.. |Engine Driverx| replace:: + + :doc:`Engine Driver ` +.. +.. |EDx| replace:: + + :doc:`Engine Driver ` +.. +.. |wiThrottlex| replace:: + + :doc:`wiThrottle ` +.. +.. |wiThrottle Litex| replace:: + + :doc:`wiThrottle Lite ` +.. +.. |ThrottleCardx| replace:: + + :doc:`ThrottleCard ` +.. +.. |wiThrottle Protocolx| replace:: + + :doc:`wiThrottle Protocol ` +.. +.. |wiThrottle Serverx| replace:: + + :doc:`wiThrottle Server ` +.. +.. |Access Pointx| replace:: + + :doc:`Access Point (AP) ` +.. +.. |Access Point Modex| replace:: + + :doc:`Access Point (AP) Mode ` +.. +.. |Station Modex| replace:: + + :doc:`Station (STA) Mode ` +.. +.. |Arduino IDEx| replace:: + + :doc:`Arduino IDE ` +.. +.. |VSCx| replace:: + + :doc:`Visual Studio Code (VSC) ` +.. +.. |DCC-EX Native Commandsx| replace:: + + :doc:`DCC-EX Native Commands ` +.. +.. |DCC-EX Native Protocolx| replace:: + + :doc:`DCC-EX Native Protocol ` +.. +.. |DC PWMx| replace:: + + :doc:`DC PWM ` +.. +.. |DCx| replace:: + + :doc:`DC ` +.. +.. |DCCx| replace:: + + :doc:`DCC ` +.. +.. |Serial Monitorx| replace:: + + :doc:`Serial Monitor ` +.. +.. |IDE Serial Monitorx| replace:: + + :ref:`Arduino IDE Serial Monitor ` +.. +.. |Device Monitorx| replace:: + + :ref:`EX-Installer Device Monitor ` +.. +.. |STANDARD MOTOR DRIVERx| replace:: + + :abbr:`Standard Motor Driver (Either the 'Arduino Motor Shield R38' or 'Deek-Robot Motor Shield'.)` +.. +.. |MOTOR DRIVERx| replace:: + + :abbr:`Motor Driver (also referred to as a 'Motor Controller', 'Motor Shield' or 'Motor Board')` +.. +.. |MOTOR SHIELDx| replace:: + + :abbr:`Motor Shield (also referred to as a 'Motor Controller', 'Motor Driver' or Motor Board')` +.. +.. |DIYx| replace:: + + :abbr:`DIY (Do-it-yourself)` +.. +.. |RTRx| replace:: + + :abbr:`RTR (Ready-to-run / plug-and-play)` +.. +.. |Booster Modex| replace:: + + :doc:`Booster Mode ` +.. +.. |hr-dashedx| raw:: html + +
+.. +.. |hr-heavyx| raw:: html + +
+.. \ No newline at end of file diff --git a/docs/products.rst b/docs/products.rst index 1d2187b3b5..90a7a7c658 100644 --- a/docs/products.rst +++ b/docs/products.rst @@ -10,6 +10,25 @@ Our Products ********************************* +Our Open Source Hardware +========================= + +Our *open source* hardware products currently include: + +.. list-table:: + :widths: 50 50 + :header-rows: 0 + :class: table-wrap-text + + * - |EX-CSB1-LOGO-SMALL| + - Our ready-to-run |DCC| & |DC| command station / booster |BR| for controlling your model railroad. Preloaded with our |EX-CS| software. + * - |EX-MS-LOGO-SMALL| + - Our dual 5A output |motor shield| for DIY command stations |BR| and adding additional power districts to the |EX-CSB1-SHORT| + * - |EX-WS-LOGO-SMALL| + - Our WiFi add-on board for DIY command stations + +See the :doc:`Purchasing ` page for information on how to buy our hardware products. + Our Free, Open Source Software ============================== @@ -18,6 +37,7 @@ Our *free*, *open source* software products currently include: .. list-table:: :widths: 50 50 :header-rows: 0 + :class: table-wrap-text * - |EX-CS-LOGO-SMALL| - Our |DCC| & |DC| command station software for controlling your model railroad. |BR| :dcc-ex-text-size-60pct:`For a ready-to-run version of the EX-CommandStation see our` |EX-CSB1-SHORT| @@ -38,23 +58,6 @@ Our *free*, *open source* software products currently include: * - |EX-TB-LOGO-SMALL| - An Android app to help configure your EX-CommandStation -Our Open Source Hardware -========================= - -Our *open source* hardware products currently include: - - -.. list-table:: - :widths: 50 50 - :header-rows: 0 - - * - |EX-CSB1-LOGO-SMALL| - - Our ready-to-run |DCC| & |DC| command station / booster |BR| for controlling your model railroad - * - |EX-MS-LOGO-SMALL| - - Our dual 5A output |motor shield| for DIY command stations |BR| and adding additional power districts to the |EX-CSB1-SHORT| - * - |EX-WS-LOGO-SMALL| - - Our WiFi add-on board for DIY command stations - |HR-HEAVY| Next Steps @@ -71,8 +74,8 @@ For how to buy a *ready-to-run (RTR)* or build your own *do-it-yourself (DIY)* | ex-commandstation/index EX-CSB1 Express - EX-MotorShield8874 - EX-WiFiShield-8266 + EX-MotorShield8874 + EX-WiFiShield-8266 ex-installer/index ex-webthrottle/index ex-toolbox/index diff --git a/docs/reference/hardware/motorboards/ex-motor-shield-8874.rst b/docs/reference/hardware/motorboards/ex-motor-shield-8874.rst index 4c8d2fe05a..19b6ea0007 100644 --- a/docs/reference/hardware/motorboards/ex-motor-shield-8874.rst +++ b/docs/reference/hardware/motorboards/ex-motor-shield-8874.rst @@ -10,474 +10,4 @@ DCC-EX EX-MotorShield8874 RevA ****************************** -|SUITABLE| |conductor| |tinkerer| |engineer| |support-button| - -.. sidebar:: - :class: sidebar-on-this-page - - .. contents:: On this page - :depth: 3 - :local: - -.. note:: - - This board is compatible with |TM| DC mode. - -Designed in conjunction with the |DCC-EX| development team, the |EX-MS| is extremely simple to use with all current and future generations of |EX-CS| hardware. - -It also safely powers the Command Station motherboard via the same single barrel jack DC input voltage that powers the track. It is rated at a very generous peak 5A of load per channel using Texas Instruments DRV8874 MOSFET technology. This board is the new standard by which we compare other boards. - -.. figure:: /_static/images/motorboards/ex_motorshield8874.png - :alt: DCC-EX EX-MotorShield8874 RevA Semify - :scale: 10% - - DCC-EX EX-MotorShield8874 RevA Semify - -.. figure:: /_static/images/motorboards/ex_motorshield8874_purple_side.png - :alt: DCC-EX EX-MotorShield8874 RevA Millennium Engineering - :scale: 10% - - DCC-EX EX-MotorShield8874 RevA Millennium Engineering - ----- - -What Is It? -=========== - -The EX-Motorshield8874 is pin compatible with the original Arduino Motor Shield Rev3 but provides significantly improved electrical performance for driving higher loads, and improved usability. - -* Rated for 5 Amps of continuous output current -* No need to cut traces or bend out pins for stacking on the EX-CommandStation -* 2 outputs (Main and Programming Track or 2 Mains) -* Single power supply input powers the shield, the Arduino, and the track (motor output)! -* 5V and 3.3V compatible -* Virtually no voltage drop, even at high currents -* I2C header and STEMMA Qwiic connector for accessories (displays, port expanders, servo boards, etc.) -* Reverse polarity protection -* Fault detection in addition to overcurrent reporting for extra safety -* Alternative power in and out solder pads for different connector types -* Stackable (Support multiple Power Districts) -* Optional OLED header to connect a display directly to the shield - -The |EX-MS| is based on two DRV8874 H-bridge motor drivers with integrated current sensing from Texas Instruments (TI). It is used to drive inductive loads like relays, solenoids, DC and stepping motors, as well as provide the DCC signal and power to the model railroad tracks. - -Powering of Arduino boards is possible due to the on board DC/DC buck converter, supporting a wide input supply range from 9 to 25V. The reverse polarity protection prevents damage to the circuit and its components in case the power supply is accidentally connected backwards. - -The board's 5V and 3V3 friendly design makes it suitable for a broad range of Arduino compatible platforms, with an override that compensates for designs with incomplete support (such as an incorrect IORef voltage). - -This Shield features a status LED for supply, which provides a visual indication of the power supply status in addition to LEDs to show each side of the A and B power outputs. - ----- - -Why did we make it? -==================== - -|EX-MS| is specifically designed for use with DCC-EX Command Station for controlling model railroads, but can also be used as generally better replacement for Arduino Motor Shield R3 in any device that needs to control a motor. We needed higher current capacity to power more motors/trains and have little to no voltage drop due to advanced MOSFET driver technology. - - -.. note:: - - The |EX-MS| was created through the gracious support and design facilities of Semify, who, along with DCC-EX, license it to manufacturers. The hardware design has been made open source for individual users and the schematics are available on the `DCC-EX GitHub `_ repository. - - ----- - -How can I get one? -================== - -Units may be purchased from the following sources: - -.. include:: /purchasing/include__dealers.rst - -|HR-DASHED| - -There are different options for the board such as fully assembled or in kit form where connectors and headers need to be soldered onto the board. Prices vary from around $34.95 to $39.90 in the US, to approximately £29.99 in the UK, €37 in Europe, and in Australia starting from $AU55.00. Prices typically do not include tax and shipping. - -For quantities of 10 or less per annum, you may utilise a PCB manufacturing and assembly service such as JLCPCB without licensing fees. A donation to DCC-EX would be appreciated, so click the DONATE button! The production files are available on the `DCC-EX GitHub `_. - -Entrepreneurs wanting to use the design to offer commercial quantities to their local communities should contact Semify (service @ semify-eda.com) to arrange a bulk purchase or DCC-EX (support @ dcc-ex.com) for a license to manufacture. Licensing includes donating a royalty to DCC-EX per board sold. - ------ - -Assembly with EX-MotorShield8874 -================================ - -Assembly with the |EX-MS| is extremely simple, just plug the motor shield into your choice of Command Station motherboard. Unlike other motor shields, the EX-MotorShield8874 needs no jumpering, trace cutting, or pin bending! Just plug it in. - -Shown here are examples of the shield plugged into Mega+WiFi, Nucleo-F411RE: - -.. figure:: /_static/images/motorboards/ex_motorshield8874_mega.png - :alt: DCC-EX EX-MotorShield8874 RevA on Mega+WiFi - :scale: 15% - - DCC-EX EX-MotorShield8874 RevA on Mega+WiFi - -.. figure:: /_static/images/motorboards/ex_motorshield8874_nucleo_f411.png - :alt: DCC-EX EX-MotorShield8874 RevA on Nucleo-F411RE - :scale: 15% - - DCC-EX EX-MotorShield8874 RevA on Nucleo-F411RE - -1. Connect DC Power to Motor Driver ------------------------------------- - -The |EX-MS| accepts a standard 2.1mm inside diameter DC barrel jack for DC power, with centre pin positive, and polarity protected for your safety. Acceptable voltages for correct DCC operation include 10-24VDC, but the shield can cope with 9-25VDC. - -.. figure:: /_static/images/motorboards/ex_motorshield8874_purple_megawifi.png - :alt: DCC-EX EX-MotorShield8874 on Mega+WiFi with power and track connectors - :scale: 10% - - DCC-EX EX-MotorShield8874 on Mega+WiFi with power and track connectors - -.. note:: - **DO NOT** connect power to BOTH the EX-MotorShield8874 barrel jack and the underlying Arduino motherboard via its DC barrel jack as you may damage your Arduino and/or EX-MotorShield8874!! - -The EX-MotorShield8874's DC barrel jack is the only power source required to power both the tracks and the |EX-CS| into which it is plugged. It supplies carefully regulated 7.2V DC power to the underlying Arduino R3 compatible motherboard via the VIN pin. This voltage is safely regulated down from the track power input to ensure Command Station motherboards will stay cool and work well. There is no need to power the Command Station via its barrel jack, or USB power. It is safe, however, to connect the USB cable as it will not create a conflict. - -.. warning:: - :class: warning-float-right - - These are *common*, but not universal, upper limits of what decoders will accept. You should check the manual of your decoders to confirm what they accept, and adjust the voltage down accordingly. - - :dcc-ex-red-bold-italic:`Applying a voltage above what a decoder was designed for may permanently damage it.` - -Because the EX-MotorShield8874 does not drop voltage like the standard L298 based motor shields we suggest: - -* **10v-12vDC** for Z scale -* **10v-14vDC** for N scale -* **14v-16vDC** for HO/OO scale -* **18v-19vDC** for O scale -* **20v-24vDC** for G scale - -Note that good quality, fully-enclosed and double-insulated switch mode power supplies are best, and we suggest laptop power bricks as ideal in this role as they typically output 3-20A easily and safely. - -.. note:: - Please note that as the EX-MotorShield8874 can supply up to 5A of track power per channel, a power supply of more than 10A peak capacity is required to run both channels at full peak current and have power left for the Command Station. - -.. note:: - If you are just just testing your Arduino (not trying to power the track with the motor shield) some users have found that their PC USB ports have not been providing reliable power to the Arduino and have needed to plug the power supply into EX-MotorShield8874. - -1. Turn on Power to the Motor Driver ------------------------------------- - -Once satisfied the |EX-MS| is seated properly on the Command Station motherboard, you can apply power to the |EX-CS|. You ought to see a green LED light up indicating power is being supplied to the motherboard. - -.. figure:: /_static/images/motorboards/ex_motorshield8874_purple_megawifi_LED_on.png - :alt: DCC-EX EX-MotorShield8874 RevA on Mega+WiFi with power LED on - :scale: 10% - - DCC-EX EX-MotorShield8874 RevA on Mega+WiFi with power LED on - -3. Connect Track to Motor Driver ------------------------------------- - -Track power for A (MAIN) and B (PROG) tracks can be connected now using the green track connectors. These unplug conveniently to allow easy swapping in and out of the |EX-CS|. Make sure to tighten the screws onto the wire in the connectors before applying power. - -.. figure:: /_static/images/motorboards/ex_motorshield8874_purple_connector_closeup.png - :alt: DCC-EX EX-MotorShield8874 RevA connectors - :scale: 30% - - DCC-EX EX-MotorShield8874 RevA connectors - -There are two sets of output connectors on the motor shield, ``A`` and ``B``. A is the Main or Operations (also called 'Ops') track while ``B`` is the Programming or Service track. Connect twisted pair wire of the proper gauge to each track. - -Notice that A (MAIN) is on the left as you look at the connectors, and B (PROG) is on the right, next to the DC barrel jack. - -Polarity (which wire is connected to which side of the track) is not not important here if you are using separate, completely isolated piece of track for PROG. *However* if you will be using a siding track that connects to your main track, make sure that the *connections for both tracks match*. - -In other words, if you view one side of your main track as having a 'left' side and a 'right' side, and connect positive output A to the left side, connect the positive from the B side to the left side of the programming track. In electrical terms, we want both tracks to be "in phase" with each other. Here is the diagram from above repeated again for reference. - -|HR-HEAVY| - -Next steps -========== - -See the :doc:`/ex-commandstation/diy/wifi-setup` page to learn how to connect the WiFi shield to your |EX-CS|, or *alternatively* connect a controller like |JMRI| or our |EX-WT| by using the serial cable to connect between your computer and the |EX-CS| as outlined in the :ref:`ex-installer/installing:getting ready` section of the |EX-I| page. Note that when configuring the EX-CommandStation you will want to select `EX8874_SHIELD` as the motor board during configuration. - ----- - -Additional Information -====================== - -Stacking EX-MotorShield8874s ----------------------------- - -This is **definitely** advanced Tinkerer/Engineer level work. Do **not** attempt it without some confidence you know what you are doing electronically. Future revisions of the EX-MotorShield8874 will look at alternative ways to expand the number of DCC districts. - -This article covers both stacking an Arduino Motor Shield R3 and an EX-MotorShield8874, and stacking two EX-MotorShield8874s. |BR| -> Note that L298 clone motor shields can be used on 5V Mega, etc., but require modification for use with 3.3V ESP32-WROOM and Nucleo-F4. :ref:`Link to further detail. ` - -Stacking an Arduino Motor Shield R3 and EX-MotorShield8874 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This stack is perhaps simplest and an easy enough upgrade for those who already have an Arduino Motor Shield R3 or clone. - -We are going to leave the Arduino Motor Shield R3 in the same configuration as recommended on the :doc:`/ex-commandstation/diy/assembly` page and as such it is worth doing this first and testing all is well before proceeding if this is a new install. - -The best solution is to stack the EX-MotorShield8874 on top of the Arduino Motor Shield R3 (is it, really??) for which we will need to re-route some of its IO pins to allow it to function. - -On the EX-MotorShield8874 you need to alter the Pin Assignment pads (NB: the following is fine for Mega and Nucleo/STM32 motherboards, but is **not** ideal for ESPDuino32 motherboards): - -.. figure:: /_static/images/motorboards/ex_motorshield8874_pin_assignment_pads.jpg - :alt: DCC-EX EX-MotorShield8874 RevA Pin Assignment Pads - :scale: 30% - -* Cut the PWM (EN) jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads -* Cut the BRAKE jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads -* Cut the DIR jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads -* Cut the SENSE jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads - -The above will re-allocate most of the pins used by the top board to the `ALT or alternate set of pins `_ |EXTERNAL-LINK| but note it leaves the FAULT pins routed to the default positions of A4/A5 as there is no conflict with the Arduino Motor Shield R3. - -Add **one** of the following motor driver definitions to your config.h file (if uncertain, read :doc:`this description ` first): - -Find this section in the file: - -.. code-block:: cpp - - // DEFINE MOTOR_SHIELD_TYPE BELOW ACCORDING TO THE FOLLOWING TABLE: - // - // STANDARD_MOTOR_SHIELD : Arduino Motor shield Rev3 based on the L298 with max 18V 2A per channel - // POLOLU_MOTOR_SHIELD : Pololu MC33926 Motor Driver (not recommended for prog track) - // FUNDUMOTO_SHIELD : Fundumoto Shield, no current sensing (not recommended, no short protection) - // FIREBOX_MK1 : The Firebox MK1 - // FIREBOX_MK1S : The Firebox MK1S - // | - // +----------------------- - // - #define MOTOR_SHIELD_TYPE STANDARD_MOTOR_SHIELD - -And for an Arduino UNO or Mega (or any 5v microcontroller) add the following: - -.. code-block:: cpp - - // EX-MotorShield8874 stacked onto Arduino Motor Shield R3 - // For Arduino UNO, Mega and any 5v microcontroller - #define MOTOR_SHIELD_TYPE EX8874_STACKED_ON_ARDUINO - #define EX8874_STACKED_ON_ARDUINO F("EX8874_STACKED_ON_ARDUINO"),\ - 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, A2, 5.08, 5000, A4), \ - new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 5.08, 5000, A5) - - -Or for any 3v3 microcontroller such as STM32 Nucleo models, but not the ESPDuino32, add the following: - -.. code-block:: cpp - - // EX-MotorShield8874 stacked onto Arduino Motor Shield R3 - // For Nucleo/STM32 and any 3v3 microcontroller except ESP32 - #define MOTOR_SHIELD_TYPE EX8874_STACKED_ON_ARDUINO - #define EX8874_STACKED_ON_ARDUINO F("EX8874_STACKED_ON_ARDUINO"),\ - 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), \ - new MotorDriver( 2, 10, UNUSED_PIN, 7, A2, 1.27, 5000, A4), \ - new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 1.27, 5000, A5) - -Stacking Two EX-MotorShield8874s -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The easiest way forward is to leave the first EX-MotorShield8874 in the stack entirely unmodified. Note that if you are using an Ethernet shield, it must be the very first board in the stack, with the unmodified EX-MotorShield8874 next immediately on top of that. As such, this too it likely worth testing first before proceeding to modifying the second EX-MotorShield8874 and adding it on. - -The top EX-MotorShield8874 must have its onboard 7.2V regulators disconnected from the VIN pin at least, and preferably also disabled to save a little power consumption and lower the RF noise. It also needs to have all of its IO pins used to communicate with the |EX-CS| re-routed to alternate pins and an additional motor driver entry created in `config.h` - -The documentation has the `jumpers described on GitHub `_ - -But to be VERY clear, you must CUT the regulator to VIN pin on the top of the PCB which is not labelled on the original version, but has been labelled on later versions: - -.. figure:: /_static/images/motorboards/ex_motorshield8874_vreg_vin_pad.jpg - :alt: DCC-EX EX-MotorShield8874 RevA Vreg output to VIN pad - :scale: 30% - -Then you should also cut the "Regulator Enable" trace on the bottom of the board: - -.. figure:: /_static/images/motorboards/ex_motorshield8874_vreg_enable_pad.jpg - :alt: DCC-EX EX-MotorShield8874 RevA Vreg EMABLE pad - :scale: 30% - -On the top board you then need to alter the Pin Assignment pads (NB: this is for Mega and Nucleo/STM32 motherboards, but is **not** ideal for ESPDuino32 motherboards): - -.. figure:: /_static/images/motorboards/ex_motorshield8874_pin_assignment_pads.jpg - :alt: DCC-EX EX-MotorShield8874 RevA Pin Assignment Pads - :scale: 30% - -* Cut the PWM (EN) jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads -* Cut the FAULT jumpers for both Driver A and Driver B but do NOT solder the right hand ALT pads (explanation below) -* Cut the BRAKE jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads -* Cut the DIR jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads -* Cut the SENSE jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads - -The above will re-allocate the pins used by the top board to the `ALT or alternate set of pins `_ - -The reason we did not solder the FAULT pins to their righthand ALT pads is that this would connect the FAULT pins to D0/D1 on the Arduino R3 headers which is not ideal because D0/D1 typically carry the serial port. You can of course bend those pins out if you wish to use them, and simply jumper them that way. - -If you do wish to use the solder method, solder a jumper wire (carefully!) to the centre pad of the FAULT which you can jumper to any available digital input pin on the motherboard you are using. - -Add **one** of the following motor driver definitions to your config.h file (if uncertain, read :doc:`this description ` first): - -Find this section in the file: - -.. code-block:: cpp - - // DEFINE MOTOR_SHIELD_TYPE BELOW ACCORDING TO THE FOLLOWING TABLE: - // - // STANDARD_MOTOR_SHIELD : Arduino Motor shield Rev3 based on the L298 with max 18V 2A per channel - // POLOLU_MOTOR_SHIELD : Pololu MC33926 Motor Driver (not recommended for prog track) - // FUNDUMOTO_SHIELD : Fundumoto Shield, no current sensing (not recommended, no short protection) - // FIREBOX_MK1 : The Firebox MK1 - // FIREBOX_MK1S : The Firebox MK1S - // | - // +----------------------- - // - #define MOTOR_SHIELD_TYPE STANDARD_MOTOR_SHIELD - -And for an Arduino UNO or Mega (or any 5v microcontroller) add the following: - -.. code-block:: cpp - - // Dual stacked EX-MotorShield8874s - // For Arduino UNO, Mega and any 5v microcontroller - #define MOTOR_SHIELD_TYPE EX8874_DUAL_STACKED - #define EX8874_DUAL_STACKED F("EX8874_DUAL_STACKED"),\ - new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 5.08, 5000, A4), \ - new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 5.08, 5000, A5), \ - new MotorDriver( 2, 10, UNUSED_PIN, 7, A2, 5.08, 5000, YOUR_PIN_A), \ - new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 5.08, 5000, YOUR_PIN_B) - -Or for any 3v3 microcontroller such as STM32 Nucleo models, but not the ESPDuino32, add the following: - -.. code-block:: cpp - - // Dual stacked EX-MotorShield8874s - // For Nucleo/STM32 and any 3v3 microcontroller except ESP32 - #define MOTOR_SHIELD_TYPE EX8874_DUAL_STACKED - #define EX8874_DUAL_STACKED F("EX8874_DUAL_STACKED"),\ - new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 1.27, 5000, A4), \ - new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 1.27, 5000, A5), \ - new MotorDriver( 2, 10, UNUSED_PIN, 7, A2, 1.27, 5000, YOUR_PIN_A), \ - new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 1.27, 5000, YOUR_PIN_B) - -Where `YOUR_PIN_A` and `YOUR_PIN_B` are the pins you have jumpered to the Sense pins for channel A and B respectively on the top EX-MotorShield8874. - -Note that on Nucleo-144 motherboards, D7 and D8 are incapable of Pulse Width Modulation (PWM) for the Brake for channel B on either the first or second shield. PWM is used for |DC PWM| output **and** for managing DCC overload situations for the EX-MotorShield8874. As such it is recommended that the first board in the stack use the default Channel A BRAKE of D9, and the ALT Channel B BRAKE of D6. - -Then on the top EX-MotorShield8874 set all pins except the BRAKE pins for Channel A and B to the ALT settings. For this to work you will also need to disable the Serial6 port as those appear on Arduino D0(PG9)/D1(PG14) which we will use for the ALT FAULT pins. Find the following line in DCCTimerSTM32.cpp and comment it out thusly: - -.. code-block:: cpp - - //HardwareSerial Serial6(PG9, PG14); // Rx=PG9, Tx=PG14 -- USART6 - -The BRAKE pins both need to be isolated by cutting the default setting on the pads, and then solder jumpered to other PWM capable pins such as PE12 and PE14. This requires careful soldering of jumpers to the centre pad of the BRAKE jumper pads for both Channel A and B on the top EX-MotorShield8874. We suggest the use of male-male dupont jumpers where you cut one end off, strip the wires and tin with solder to attached to the centre pad. Then use the male dupont pin to connect to PE12/PE13. The motor driver configuration would then look like this: - -.. code-block:: cpp - - // Dual stacked EX-MotorShield8874s - // For Nucleo-F429ZI/F439ZI - #define MOTOR_SHIELD_TYPE EX8874_DUAL_STACKED_ETH - #define EX8874_DUAL_STACKED_ETH F("EX8874_DUAL_STACKED_ETH"),\ - new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 1.27, 5000, A4), \ - new MotorDriver(11, 13, UNUSED_PIN, 6, A1, 1.27, 5000, A5), \ - new MotorDriver( 2, 10, UNUSED_PIN, 7, A2, 1.27, 5000, YOUR_PIN_A), \ - new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 1.27, 5000, YOUR_PIN_B) - -For more detailed and technical information, follow the link to the `EX-MotorShield8874 on Github `_ It also includes the schematic and the KiCad project files. - ----- - -Testing TrackManager configuration and operation ------------------------------------------------- - -There are some simple tests you can perform to confirm that the EX-MotorShield8874 is operating correctly once configured. - -All of these tests require a serial connection to your |EX-CS| and use interactive commands to change the active configuration. If you're unsure on how to connect via a serial connection, refer to :doc:`/reference/tools/serial-monitor` - -Note in the images below, Track A is the right hand green connector, and Track B is the left hand green connector. - -Firstly, configure both Tracks as ``MAIN`` and turn track power on: - -.. code-block:: cpp - - <= A MAIN> - <= B MAIN> - <1> - -This should result in all four (4) yellow LEDs being lit: - -.. figure:: /_static/images/ex-motorshield8874/tracks-a-b-main-poweron.jpg - :alt: Tracks A/B Main - :scale: 20% - - Tracks A and B configured as ``MAIN`` with power on - -Next, configure Track A as ``DC``, turn power on again, and ensure that there is no throttle speed: - -.. code-block:: cpp - - - <1> - - -This should result in both Track B (left) LEDs being lit, but Track A (right) LEDs being off: - -.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-main-nothrottle.jpg - :alt: Track A DC/B Main no throttle - :scale: 20% - - Track A ``DC``, B ``MAIN``, no throttle - -Set throttle speed for Track A using DCC address 1: - -.. code-block:: cpp - - - -This should result in both Track B (left) LEDs still being lit, and one Track A (right) LED being lit: - -.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-main-throttle.jpg - :alt: Track A DC/B Main throttle - :scale: 20% - - Track A ``DC``, B ``MAIN``, with forward throttle - -Reverse the direction for Track A using DCC address 1: - -.. code-block:: cpp - - - -This should result in both Track B (left) LEDs still being lit, and the opposite Track A (right) LED being lit: - -.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-main-throttlerev.jpg - :alt: Track A DC/B Main throttle reversed - :scale: 20% - - Track A ``DC``, B ``MAIN``, with reverse throttle - -Now configure Track B as ``DC`` with the same DCC address as Track A and power on: - -.. code-block:: cpp - - <= B DC 1> - <1> - -This should now result in one Track B (left) LED being lit, matching Track A's (right) LED being lit: - -.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-dc-throttlerev.jpg - :alt: Track A DC/B DC throttle reversed - :scale: 20% - - Track A ``DC``, B ``DC``, with reverse throttle - -Finally, change to the forward direction again: - -.. code-block:: cpp - - - -This should now result in both Track B (left) and Track A (right) having the opposite LED being lit: - -.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-dc-throttle.jpg - :alt: Track A DC/B DC throttle forward - :scale: 20% - - Track A ``DC``, B ``DC``, with forward throttle +.. include:: include__ex-motor-shield-8874.rst diff --git a/docs/reference/hardware/motorboards/ex-motor-shield-8874_2.rst b/docs/reference/hardware/motorboards/ex-motor-shield-8874_2.rst new file mode 100644 index 0000000000..fec057df44 --- /dev/null +++ b/docs/reference/hardware/motorboards/ex-motor-shield-8874_2.rst @@ -0,0 +1,11 @@ +.. include:: /include/include.rst +.. include:: /include/include-l3.rst +.. include:: /include/include-hardware.rst + +|EX-MS-LOGO| |donate-button| + +****************************** +DCC-EX EX-MotorShield8874 RevA +****************************** + +.. include:: include__ex-motor-shield-8874.rst diff --git a/docs/reference/hardware/motorboards/include__ex-motor-shield-8874.rst b/docs/reference/hardware/motorboards/include__ex-motor-shield-8874.rst new file mode 100644 index 0000000000..550bc305e6 --- /dev/null +++ b/docs/reference/hardware/motorboards/include__ex-motor-shield-8874.rst @@ -0,0 +1,474 @@ +.. include:: /include/include_x.rst +.. include:: /include/include-l3_x.rst + +|SUITABLEx| |conductorx| |tinkererx| |engineerx| |support-buttonx| + +.. sidebar:: + :class: sidebar-on-this-page + + .. contents:: On this page + :depth: 3 + :local: + +.. note:: + + This board is compatible with |TMx| DC mode. + +Designed in conjunction with the |DCC-EXx| development team, the |EX-MSx| is extremely simple to use with all current and future generations of |EX-CSx| hardware. + +It also safely powers the Command Station motherboard via the same single barrel jack DC input voltage that powers the track. It is rated at a very generous peak 5A of load per channel using Texas Instruments DRV8874 MOSFET technology. This board is the new standard by which we compare other boards. + +.. figure:: /_static/images/motorboards/ex_motorshield8874.png + :alt: DCC-EX EX-MotorShield8874 RevA Semify + :scale: 10% + + DCC-EX EX-MotorShield8874 RevA Semify + +.. figure:: /_static/images/motorboards/ex_motorshield8874_purple_side.png + :alt: DCC-EX EX-MotorShield8874 RevA Millennium Engineering + :scale: 10% + + DCC-EX EX-MotorShield8874 RevA Millennium Engineering + +---- + +What Is It? +=========== + +The EX-Motorshield8874 is pin compatible with the original Arduino Motor Shield Rev3 but provides significantly improved electrical performance for driving higher loads, and improved usability. + +* Rated for 5 Amps of continuous output current +* No need to cut traces or bend out pins for stacking on the EX-CommandStation +* 2 outputs (Main and Programming Track or 2 Mains) +* Single power supply input powers the shield, the Arduino, and the track (motor output)! +* 5V and 3.3V compatible +* Virtually no voltage drop, even at high currents +* I2C header and STEMMA Qwiic connector for accessories (displays, port expanders, servo boards, etc.) +* Reverse polarity protection +* Fault detection in addition to overcurrent reporting for extra safety +* Alternative power in and out solder pads for different connector types +* Stackable (Support multiple Power Districts) +* Optional OLED header to connect a display directly to the shield + +The |EX-MSx| is based on two DRV8874 H-bridge motor drivers with integrated current sensing from Texas Instruments (TI). It is used to drive inductive loads like relays, solenoids, DC and stepping motors, as well as provide the DCC signal and power to the model railroad tracks. + +Powering of Arduino boards is possible due to the on board DC/DC buck converter, supporting a wide input supply range from 9 to 25V. The reverse polarity protection prevents damage to the circuit and its components in case the power supply is accidentally connected backwards. + +The board's 5V and 3V3 friendly design makes it suitable for a broad range of Arduino compatible platforms, with an override that compensates for designs with incomplete support (such as an incorrect IORef voltage). + +This Shield features a status LED for supply, which provides a visual indication of the power supply status in addition to LEDs to show each side of the A and B power outputs. + +---- + +Why did we make it? +==================== + +|EX-MSx| is specifically designed for use with DCC-EX Command Station for controlling model railroads, but can also be used as generally better replacement for Arduino Motor Shield R3 in any device that needs to control a motor. We needed higher current capacity to power more motors/trains and have little to no voltage drop due to advanced MOSFET driver technology. + + +.. note:: + + The |EX-MSx| was created through the gracious support and design facilities of Semify, who, along with DCC-EX, license it to manufacturers. The hardware design has been made open source for individual users and the schematics are available on the `DCC-EX GitHub `_ repository. + + +---- + +How can I get one? +================== + +Units may be purchased from the following sources: + +.. include:: /purchasing/include__dealers.rst + +|HR-DASHEDx| + +There are different options for the board such as fully assembled or in kit form where connectors and headers need to be soldered onto the board. Prices vary from around $34.95 to $39.90 in the US, to approximately £29.99 in the UK, €37 in Europe, and in Australia starting from $AU55.00. Prices typically do not include tax and shipping. + +For quantities of 10 or less per annum, you may utilise a PCB manufacturing and assembly service such as JLCPCB without licensing fees. A donation to DCC-EX would be appreciated, so click the DONATE button! The production files are available on the `DCC-EX GitHub `_. + +Entrepreneurs wanting to use the design to offer commercial quantities to their local communities should contact Semify (service @ semify-eda.com) to arrange a bulk purchase or DCC-EX (support @ dcc-ex.com) for a license to manufacture. Licensing includes donating a royalty to DCC-EX per board sold. + +----- + +Assembly with EX-MotorShield8874 +================================ + +Assembly with the |EX-MSx| is extremely simple, just plug the motor shield into your choice of Command Station motherboard. Unlike other motor shields, the EX-MotorShield8874 needs no jumpering, trace cutting, or pin bending! Just plug it in. + +Shown here are examples of the shield plugged into Mega+WiFi, Nucleo-F411RE: + +.. figure:: /_static/images/motorboards/ex_motorshield8874_mega.png + :alt: DCC-EX EX-MotorShield8874 RevA on Mega+WiFi + :scale: 15% + + DCC-EX EX-MotorShield8874 RevA on Mega+WiFi + +.. figure:: /_static/images/motorboards/ex_motorshield8874_nucleo_f411.png + :alt: DCC-EX EX-MotorShield8874 RevA on Nucleo-F411RE + :scale: 15% + + DCC-EX EX-MotorShield8874 RevA on Nucleo-F411RE + +1. Connect DC Power to Motor Driver +------------------------------------ + +The |EX-MSx| accepts a standard 2.1mm inside diameter DC barrel jack for DC power, with centre pin positive, and polarity protected for your safety. Acceptable voltages for correct DCC operation include 10-24VDC, but the shield can cope with 9-25VDC. + +.. figure:: /_static/images/motorboards/ex_motorshield8874_purple_megawifi.png + :alt: DCC-EX EX-MotorShield8874 on Mega+WiFi with power and track connectors + :scale: 10% + + DCC-EX EX-MotorShield8874 on Mega+WiFi with power and track connectors + +.. note:: + **DO NOT** connect power to BOTH the EX-MotorShield8874 barrel jack and the underlying Arduino motherboard via its DC barrel jack as you may damage your Arduino and/or EX-MotorShield8874!! + +The EX-MotorShield8874's DC barrel jack is the only power source required to power both the tracks and the |EX-CSx| into which it is plugged. It supplies carefully regulated 7.2V DC power to the underlying Arduino R3 compatible motherboard via the VIN pin. This voltage is safely regulated down from the track power input to ensure Command Station motherboards will stay cool and work well. There is no need to power the Command Station via its barrel jack, or USB power. It is safe, however, to connect the USB cable as it will not create a conflict. + +.. warning:: + :class: warning-float-right + + These are *common*, but not universal, upper limits of what decoders will accept. You should check the manual of your decoders to confirm what they accept, and adjust the voltage down accordingly. + + :dcc-ex-red-bold-italic:`Applying a voltage above what a decoder was designed for may permanently damage it.` + +Because the EX-MotorShield8874 does not drop voltage like the standard L298 based motor shields we suggest: + +* **10v-12vDC** for Z scale +* **10v-14vDC** for N scale +* **14v-16vDC** for HO/OO scale +* **18v-19vDC** for O scale +* **20v-24vDC** for G scale + +Note that good quality, fully-enclosed and double-insulated switch mode power supplies are best, and we suggest laptop power bricks as ideal in this role as they typically output 3-20A easily and safely. + +.. note:: + Please note that as the EX-MotorShield8874 can supply up to 5A of track power per channel, a power supply of more than 10A peak capacity is required to run both channels at full peak current and have power left for the Command Station. + +.. note:: + If you are just just testing your Arduino (not trying to power the track with the motor shield) some users have found that their PC USB ports have not been providing reliable power to the Arduino and have needed to plug the power supply into EX-MotorShield8874. + +1. Turn on Power to the Motor Driver +------------------------------------ + +Once satisfied the |EX-MSx| is seated properly on the Command Station motherboard, you can apply power to the |EX-CSx|. You ought to see a green LED light up indicating power is being supplied to the motherboard. + +.. figure:: /_static/images/motorboards/ex_motorshield8874_purple_megawifi_LED_on.png + :alt: DCC-EX EX-MotorShield8874 RevA on Mega+WiFi with power LED on + :scale: 10% + + DCC-EX EX-MotorShield8874 RevA on Mega+WiFi with power LED on + +3. Connect Track to Motor Driver +------------------------------------ + +Track power for A (MAIN) and B (PROG) tracks can be connected now using the green track connectors. These unplug conveniently to allow easy swapping in and out of the |EX-CSx|. Make sure to tighten the screws onto the wire in the connectors before applying power. + +.. figure:: /_static/images/motorboards/ex_motorshield8874_purple_connector_closeup.png + :alt: DCC-EX EX-MotorShield8874 RevA connectors + :scale: 30% + + DCC-EX EX-MotorShield8874 RevA connectors + +There are two sets of output connectors on the motor shield, ``A`` and ``B``. A is the Main or Operations (also called 'Ops') track while ``B`` is the Programming or Service track. Connect twisted pair wire of the proper gauge to each track. + +Notice that A (MAIN) is on the left as you look at the connectors, and B (PROG) is on the right, next to the DC barrel jack. + +Polarity (which wire is connected to which side of the track) is not not important here if you are using separate, completely isolated piece of track for PROG. *However* if you will be using a siding track that connects to your main track, make sure that the *connections for both tracks match*. + +In other words, if you view one side of your main track as having a 'left' side and a 'right' side, and connect positive output A to the left side, connect the positive from the B side to the left side of the programming track. In electrical terms, we want both tracks to be "in phase" with each other. Here is the diagram from above repeated again for reference. + +|HR-HEAVYx| + +Next steps +========== + +See the :doc:`/ex-commandstation/diy/wifi-setup` page to learn how to connect the WiFi shield to your |EX-CSx|, or *alternatively* connect a controller like |JMRIx| or our |EX-WTx| by using the serial cable to connect between your computer and the |EX-CSx| as outlined in the :ref:`ex-installer/installing:getting ready` section of the |EX-Ix| page. Note that when configuring the EX-CommandStation you will want to select `EX8874_SHIELD` as the motor board during configuration. + +---- + +Additional Information +====================== + +Stacking EX-MotorShield8874s +---------------------------- + +This is **definitely** advanced Tinkerer/Engineer level work. Do **not** attempt it without some confidence you know what you are doing electronically. Future revisions of the EX-MotorShield8874 will look at alternative ways to expand the number of DCC districts. + +This article covers both stacking an Arduino Motor Shield R3 and an EX-MotorShield8874, and stacking two EX-MotorShield8874s. |BRx| +> Note that L298 clone motor shields can be used on 5V Mega, etc., but require modification for use with 3.3V ESP32-WROOM and Nucleo-F4. :ref:`Link to further detail. ` + +Stacking an Arduino Motor Shield R3 and EX-MotorShield8874 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This stack is perhaps simplest and an easy enough upgrade for those who already have an Arduino Motor Shield R3 or clone. + +We are going to leave the Arduino Motor Shield R3 in the same configuration as recommended on the :doc:`/ex-commandstation/diy/assembly` page and as such it is worth doing this first and testing all is well before proceeding if this is a new install. + +The best solution is to stack the EX-MotorShield8874 on top of the Arduino Motor Shield R3 (is it, really??) for which we will need to re-route some of its IO pins to allow it to function. + +On the EX-MotorShield8874 you need to alter the Pin Assignment pads (NB: the following is fine for Mega and Nucleo/STM32 motherboards, but is **not** ideal for ESPDuino32 motherboards): + +.. figure:: /_static/images/motorboards/ex_motorshield8874_pin_assignment_pads.jpg + :alt: DCC-EX EX-MotorShield8874 RevA Pin Assignment Pads + :scale: 30% + +* Cut the PWM (EN) jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads +* Cut the BRAKE jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads +* Cut the DIR jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads +* Cut the SENSE jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads + +The above will re-allocate most of the pins used by the top board to the `ALT or alternate set of pins `_ |EXTERNAL-LINKx| but note it leaves the FAULT pins routed to the default positions of A4/A5 as there is no conflict with the Arduino Motor Shield R3. + +Add **one** of the following motor driver definitions to your config.h file (if uncertain, read :doc:`this description ` first): + +Find this section in the file: + +.. code-block:: cpp + + // DEFINE MOTOR_SHIELD_TYPE BELOW ACCORDING TO THE FOLLOWING TABLE: + // + // STANDARD_MOTOR_SHIELD : Arduino Motor shield Rev3 based on the L298 with max 18V 2A per channel + // POLOLU_MOTOR_SHIELD : Pololu MC33926 Motor Driver (not recommended for prog track) + // FUNDUMOTO_SHIELD : Fundumoto Shield, no current sensing (not recommended, no short protection) + // FIREBOX_MK1 : The Firebox MK1 + // FIREBOX_MK1S : The Firebox MK1S + // | + // +----------------------- + // + #define MOTOR_SHIELD_TYPE STANDARD_MOTOR_SHIELD + +And for an Arduino UNO or Mega (or any 5v microcontroller) add the following: + +.. code-block:: cpp + + // EX-MotorShield8874 stacked onto Arduino Motor Shield R3 + // For Arduino UNO, Mega and any 5v microcontroller + #define MOTOR_SHIELD_TYPE EX8874_STACKED_ON_ARDUINO + #define EX8874_STACKED_ON_ARDUINO F("EX8874_STACKED_ON_ARDUINO"),\ + 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, A2, 5.08, 5000, A4), \ + new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 5.08, 5000, A5) + + +Or for any 3v3 microcontroller such as STM32 Nucleo models, but not the ESPDuino32, add the following: + +.. code-block:: cpp + + // EX-MotorShield8874 stacked onto Arduino Motor Shield R3 + // For Nucleo/STM32 and any 3v3 microcontroller except ESP32 + #define MOTOR_SHIELD_TYPE EX8874_STACKED_ON_ARDUINO + #define EX8874_STACKED_ON_ARDUINO F("EX8874_STACKED_ON_ARDUINO"),\ + 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), \ + new MotorDriver( 2, 10, UNUSED_PIN, 7, A2, 1.27, 5000, A4), \ + new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 1.27, 5000, A5) + +Stacking Two EX-MotorShield8874s +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The easiest way forward is to leave the first EX-MotorShield8874 in the stack entirely unmodified. Note that if you are using an Ethernet shield, it must be the very first board in the stack, with the unmodified EX-MotorShield8874 next immediately on top of that. As such, this too it likely worth testing first before proceeding to modifying the second EX-MotorShield8874 and adding it on. + +The top EX-MotorShield8874 must have its onboard 7.2V regulators disconnected from the VIN pin at least, and preferably also disabled to save a little power consumption and lower the RF noise. It also needs to have all of its IO pins used to communicate with the |EX-CSx| re-routed to alternate pins and an additional motor driver entry created in `config.h` + +The documentation has the `jumpers described on GitHub `_ + +But to be VERY clear, you must CUT the regulator to VIN pin on the top of the PCB which is not labelled on the original version, but has been labelled on later versions: + +.. figure:: /_static/images/motorboards/ex_motorshield8874_vreg_vin_pad.jpg + :alt: DCC-EX EX-MotorShield8874 RevA Vreg output to VIN pad + :scale: 30% + +Then you should also cut the "Regulator Enable" trace on the bottom of the board: + +.. figure:: /_static/images/motorboards/ex_motorshield8874_vreg_enable_pad.jpg + :alt: DCC-EX EX-MotorShield8874 RevA Vreg EMABLE pad + :scale: 30% + +On the top board you then need to alter the Pin Assignment pads (NB: this is for Mega and Nucleo/STM32 motherboards, but is **not** ideal for ESPDuino32 motherboards): + +.. figure:: /_static/images/motorboards/ex_motorshield8874_pin_assignment_pads.jpg + :alt: DCC-EX EX-MotorShield8874 RevA Pin Assignment Pads + :scale: 30% + +* Cut the PWM (EN) jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads +* Cut the FAULT jumpers for both Driver A and Driver B but do NOT solder the right hand ALT pads (explanation below) +* Cut the BRAKE jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads +* Cut the DIR jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads +* Cut the SENSE jumpers for both Driver A and Driver B, and solder bridge the right hand ALT pads + +The above will re-allocate the pins used by the top board to the `ALT or alternate set of pins `_ + +The reason we did not solder the FAULT pins to their righthand ALT pads is that this would connect the FAULT pins to D0/D1 on the Arduino R3 headers which is not ideal because D0/D1 typically carry the serial port. You can of course bend those pins out if you wish to use them, and simply jumper them that way. + +If you do wish to use the solder method, solder a jumper wire (carefully!) to the centre pad of the FAULT which you can jumper to any available digital input pin on the motherboard you are using. + +Add **one** of the following motor driver definitions to your config.h file (if uncertain, read :doc:`this description ` first): + +Find this section in the file: + +.. code-block:: cpp + + // DEFINE MOTOR_SHIELD_TYPE BELOW ACCORDING TO THE FOLLOWING TABLE: + // + // STANDARD_MOTOR_SHIELD : Arduino Motor shield Rev3 based on the L298 with max 18V 2A per channel + // POLOLU_MOTOR_SHIELD : Pololu MC33926 Motor Driver (not recommended for prog track) + // FUNDUMOTO_SHIELD : Fundumoto Shield, no current sensing (not recommended, no short protection) + // FIREBOX_MK1 : The Firebox MK1 + // FIREBOX_MK1S : The Firebox MK1S + // | + // +----------------------- + // + #define MOTOR_SHIELD_TYPE STANDARD_MOTOR_SHIELD + +And for an Arduino UNO or Mega (or any 5v microcontroller) add the following: + +.. code-block:: cpp + + // Dual stacked EX-MotorShield8874s + // For Arduino UNO, Mega and any 5v microcontroller + #define MOTOR_SHIELD_TYPE EX8874_DUAL_STACKED + #define EX8874_DUAL_STACKED F("EX8874_DUAL_STACKED"),\ + new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 5.08, 5000, A4), \ + new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 5.08, 5000, A5), \ + new MotorDriver( 2, 10, UNUSED_PIN, 7, A2, 5.08, 5000, YOUR_PIN_A), \ + new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 5.08, 5000, YOUR_PIN_B) + +Or for any 3v3 microcontroller such as STM32 Nucleo models, but not the ESPDuino32, add the following: + +.. code-block:: cpp + + // Dual stacked EX-MotorShield8874s + // For Nucleo/STM32 and any 3v3 microcontroller except ESP32 + #define MOTOR_SHIELD_TYPE EX8874_DUAL_STACKED + #define EX8874_DUAL_STACKED F("EX8874_DUAL_STACKED"),\ + new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 1.27, 5000, A4), \ + new MotorDriver(11, 13, UNUSED_PIN, 8, A1, 1.27, 5000, A5), \ + new MotorDriver( 2, 10, UNUSED_PIN, 7, A2, 1.27, 5000, YOUR_PIN_A), \ + new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 1.27, 5000, YOUR_PIN_B) + +Where `YOUR_PIN_A` and `YOUR_PIN_B` are the pins you have jumpered to the Sense pins for channel A and B respectively on the top EX-MotorShield8874. + +Note that on Nucleo-144 motherboards, D7 and D8 are incapable of Pulse Width Modulation (PWM) for the Brake for channel B on either the first or second shield. PWM is used for |DC PWMx| output **and** for managing DCC overload situations for the EX-MotorShield8874. As such it is recommended that the first board in the stack use the default Channel A BRAKE of D9, and the ALT Channel B BRAKE of D6. + +Then on the top EX-MotorShield8874 set all pins except the BRAKE pins for Channel A and B to the ALT settings. For this to work you will also need to disable the Serial6 port as those appear on Arduino D0(PG9)/D1(PG14) which we will use for the ALT FAULT pins. Find the following line in DCCTimerSTM32.cpp and comment it out thusly: + +.. code-block:: cpp + + //HardwareSerial Serial6(PG9, PG14); // Rx=PG9, Tx=PG14 -- USART6 + +The BRAKE pins both need to be isolated by cutting the default setting on the pads, and then solder jumpered to other PWM capable pins such as PE12 and PE14. This requires careful soldering of jumpers to the centre pad of the BRAKE jumper pads for both Channel A and B on the top EX-MotorShield8874. We suggest the use of male-male dupont jumpers where you cut one end off, strip the wires and tin with solder to attached to the centre pad. Then use the male dupont pin to connect to PE12/PE13. The motor driver configuration would then look like this: + +.. code-block:: cpp + + // Dual stacked EX-MotorShield8874s + // For Nucleo-F429ZI/F439ZI + #define MOTOR_SHIELD_TYPE EX8874_DUAL_STACKED_ETH + #define EX8874_DUAL_STACKED_ETH F("EX8874_DUAL_STACKED_ETH"),\ + new MotorDriver( 3, 12, UNUSED_PIN, 9, A0, 1.27, 5000, A4), \ + new MotorDriver(11, 13, UNUSED_PIN, 6, A1, 1.27, 5000, A5), \ + new MotorDriver( 2, 10, UNUSED_PIN, 7, A2, 1.27, 5000, YOUR_PIN_A), \ + new MotorDriver( 5, 4, UNUSED_PIN, 6, A3, 1.27, 5000, YOUR_PIN_B) + +For more detailed and technical information, follow the link to the `EX-MotorShield8874 on Github `_ It also includes the schematic and the KiCad project files. + +---- + +Testing TrackManager configuration and operation +------------------------------------------------ + +There are some simple tests you can perform to confirm that the EX-MotorShield8874 is operating correctly once configured. + +All of these tests require a serial connection to your |EX-CSx| and use interactive commands to change the active configuration. If you're unsure on how to connect via a serial connection, refer to :doc:`/reference/tools/serial-monitor` + +Note in the images below, Track A is the right hand green connector, and Track B is the left hand green connector. + +Firstly, configure both Tracks as ``MAIN`` and turn track power on: + +.. code-block:: cpp + + <= A MAIN> + <= B MAIN> + <1> + +This should result in all four (4) yellow LEDs being lit: + +.. figure:: /_static/images/ex-motorshield8874/tracks-a-b-main-poweron.jpg + :alt: Tracks A/B Main + :scale: 20% + + Tracks A and B configured as ``MAIN`` with power on + +Next, configure Track A as ``DC``, turn power on again, and ensure that there is no throttle speed: + +.. code-block:: cpp + + + <1> + + +This should result in both Track B (left) LEDs being lit, but Track A (right) LEDs being off: + +.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-main-nothrottle.jpg + :alt: Track A DC/B Main no throttle + :scale: 20% + + Track A ``DC``, B ``MAIN``, no throttle + +Set throttle speed for Track A using DCC address 1: + +.. code-block:: cpp + + + +This should result in both Track B (left) LEDs still being lit, and one Track A (right) LED being lit: + +.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-main-throttle.jpg + :alt: Track A DC/B Main throttle + :scale: 20% + + Track A ``DC``, B ``MAIN``, with forward throttle + +Reverse the direction for Track A using DCC address 1: + +.. code-block:: cpp + + + +This should result in both Track B (left) LEDs still being lit, and the opposite Track A (right) LED being lit: + +.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-main-throttlerev.jpg + :alt: Track A DC/B Main throttle reversed + :scale: 20% + + Track A ``DC``, B ``MAIN``, with reverse throttle + +Now configure Track B as ``DC`` with the same DCC address as Track A and power on: + +.. code-block:: cpp + + <= B DC 1> + <1> + +This should now result in one Track B (left) LED being lit, matching Track A's (right) LED being lit: + +.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-dc-throttlerev.jpg + :alt: Track A DC/B DC throttle reversed + :scale: 20% + + Track A ``DC``, B ``DC``, with reverse throttle + +Finally, change to the forward direction again: + +.. code-block:: cpp + + + +This should now result in both Track B (left) and Track A (right) having the opposite LED being lit: + +.. figure:: /_static/images/ex-motorshield8874/tracks-a-dc-b-dc-throttle.jpg + :alt: Track A DC/B DC throttle forward + :scale: 20% + + Track A ``DC``, B ``DC``, with forward throttle diff --git a/docs/reference/hardware/wifi-boards/ex-wifi-shield-8266.rst b/docs/reference/hardware/wifi-boards/ex-wifi-shield-8266.rst index adac9bb18c..088af0950a 100644 --- a/docs/reference/hardware/wifi-boards/ex-wifi-shield-8266.rst +++ b/docs/reference/hardware/wifi-boards/ex-wifi-shield-8266.rst @@ -4,59 +4,8 @@ |donate-button| -.. index:: 8874, EX-MotorShield - ************************* DCC-EX EX-WiFiShield 8266 ************************* -|SUITABLE| |conductor| |tinkerer| |engineer| |support-button| - -.. sidebar:: - :class: sidebar-on-this-page - - .. contents:: On this page - :depth: 1 - :local: - -Designed in conjunction with the |DCC-EX| development team... - -.. image:: /_static/images/wifi/exwifi5.png - :alt: EX-WiFiShield-8266 front - :scale: 40% - :align: left - - -Overview -=========== - -The new v1.1 WiFi shield is a joint DCC-EX and Makerfabs project. It comes already flashed with DCC-EX EX-CommandStation compatible firmware and can now be easily updated with an Arduino or USB to TTL Adapter. - -The EX-WiFiShield 8266 is a cost-effective and highly integrated UART-WiFi module for DCC-EX and general IoT applications. It comes in a standard Arduino Uno shield format and uses ULP technology (Ultra Low Power). - -This WiFi Shield is based on ESP-12F, which is a newer version of the proven ESP8266 chip. With this Shield, you can connect your Command Station to your network, or have it operate as a stand alone Access Point to connect directly from your phone, tablet, laptop, or WiFi hardware throttle. - -Features -==================== - -supports wireless 2.4GHz 802.11 b/g/n supports the STA/AP/STA + AP operation modes Built-in TCP/IP protocol stack, and support for multiple TCP Client connections supports simple AT commands supports UART/GPIO data communication interface supports Smart Link intelligent networking Dimensions: 2.1"(53mm) * 1.9"(47mm) * .9"(23mm) - - - -How can I get one? -================== - -Units may be purchased from the following sources you can find here: :doc:`/purchasing/dealers` - - -Assembly with EX-MotorShield8874 -================================ - -Assembly instructions to come! But the short version is to just connect the shield on top of your Motor Shield and connect the included jumpers from any one of the Tx row of pins to Rx1 on the Mega and a jumper from any of the Rx row pins to the Tx1 header on the Mega. - -|HR-HEAVY| - -Next steps -========== - -See the :doc:`/ex-commandstation/diy/wifi-setup` page to learn how to connect the WiFi shield to your |EX-CS|, or *alternatively* connect a controller like |JMRI| or our |EX-WT| by using the serial cable to connect between your computer and the |EX-CS| as outlined in the :ref:`ex-installer/installing:getting ready` section of the |EX-I| page. Note that when configuring the EX-CommandStation you will want to select `EX8874_SHIELD` as the motor board during configuration. +.. include:: include__ex-wifi-shield-8266.rst diff --git a/docs/reference/hardware/wifi-boards/ex-wifi-shield-8266_2.rst b/docs/reference/hardware/wifi-boards/ex-wifi-shield-8266_2.rst new file mode 100644 index 0000000000..088af0950a --- /dev/null +++ b/docs/reference/hardware/wifi-boards/ex-wifi-shield-8266_2.rst @@ -0,0 +1,11 @@ +.. include:: /include/include.rst +.. include:: /include/include-l3.rst +.. include:: /include/include-hardware.rst + +|donate-button| + +************************* +DCC-EX EX-WiFiShield 8266 +************************* + +.. include:: include__ex-wifi-shield-8266.rst diff --git a/docs/reference/hardware/wifi-boards/include__ex-wifi-shield-8266.rst b/docs/reference/hardware/wifi-boards/include__ex-wifi-shield-8266.rst new file mode 100644 index 0000000000..5ceb345b13 --- /dev/null +++ b/docs/reference/hardware/wifi-boards/include__ex-wifi-shield-8266.rst @@ -0,0 +1,52 @@ +.. include:: /include/include-l3_x.rst + +|SUITABLEx| |conductorx| |tinkererx| |engineerx| |support-buttonx| + +.. sidebar:: + :class: sidebar-on-this-page + + .. contents:: On this page + :depth: 1 + :local: + +Designed in conjunction with the |DCC-EXx| development team... + +.. image:: /_static/images/wifi/exwifi5.png + :alt: EX-WiFiShield-8266 front + :scale: 40% + :align: left + + +Overview +=========== + +The new v1.1 WiFi shield is a joint DCC-EX and Makerfabs project. It comes already flashed with DCC-EX EX-CommandStation compatible firmware and can now be easily updated with an Arduino or USB to TTL Adapter. + +The EX-WiFiShield 8266 is a cost-effective and highly integrated UART-WiFi module for DCC-EX and general IoT applications. It comes in a standard Arduino Uno shield format and uses ULP technology (Ultra Low Power). + +This WiFi Shield is based on ESP-12F, which is a newer version of the proven ESP8266 chip. With this Shield, you can connect your Command Station to your network, or have it operate as a stand alone Access Point to connect directly from your phone, tablet, laptop, or WiFi hardware throttle. + +Features +==================== + +supports wireless 2.4GHz 802.11 b/g/n supports the STA/AP/STA + AP operation modes Built-in TCP/IP protocol stack, and support for multiple TCP Client connections supports simple AT commands supports UART/GPIO data communication interface supports Smart Link intelligent networking Dimensions: 2.1"(53mm) * 1.9"(47mm) * .9"(23mm) + + + +How can I get one? +================== + +Units may be purchased from the sources you can find here: :doc:`/purchasing/dealers` + + +Assembly with EX-MotorShield8874 +================================ + +Assembly instructions to come! But the short version is to just connect the shield on top of your Motor Shield and connect the included jumpers from any one of the Tx row of pins to Rx1 on the Mega and a jumper from any of the Rx row pins to the Tx1 header on the Mega. + +|HR-HEAVY| + +Next steps +========== + +See the :doc:`/ex-commandstation/diy/wifi-setup` page to learn how to connect the WiFi shield to your |EX-CSx|, or *alternatively* connect a controller like |JMRIx| or our |EX-WTx| by using the serial cable to connect between your computer and the |EX-CSx| as outlined in the :ref:`ex-installer/installing:getting ready` section of the |EX-Ix| page. Note that when configuring the EX-CommandStation you will want to select `EX8874_SHIELD` as the motor board during configuration. From c0eae19f0c116875c5cdd7c6d3a4494999b62d13 Mon Sep 17 00:00:00 2001 From: Peter Akers Date: Mon, 11 May 2026 10:13:55 +1000 Subject: [PATCH 3/7] Update include__ex-wifi-shield-8266.rst --- .../hardware/wifi-boards/include__ex-wifi-shield-8266.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/hardware/wifi-boards/include__ex-wifi-shield-8266.rst b/docs/reference/hardware/wifi-boards/include__ex-wifi-shield-8266.rst index 5ceb345b13..a25c2e0ec8 100644 --- a/docs/reference/hardware/wifi-boards/include__ex-wifi-shield-8266.rst +++ b/docs/reference/hardware/wifi-boards/include__ex-wifi-shield-8266.rst @@ -1,3 +1,4 @@ +.. include:: /include/include_x.rst .. include:: /include/include-l3_x.rst |SUITABLEx| |conductorx| |tinkererx| |engineerx| |support-buttonx| @@ -44,7 +45,7 @@ Assembly with EX-MotorShield8874 Assembly instructions to come! But the short version is to just connect the shield on top of your Motor Shield and connect the included jumpers from any one of the Tx row of pins to Rx1 on the Mega and a jumper from any of the Rx row pins to the Tx1 header on the Mega. -|HR-HEAVY| +|HR-HEAVYx| Next steps ========== From dcaa1fb7961a3c6984dbb32320c1d885221c6683 Mon Sep 17 00:00:00 2001 From: Peter Akers Date: Mon, 11 May 2026 12:39:58 +1000 Subject: [PATCH 4/7] more cleanup of the navigation --- .../advanced-setup/installation-options/index.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/ex-commandstation/advanced-setup/installation-options/index.rst b/docs/ex-commandstation/advanced-setup/installation-options/index.rst index 7e2657476e..5e9f373e5d 100644 --- a/docs/ex-commandstation/advanced-setup/installation-options/index.rst +++ b/docs/ex-commandstation/advanced-setup/installation-options/index.rst @@ -23,8 +23,5 @@ There are three options available to install |EX-CS|: The |EX-I| will meet 100% of the needs of a |conductor-text| or |tinkerer-text| with considerably less effort. -.. toctree:: - :maxdepth: 1 - - Install using EX-Installer - Install using Arduino IDE +* :doc:`Install using EX-Installer ` +* :doc:`Install using Arduino IDE ` From 8ba48dac108b6335118b3b0453525d4d75e6cd40 Mon Sep 17 00:00:00 2001 From: Peter Akers Date: Mon, 11 May 2026 12:50:52 +1000 Subject: [PATCH 5/7] Update index.rst --- .../advanced-setup/installation-options/index.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/ex-commandstation/advanced-setup/installation-options/index.rst b/docs/ex-commandstation/advanced-setup/installation-options/index.rst index 5e9f373e5d..7ec0b367ad 100644 --- a/docs/ex-commandstation/advanced-setup/installation-options/index.rst +++ b/docs/ex-commandstation/advanced-setup/installation-options/index.rst @@ -11,8 +11,8 @@ Installation Options There are three options available to install |EX-CS|: -* |EX-I| is aimed at the |conductor-text| or |tinkerer-text| level user utilising the recommended hardware, and is the simplest option to get |EX-CS| installed and running. -* The |Arduino IDE| is more aimed at the |engineer-text| level user who is using different hardware options or requires a level of customisation not available in |EX-I|. +* |EX-I| is aimed at the |conductor-text| or |tinkerer-text| level user utilising the recommended hardware, and is the simplest option to get |EX-CS| installed and running. |BR| |BR| +* The |Arduino IDE| is more aimed at the |engineer-text| level user who is using different hardware options or requires a level of customisation not available in |EX-I|. |BR| |BR| * **Microsoft Visual Studio Code** (VSC) is more aimed at the |engineer-text| level user who is using different hardware options or requires a level of customisation not available in |EX-I|. It better that the |Arduino IDE| in most respects but takes a bit more effort to setup initially. We don't cover this option on these pages. .. important:: @@ -25,3 +25,11 @@ There are three options available to install |EX-CS|: * :doc:`Install using EX-Installer ` * :doc:`Install using Arduino IDE ` + + +.. toctree:: + :hidden: + :maxdepth: 1 + + Install using Arduino IDE + From f0468e58708af7b93bb96d86b47b95c01e0fddad Mon Sep 17 00:00:00 2001 From: Peter Akers Date: Mon, 11 May 2026 13:24:27 +1000 Subject: [PATCH 6/7] microcontroller table updates --- .../include_table_microcontrollers.rst | 26 ++++++++++--------- .../hardware/microcontrollers/arduino-uno.rst | 2 ++ 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/reference/hardware/include_table_microcontrollers.rst b/docs/reference/hardware/include_table_microcontrollers.rst index 82aadbef5a..be0dd15ccd 100644 --- a/docs/reference/hardware/include_table_microcontrollers.rst +++ b/docs/reference/hardware/include_table_microcontrollers.rst @@ -9,7 +9,7 @@ - R |BRxa| e |BRxa| c |BRxa| o |BRxa| m |BRxa| m |BRxa| e |BRxa| n |BRxa| d |BRxa| e |BRxa| d - S |BRxa| u |BRxa| p |BRxa| p |BRxa| o |BRxa| r |BRxa| t |BRxa| e |BRxa| d - Level - - Shield |BRxa| Format + - S |BRxa| h |BRxa| i |BRxa| e |BRxa| l |BRxa| d |BRxa| [#mc10]_ - HAL |BRxa| / |BRxa| |I2Cxa| - E |BRxa| E |BRxa| P |BRxa| R |BRxa| O |BRxa| M - EX- |BRxa| RAIL |BRxa| Sup- |BRxa| port @@ -17,13 +17,13 @@ - D C |BRxa| Sup- |BRxa| port - W |BRxa| i |BRxa| F |BRxa| i - Wifi |BRxa| # |BRxa| Con- |BRxa| nect- |BRxa| ions |BRxa| [#mc9]_ - - Comments / Notes |_xa| |_xa| |_xa| |_xa| |_xa| |_xa| |_xa| |_xa| |_xa| |_xa| + - Comments / Notes |_xa| |_xa| |_xa| |_xa| |_xa| |_xa| |_xa| |_xa| |_xa| * - EX-CSB1 - Yes - Yes - Conductor - - UNO / Mega + - Mega - Yes - Yes - Yes @@ -38,7 +38,7 @@ - Yes - Yes - Conductor - - UNO / Mega + - UNO - Yes - Yes - Yes @@ -52,7 +52,7 @@ - Yes - Yes - Tinkerer - - \- + - UNO - Yes [#mc5]_ - No - Yes @@ -60,13 +60,13 @@ - Yes [#mc2]_ - Yes - ~11 - - Inexpensive and includes both WiFi and Bluetooth connectivity, limited in I/O pins + - Inexpensive and includes both WiFi and Bluetooth connectivity, limited in I/O pins. Most require hardware modifications to work. * - :doc:`STM32 Nucleo` - Yes - Yes - Tinkerer - - \- + - UNO - Yes - No - Yes @@ -76,11 +76,11 @@ - 4 - Lots of memory and 32 bit architecture, still in the convenient Uno form factor but with more I/O pins - * - Arduino :doc:`Uno R3` + * - Arduino :doc:`Uno R3` [#mc11]_ - No - Yes - Tinkerer - - UNO / Mega + - UNO - No - Yes - Limit- |BRxa| ed [#mc3]_ @@ -96,7 +96,7 @@ - :cspan:`8` \- - :dcc-ex-red-bold-italic:`Different architecture to the R3. Will never be supported.` - * - Arduino :doc:`Nano` + * - Arduino :doc:`Nano` [#mc11]_ - No - Yes - Tinkerer @@ -114,7 +114,7 @@ - No [#mc6]_ - Yes - Tinkerer - - UNO / Mega + - Mega - Yes - Yes - Yes @@ -174,4 +174,6 @@ .. [#mc6] While the Mega+WiFi boards seem like a good option and are based on our well-known, stable Mega2560 platform, there are many reports of quality issues with these, so buyer beware, and use of these is not recommended .. [#mc7] The core development team no longer have access to these, and testing is limited to ensuring the software compiles for the board type .. [#mc8] The core Arduino library has a bug affecting serial console output which can be patched but renders the device unsuited for future development until fixed in the main Arduino core library for SAMD21 -.. [#mc9] Direct WiFi connections. If connected via JMRI, more are are supported +.. [#mc9] Number of *direct* WiFi connections. If connected via JMRI, more are are supported +.. [#mc10] If the board supports stackable shields. UNO, Mega = Supports both Uno/Mega shields, \- = no shield format +.. [#mc11] Requires the use of JMRI. diff --git a/docs/reference/hardware/microcontrollers/arduino-uno.rst b/docs/reference/hardware/microcontrollers/arduino-uno.rst index b65390a8a3..594cd3e46c 100644 --- a/docs/reference/hardware/microcontrollers/arduino-uno.rst +++ b/docs/reference/hardware/microcontrollers/arduino-uno.rst @@ -14,6 +14,8 @@ Arduino Uno (Not recommended) If you already have an Uno, or will use |JMRI| to control your trains, then by all means use an Uno. Just remember that you can't have WiFi, Ethernet or a few other options due to memory limitations. But as a Command Station connected to |JMRI| with a USB cable it works great. +Support for the Arduino Uno will soon be discontinued for future releases of the |EX_CS| software. You will continue to be able to install older versions. + .. image:: /_static/images/microcontrollers/uno.png :alt: Arduino Uno R3 :scale: 75% From 204f86c4685b7ac0de730c1f383ae3c55471c1a5 Mon Sep 17 00:00:00 2001 From: Peter Akers Date: Mon, 11 May 2026 13:30:13 +1000 Subject: [PATCH 7/7] Update arduino-uno.rst --- docs/reference/hardware/microcontrollers/arduino-uno.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/hardware/microcontrollers/arduino-uno.rst b/docs/reference/hardware/microcontrollers/arduino-uno.rst index 594cd3e46c..71cbbfe726 100644 --- a/docs/reference/hardware/microcontrollers/arduino-uno.rst +++ b/docs/reference/hardware/microcontrollers/arduino-uno.rst @@ -14,7 +14,7 @@ Arduino Uno (Not recommended) If you already have an Uno, or will use |JMRI| to control your trains, then by all means use an Uno. Just remember that you can't have WiFi, Ethernet or a few other options due to memory limitations. But as a Command Station connected to |JMRI| with a USB cable it works great. -Support for the Arduino Uno will soon be discontinued for future releases of the |EX_CS| software. You will continue to be able to install older versions. +Support for the Arduino Uno will soon be discontinued for future releases of the |EX-CS| software. You will continue to be able to install older versions. .. image:: /_static/images/microcontrollers/uno.png :alt: Arduino Uno R3