Difference between revisions of "Command Station Macros"
TCSSoftware (talk | contribs) |
TCSSoftware (talk | contribs) |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | == Overview == | + | ==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. | 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. | Macros can be triggered using TCS throttles, LCC connected buttons, or other LCC input devices such as a block detector. | ||
| − | == Introduction == | + | ==Introduction== |
| − | '''What is a macro?''' <br/> | + | '''What is a macro?''' <br /> |
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. | 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. | ||
| Line 16: | Line 16: | ||
'''Where are macros stored?''' <br> | '''Where are macros stored?''' <br> | ||
| − | 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 | + | 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 [[CS-105 Database Backup|Database Backup]] from the Command Station is created. |
| − | '''How is a macro triggered?''' | + | '''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. | ||
| − | test | + | 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. | ||
| + | |||
| + | ==Additional features== | ||
| + | |||
| + | '''Macro Name'''<br> | ||
| + | Each macro can have a textual description associated with it. The Command Station stores this text as-is. This is intended for user documentation. | ||
| + | |||
| + | '''Disable'''<br> | ||
| + | If a macro is misbehaving, the Disable settings can be set to “Not Allowed To Run”. When a disabled macro is triggered using a throttle, via the LCC Events, or via Link Macro, nothing happens. | ||
| + | |||
| + | '''Test Trigger'''<br> | ||
| + | To test run the macro currently loaded into the Macro Editor, select Trigger Now to “Go!” and Save (Write) this field. The macro will be executed immediately. The Test Trigger works even if the macro is disabled. | ||
| + | |||
| + | ==Limitations== | ||
| + | |||
| + | *The CS-105 can store up to 300 macros, which are numbered 1 to 300. | ||
| + | *The LT-50 can store up to 20 macros, which are numbered 1 to 20. | ||
| + | *Each macro can have up to 10 steps. | ||
| + | *Macro steps (except steps set to ''Unused'' command) take up storage. The total amount of storage is limited, and is used together with consists and roster entries. The available storage can be viewed under the DCC System Settings > Status > Free Storage menu item on a TCS Throttle. | ||
Latest revision as of 20:44, 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 Database 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.
Additional features
Macro Name
Each macro can have a textual description associated with it. The Command Station stores this text as-is. This is intended for user documentation.
Disable
If a macro is misbehaving, the Disable settings can be set to “Not Allowed To Run”. When a disabled macro is triggered using a throttle, via the LCC Events, or via Link Macro, nothing happens.
Test Trigger
To test run the macro currently loaded into the Macro Editor, select Trigger Now to “Go!” and Save (Write) this field. The macro will be executed immediately. The Test Trigger works even if the macro is disabled.
Limitations
- The CS-105 can store up to 300 macros, which are numbered 1 to 300.
- The LT-50 can store up to 20 macros, which are numbered 1 to 20.
- Each macro can have up to 10 steps.
- Macro steps (except steps set to Unused command) take up storage. The total amount of storage is limited, and is used together with consists and roster entries. The available storage can be viewed under the DCC System Settings > Status > Free Storage menu item on a TCS Throttle.
