Package jmri.implementation

Class MultiIndexProgrammerFacade

  • All Implemented Interfaces:
    java.util.EventListener, Disposable, ProgListener, Programmer
    public class MultiIndexProgrammerFacade
extends AbstractProgrammerFacade
implements ProgListener
    Programmer facade for accessing CVs that require one or more "index CVs" to have specific values before doing the final read or write operation.

    Currently supports direct access to CVs (the usual style), operations where one index CV (called PI, for primary index) must have a specific value first, and operations where two index CVs (called PI and SI, for secondary index) must have a specific value first.

    Accepts two different address formats so that the CV addresses can be written in the same style as the decoder manufacturer's documentation:

    • If cvFirst is true:
      • 123 Do read or write directly to CV 123; this allows unindexed CVs to go through
      • 123.11 Writes 11 to PI, the index CV, then does the final read or write to CV 123
      • 123.11.12 Writes 11 to the first index CV, then 12 to the second index CV, then does the final read or write to CV 123
    • If cvFirst is false:
      • 123 Do read or write directly to CV 123; this allows unindexed CVs to go through
      • 11.123 Writes 11 to the first index CV, then does the final read or write to CV 123
      • 11.12.123 Writes 11 to the first index CV, then 12 to the second index CV, then does the final read or write to CV 123
    QSI decoders generally use the 1st format, and ESU LokSound decoders the second.

    The specific CV numbers for PI and SI are provided when constructing the object. They can be read from a decoder definition file by e.g. ProgrammerFacadeSelector.

    Alternately the PI and/or SI CV numbers can be set by using a "nn=nn" syntax when specifying PI and/or SI. For example, using a cvFirst false syntax, "101=12.80" sets CV101 to 12 before accessing CV 80, regardless of the PI value configured into the facade.

    If skipDupIndexWrite is true, sequential operations with the same PI and SI values (and only immediately sequential operations with both PI and SI unchanged) will skip writing of the PI and SI CVs. This might not work for some decoders, hence is configurable. See the logic in ProgrammerFacadeSelector for how the decoder file contents and default (preferences) interact.

    State Diagram for read and write operations (click to magnify): UML State diagram

    See Also:
    ProgrammerFacadeSelector

    • Constructor Detail

      • MultiIndexProgrammerFacade

        public MultiIndexProgrammerFacade​(Programmer prog,
                                  java.lang.String indexPI,
                                  java.lang.String indexSI,
                                  boolean cvFirst,
                                  boolean skipDupIndexWrite)
        Parameters:
        prog - the programmer to which this facade is attached
        indexPI - CV to which the first value is to be written for NN.NN and NN.NN.NN forms
        indexSI - CV to which the second value is to be written for NN.NN.NN forms
        cvFirst - true if first value in parsed CV is to be written; false if second value is to be written
        skipDupIndexWrite - true if heuristics can be used to skip PI and SI writes; false requires them to be written each time.

    • Method Detail

      • parseCV

        void parseCV​(java.lang.String cv)

      • useCachePiSi

        boolean useCachePiSi()
        Check if the last-written PI and SI values can still be counted on.
        Returns:
        true if last-written values are reliable; false otherwise

      • writeCV

        public void writeCV​(java.lang.String CV,
                    int val,
                    ProgListener p)
             throws ProgrammerException
        Description copied from class: AbstractProgrammerFacade
        Perform a CV write in the system-specific manner, and using the specified programming mode.

        Handles a general address space through a String address. Each programmer defines the acceptable formats.

        Note that this returns before the write is complete; you have to provide a ProgListener to hear about completion. For simplicity, expect the return to be on the GUI thread.

        Exceptions will only be thrown at the start, not during the actual programming sequence. A typical exception would be due to an invalid mode (though that should be prevented earlier)

        Specified by:
        writeCV in interface Programmer
        Overrides:
        writeCV in class AbstractProgrammerFacade
        Parameters:
        CV - the CV to write
        val - the value to write
        p - the listener that will be notified of the write
        Throws:
        ProgrammerException - if unable to communicate

      • readCV

        public void readCV​(java.lang.String CV,
                   ProgListener p)
            throws ProgrammerException
        Description copied from class: AbstractProgrammerFacade
        Perform a CV read in the system-specific manner, and using the specified programming mode.

        Handles a general address space through a String address. Each programmer defines the acceptable formats.

        Note that this returns before the write is complete; you have to provide a ProgListener to hear about completion. For simplicity, expect the return to be on the GUI thread.

        Exceptions will only be thrown at the start, not during the actual programming sequence. A typical exception would be due to an invalid mode (though that should be prevented earlier)

        Specified by:
        readCV in interface Programmer
        Overrides:
        readCV in class AbstractProgrammerFacade
        Parameters:
        CV - the CV to read
        p - the listener that will be notified of the read
        Throws:
        ProgrammerException - if unable to communicate

      • readCV

        public void readCV​(java.lang.String CV,
                   ProgListener p,
                   int startVal)
            throws ProgrammerException
        Description copied from interface: Programmer
        Perform a CV read in the system-specific manner, and using the specified programming mode, possibly using a hint of the current value to speed up programming.

        Handles a general address space through a String address. Each programmer defines the acceptable formats.

        On systems that support it, the startVal is a hint as to what the current value of the CV might be (e.g. the value from the roster). This could be verified immediately in direct byte mode to speed up the read process.

        Note that this returns before the write is complete; you have to provide a ProgListener to hear about completion. For simplicity, expect the return to be on the GUI thread.

        Defaults to the normal read method if not overridden in a specific implementation.

        Exceptions will only be thrown at the start, not during the actual programming sequence. A typical exception would be due to an invalid mode (though that should be prevented earlier)

        Specified by:
        readCV in interface Programmer
        Parameters:
        CV - the CV to read
        p - the listener that will be notified of the read
        startVal - a hint of what the current value might be, or 0
        Throws:
        ProgrammerException - if unable to communicate

      • confirmCV

        public void confirmCV​(java.lang.String CV,
                      int val,
                      ProgListener p)
               throws ProgrammerException
        Description copied from class: AbstractProgrammerFacade
        Confirm the value of a CV using the specified programming mode. On some systems, this is faster than a read.

        Handles a general address space through a String address. Each programmer defines the acceptable formats.

        Note that this returns before the write is complete; you have to provide a ProgListener to hear about completion. For simplicity, expect the return to be on the GUI thread.

        Exceptions will only be thrown at the start, not during the actual programming sequence. A typical exception would be due to an invalid mode (though that should be prevented earlier)

        Specified by:
        confirmCV in interface Programmer
        Overrides:
        confirmCV in class AbstractProgrammerFacade
        Parameters:
        CV - the CV to confirm
        val - the value to confirm
        p - the listener that will be notified of the confirmation
        Throws:
        ProgrammerException - if unable to communicate

      • programmingOpReply

        public void programmingOpReply​(int value,
                               int status)
        Description copied from interface: ProgListener
        Receive a callback at the end of a programming operation.
        Specified by:
        programmingOpReply in interface ProgListener
        Parameters:
        value - Value from a read operation, or value written on a write
        status - Denotes the completion code. Note that this is a bitwise combination of the various status coded defined in this interface.