Difference between revisions of "Command Station Macros"
TCSSoftware (talk | contribs) |
TCSSoftware (talk | contribs) |
||
| Line 24: | Line 24: | ||
*In addition, for each macro a custom LCC Event can be configured as a trigger. Whenever that Event gets produced on the LCC Bus, the macro will execute. | *In addition, for each macro a custom LCC Event can be configured as a trigger. Whenever that Event gets produced on the LCC Bus, the macro will execute. | ||
| − | == How to view and edit macros == | + | ==How to view and edit macros== |
Macros can be viewed and edited using the Command Station configuration. In JMRI there is a separate segment for Macros when opening the Configuration Dialog of the CS-105 or the LT-50. On the TCS throttles, select Menu > Settings > DCC System Settings > Macros. | Macros can be viewed and edited using the Command Station configuration. In JMRI there is a separate segment for Macros when opening the Configuration Dialog of the CS-105 or the LT-50. On the TCS throttles, select Menu > Settings > DCC System Settings > Macros. | ||
| Line 31: | Line 31: | ||
'''On the TCS throttles''' | '''On the TCS throttles''' | ||
| − | # Select Menu > Settings > DCC System Settings > Macros | + | #Select Menu > Settings > DCC System Settings > Macros |
| − | # Select [1] Load Macro to Editor | + | #Select [1] Load Macro to Editor |
| − | # Type in the macro number (e.g. [2][5]), then press ENTER or [..]Save | + | #Type in the macro number (e.g. [2][5]), then press ENTER or [..]Save |
| − | # Select [2] Macro Editor | + | #Select [2] Macro Editor |
| − | # Select [7] Steps | + | #Select [7] Steps |
| − | # Select which step you want to modify and edit the settings of this step. | + | #Select which step you want to modify and edit the settings of this step. |
'''On JMRI / Configuration Editor''' | '''On JMRI / Configuration Editor''' | ||
| − | # Open the LCC Configuration of the CS-105 / LT-50 | + | #Open the LCC Configuration of the CS-105 / LT-50 |
| − | # Expand ''“Segment: Macros”''. | + | #Expand ''“Segment: Macros”''. |
| − | # Enter the macro number into the ''“Load Macro to Editor”'' field. Press Write next to this field. | + | #Enter the macro number into the ''“Load Macro to Editor”'' field. Press Write next to this field. |
| − | # Press the ''“Refresh All”'' button at the bottom of the page. '''This is very important!''' Otherwise you will have the old macro’s values on your screen, but you will be writing to the new macro’s storage. | + | #Press the ''“Refresh All”'' button at the bottom of the page. '''This is very important!''' Otherwise you will have the old macro’s values on your screen, but you will be writing to the new macro’s storage. |
| − | # Verify that the correct macro is on your screen by checking the ''“Macro Number”'' field. This field is only for your information, it cannot be changed. | + | #Verify that the correct macro is on your screen by checking the ''“Macro Number”'' field. This field is only for your information, it cannot be changed. |
| − | # Select the Step you want to modify from the tabbed group and edit the settings of that step. | + | #Select the Step you want to modify from the tabbed group and edit the settings of that step. |
| − | + | ||
| + | == Available individual actions == | ||
| + | An action is what a given step of a macro will do. Select the action from the dropdown (in JMRI) or enter the menu ''“Command”'' on a TCS throttle. Each action carries a Number argument or an LCC Event argument (but not both). | ||
| + | |||
| + | As of this writing, the following actions can be configured for each step. | ||
| + | |||
| + | === Set DCC Turnout Normal / Reverse === | ||
| + | The Number argument should be filled in with the DCC Turnout number. The accepted range is 1 to 2040. Normal is also known as Closed, and Reverse is also known as Thrown. | ||
| + | |||
| + | The TCS Command Station will send this command both to the LCC Bus and the DCC bus. This will work even in the case when you use a separate command station for Accessory Bus. | ||
| + | |||
| + | The Macro Engine achieves this by producing an LCC Event in the Well-Known range “Activate basic DCC accessory decoder address”. The Event ID is as follows: 01.01.02.00.00.FF.00.00 + (number + 3) * 2 for Reverse, and 01.01.02.00.00.FF.00.00 + (number + 3) * 2 + 1 for Normal. This numbering scheme aligns with the “DCC Vendor B Binary Address” scheme as documented in the OpenLCB Event Identifiers Technical Note document, and it matches what the TCS Throttles do when a given accessory is controlled. | ||
| + | |||
| + | On the DCC bus, in the default configuration the DCC Accessory Control packet for the accessory with the given number and given state will be emitted. | ||
| + | |||
| + | === Send LCC Event === | ||
| + | The Event argument should be filled in with an LCC Event in JMRI (Event ID can not be edited on the TCS Throttles). This Event will be produced by the Command Station when the macro is triggered. | ||
| + | |||
| + | Use this option to operate LCC-connected Accessories such as throwing LCC Turnouts. | ||
| + | |||
| + | === Link Macro === | ||
| + | The Number argument should be filled in with a macro number (1 to 300). The respective macro will be executed after the current macro is completed or paused due to a Delay. | ||
| + | |||
| + | === Delay === | ||
| + | Suspends execution of the macro for a specified amount of time. The unit is in 0.1 seconds, so a parameter of 40 will pause the execution of the macro for 4 seconds. During the wait, other macros may be running, which is important to know -- when locomotive control is needed after the delay, the locomotive selection needs to be re-done after the Delay step. | ||
| + | |||
| + | The macro can not be triggered again while it is in a Delay step. If a new trigger arrives during the Delay, the additional trigger is lost. | ||
| + | |||
| + | The maximum delay is 3276 seconds. | ||
| + | |||
| + | === Invalid Macro === | ||
| + | When the Command dropdown shows ''“Invalid Macro”'' for a step, that means that no macro was loaded into the Macro Editor. You need to perform the steps at ''“How to view and edit macros”'' first. | ||
| + | |||
| + | == Locomotive Control == | ||
| + | |||
| + | There are additional Actions available in the Command dropdown for locomotive control. These act together in a particular way, and in almost all cases, more than one step in sequence is needed to control a locomotive. | ||
| + | |||
| + | The Macro Engine has a built-in "Throttle". There are Actions for selecting a locomotive that should be on this throttle, and there are Actions to control the current locomotive speed, direction and functions. ''It is very important to first select a specific locomotive, and in the next step issue the speed/function control command.'' It is also possible to send more than one control command to the currently selected locomotive. | ||
| + | |||
| + | When a Macro executes a Delay command or a Link Macro command, it is not guaranteed that the same locomotive is still selected after the Delay is complete, or when the linked Macro starts executing. Therefore it is important to re-select the locomotive after a Delay and at the beginning of every Macro. | ||
| + | |||
| + | === Select Loco DCC Short === | ||
| + | |||
| + | The parameter is a DCC Address (1-127). The Macro Throttle selects the DCC locomotive with this short address. | ||
| + | |||
| + | === Select Loco DCC Long === | ||
| + | |||
| + | The parameter is a DCC Address (0-10239). The Macro Throttle selects the DCC locomotive with this long address. | ||
| + | |||
| + | === Select Loco LCC === | ||
| + | |||
| + | Selects an LCC locomotive (e.g. direct wireless locomotive decoders). | ||
| + | |||
| + | The parameter is any Event ID from the LCC Node ID's range. The Macro Throttle selects the LCC locomotive with this Node ID. The last two bytes are ignored. | ||
| + | |||
| + | Example: to select the LCC wireless locomotive 99.88.77.66.55.44, enter the Event ID 99.88.77.66.55.44.00.00 into the parameter. | ||
| + | |||
| + | === Loco Speed Forward === | ||
| + | |||
| + | The parameter is a speed in mph, 0-126. The current locomotive will be set to forward direction with this speed. For DCC Locomotives, the parameter will be the speed step commanded. | ||
| + | |||
| + | === Loco Speed Reverse === | ||
| + | |||
| + | The parameter is a speed in mph, 0-126. The current locomotive will be set to reverse direction with this speed. For DCC Locomotives, the parameter will be the speed step commanded. | ||
| + | |||
| + | === Loco E-Stop === | ||
| + | |||
| + | The current locomotive will be set to E-Stop. | ||
| + | |||
| + | === Loco Function On === | ||
| + | |||
| + | The parameter is a function number (0 - 68 for DCC). The specified function will be turned on for the current locomotive. | ||
| + | |||
| + | === Loco Function Off === | ||
| + | |||
| + | The parameter is a function number (0 - 68 for DCC). The specified function will be turned off for the current locomotive. | ||
| + | |||
| + | == Additional features == | ||
Revision as of 20:17, 22 December 2024
Contents
Overview
The purpose of Command Station Macros is to allow users to easily perform multiple operations by a single action, such as lining up routes across yard ladders. It can also be used for creating simple automation scenarios, such as a shuttle service using a DCC locomotive (trolley). Both the TCS CS-105 and the TCS LT-50 support Command Station Macros, albeit with different capacity.
Macros can be triggered using TCS throttles, LCC connected buttons, or other LCC input devices such as a block detector.
Introduction
What is a macro?
A macro is a list of steps. Each step can be configured by the user to do a specific layout operation. A macro can have up to 10 steps. When the macro is triggered, the steps start executing in quick succession from the beginning. Each macro is identified by a macro number in the command station. The CS-105 supports up to 300 macros, they are numbered 1 to 300.
What is a step?
Each step in the macro can be configured by the user to perform a specific action on the layout. A typical action would be for example to set Turnout #175 to Normal/Closed. When configuring the step, select the action as “DCC Turnout Normal” and type in 175 to the parameter. See below for the detailed documentation of the possible steps.
What if more than 10 steps are needed?
A step in a macro can be configured to trigger another macro. Select the action “Link Macro” and type the macro number in the parameter box. Linked macros execute after the referencing macro completes all steps, or pauses due to a Delay step.
Where are macros stored?
Macros are stored in the internal storage of the command station, together with the locomotive roster and consists. This storage is persistent across power cycles. All changes to macros are saved immediately as the setting is written and are in effect as soon as the macro is next triggered. A factory reset of the command station erases all internal storage, including all macros. The remaining internal storage is visible in the DCC System Settings > Status > Free Storage. Macros are archived into the backup file when a Roster Backup from the Command Station is created.
How is a macro triggered?
- On the TCS throttles, starting with software release 3.0, a macro can be triggered by using Select Accessory, then entering 0, then the macro number, and pressing enter. For example to trigger macro 82, type [Accy][0][8][2][ENTER].
- Each macro has a well-known LCC Event ID that triggers it. This Event ID is 09.00.99.FE.FF.FF.00.00 plus the macro number (use hex for the macro number), and it is the same across all TCS command stations and throttles. In the JMRI Configuration Dialog this Event ID is listed for the macro being edited, which allows it to be copy-pastes to other LCC Event Producers to trigger the macro.
- In addition, for each macro a custom LCC Event can be configured as a trigger. Whenever that Event gets produced on the LCC Bus, the macro will execute.
How to view and edit macros
Macros can be viewed and edited using the Command Station configuration. In JMRI there is a separate segment for Macros when opening the Configuration Dialog of the CS-105 or the LT-50. On the TCS throttles, select Menu > Settings > DCC System Settings > Macros.
At any point in time, only one macro is shown in the Macro Editor. To select which macro to show in the Macro Editor, type the Macro Number into the “Load Macro to Editor” field, hit Write, then refresh the Editor (in JMRI use the Refresh All button) to see the macro’s current definition and change it.
On the TCS throttles
- Select Menu > Settings > DCC System Settings > Macros
- Select [1] Load Macro to Editor
- Type in the macro number (e.g. [2][5]), then press ENTER or [..]Save
- Select [2] Macro Editor
- Select [7] Steps
- Select which step you want to modify and edit the settings of this step.
On JMRI / Configuration Editor
- Open the LCC Configuration of the CS-105 / LT-50
- Expand “Segment: Macros”.
- Enter the macro number into the “Load Macro to Editor” field. Press Write next to this field.
- Press the “Refresh All” button at the bottom of the page. This is very important! Otherwise you will have the old macro’s values on your screen, but you will be writing to the new macro’s storage.
- Verify that the correct macro is on your screen by checking the “Macro Number” field. This field is only for your information, it cannot be changed.
- Select the Step you want to modify from the tabbed group and edit the settings of that step.
Available individual actions
An action is what a given step of a macro will do. Select the action from the dropdown (in JMRI) or enter the menu “Command” on a TCS throttle. Each action carries a Number argument or an LCC Event argument (but not both).
As of this writing, the following actions can be configured for each step.
Set DCC Turnout Normal / Reverse
The Number argument should be filled in with the DCC Turnout number. The accepted range is 1 to 2040. Normal is also known as Closed, and Reverse is also known as Thrown.
The TCS Command Station will send this command both to the LCC Bus and the DCC bus. This will work even in the case when you use a separate command station for Accessory Bus.
The Macro Engine achieves this by producing an LCC Event in the Well-Known range “Activate basic DCC accessory decoder address”. The Event ID is as follows: 01.01.02.00.00.FF.00.00 + (number + 3) * 2 for Reverse, and 01.01.02.00.00.FF.00.00 + (number + 3) * 2 + 1 for Normal. This numbering scheme aligns with the “DCC Vendor B Binary Address” scheme as documented in the OpenLCB Event Identifiers Technical Note document, and it matches what the TCS Throttles do when a given accessory is controlled.
On the DCC bus, in the default configuration the DCC Accessory Control packet for the accessory with the given number and given state will be emitted.
Send LCC Event
The Event argument should be filled in with an LCC Event in JMRI (Event ID can not be edited on the TCS Throttles). This Event will be produced by the Command Station when the macro is triggered.
Use this option to operate LCC-connected Accessories such as throwing LCC Turnouts.
Link Macro
The Number argument should be filled in with a macro number (1 to 300). The respective macro will be executed after the current macro is completed or paused due to a Delay.
Delay
Suspends execution of the macro for a specified amount of time. The unit is in 0.1 seconds, so a parameter of 40 will pause the execution of the macro for 4 seconds. During the wait, other macros may be running, which is important to know -- when locomotive control is needed after the delay, the locomotive selection needs to be re-done after the Delay step.
The macro can not be triggered again while it is in a Delay step. If a new trigger arrives during the Delay, the additional trigger is lost.
The maximum delay is 3276 seconds.
Invalid Macro
When the Command dropdown shows “Invalid Macro” for a step, that means that no macro was loaded into the Macro Editor. You need to perform the steps at “How to view and edit macros” first.
Locomotive Control
There are additional Actions available in the Command dropdown for locomotive control. These act together in a particular way, and in almost all cases, more than one step in sequence is needed to control a locomotive.
The Macro Engine has a built-in "Throttle". There are Actions for selecting a locomotive that should be on this throttle, and there are Actions to control the current locomotive speed, direction and functions. It is very important to first select a specific locomotive, and in the next step issue the speed/function control command. It is also possible to send more than one control command to the currently selected locomotive.
When a Macro executes a Delay command or a Link Macro command, it is not guaranteed that the same locomotive is still selected after the Delay is complete, or when the linked Macro starts executing. Therefore it is important to re-select the locomotive after a Delay and at the beginning of every Macro.
Select Loco DCC Short
The parameter is a DCC Address (1-127). The Macro Throttle selects the DCC locomotive with this short address.
Select Loco DCC Long
The parameter is a DCC Address (0-10239). The Macro Throttle selects the DCC locomotive with this long address.
Select Loco LCC
Selects an LCC locomotive (e.g. direct wireless locomotive decoders).
The parameter is any Event ID from the LCC Node ID's range. The Macro Throttle selects the LCC locomotive with this Node ID. The last two bytes are ignored.
Example: to select the LCC wireless locomotive 99.88.77.66.55.44, enter the Event ID 99.88.77.66.55.44.00.00 into the parameter.
Loco Speed Forward
The parameter is a speed in mph, 0-126. The current locomotive will be set to forward direction with this speed. For DCC Locomotives, the parameter will be the speed step commanded.
Loco Speed Reverse
The parameter is a speed in mph, 0-126. The current locomotive will be set to reverse direction with this speed. For DCC Locomotives, the parameter will be the speed step commanded.
Loco E-Stop
The current locomotive will be set to E-Stop.
Loco Function On
The parameter is a function number (0 - 68 for DCC). The specified function will be turned on for the current locomotive.
Loco Function Off
The parameter is a function number (0 - 68 for DCC). The specified function will be turned off for the current locomotive.
