Interface Programmer
-
- All Superinterfaces:
Disposable
- All Known Subinterfaces:
AddressedProgrammer
- All Known Implementing Classes:
AbstractProgrammer
,AbstractProgrammerFacade
,AccessoryOpsModeProgrammerFacade
,AddressedHighCvProgrammerFacade
,BiDiBOpsModeProgrammer
,BiDiBProgrammer
,CbusDccOpsModeProgrammer
,CbusDccProgrammer
,Dcc4PcOpsModeProgrammer
,DCCppOpsModeProgrammer
,DCCppProgrammer
,EasyDccOpsModeProgrammer
,EasyDccProgrammer
,EcosOpsModeProgrammer
,EcosProgrammer
,EliteXNetProgrammer
,LI100XNetProgrammer
,LnDeferProgrammer
,LnOpsModeProgrammer
,MrcOpsModeProgrammer
,MrcProgrammer
,MultiIndexProgrammerFacade
,Mx1OpsModeProgrammer
,Mx1Programmer
,NceOpsModeProgrammer
,NceProgrammer
,OffsetHighCvProgrammerFacade
,OlcbProgrammer
,OpsModeDelayedProgrammerFacade
,ProgDebugger
,QsiProgrammer
,ResettingOffsetHighCvProgrammerFacade
,SlotManager
,SprogOpsModeProgrammer
,SprogProgrammer
,SRCPProgrammer
,TamsOpsModeProgrammer
,TamsProgrammer
,TwoIndexTcsProgrammerFacade
,UhlenbrockSlotManager
,VerifyWriteProgrammerFacade
,XNetOpsModeProgrammer
,XNetProgrammer
,Z21XNetOpsModeProgrammer
,Z21XNetProgrammer
public interface Programmer extends Disposable
Provide access to the hardware DCC decoder programming capability.Programmers come in multiple types:
- Global, previously "Service Mode" or on a programming track
- Addressed, previously "Ops Mode" also known as "programming on the main"
- DCC CV programming, on service mode track or on the main
- CBUS Node Variable programmers
- LocoNet System Variable programmers
- LocoNet Op Switch programmers
- etc
You get a Programmer object from a
GlobalProgrammerManager
or anAddressedProgrammerManager
, which in turn can be located from theInstanceManager
.Starting in JMRI 3.5.5, the CV addresses are Strings for generality. The methods that use ints for CV addresses will later be deprecated.
Added possibility to supply CV value hint to the system
This file is part of JMRI.JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.
JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
Programmer.WriteConfirmMode
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
addPropertyChangeListener(java.beans.PropertyChangeListener p)
void
confirmCV(java.lang.String CV, int val, ProgListener p)
Confirm the value of a CV using the specified programming mode.java.lang.String
decodeErrorCode(int i)
default void
dispose()
Free up system resources.boolean
getCanRead()
Checks the general read capability, regardless of modeboolean
getCanRead(java.lang.String addr)
Checks the general read capability, regardless of mode, for a specific addressboolean
getCanWrite()
Checks the general write capability, regardless of modeboolean
getCanWrite(java.lang.String addr)
Checks the general write capability, regardless of mode, for a specific addressProgrammingMode
getMode()
Get the current programming modejava.util.List<ProgrammingMode>
getSupportedModes()
Get the list ofProgrammingMode
supported by this Programmer.Programmer.WriteConfirmMode
getWriteConfirmMode(java.lang.String addr)
Learn about whether the programmer does any kind of verification of write operationsdefault void
notifyProgListenerEnd(ProgListener p, int value, int status)
wrapper to callProgListener.programmingOpReply(int, int)
that verifies the specified progListener is not null.void
readCV(java.lang.String CV, ProgListener p)
Perform a CV read in the system-specific manner, and using the specified programming mode.default void
readCV(java.lang.String CV, ProgListener p, int startVal)
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.void
removePropertyChangeListener(java.beans.PropertyChangeListener p)
void
setMode(ProgrammingMode p)
Set the programmer to a particular mode.void
writeCV(java.lang.String CV, int val, ProgListener p)
Perform a CV write in the system-specific manner, and using the specified programming mode.
-
-
-
Method Detail
-
writeCV
void writeCV(java.lang.String CV, int val, ProgListener p) throws ProgrammerException
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)
- Parameters:
CV
- the CV to writeval
- the value to writep
- the listener that will be notified of the write- Throws:
ProgrammerException
- if unable to communicate
-
readCV
void readCV(java.lang.String CV, ProgListener p) throws ProgrammerException
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)
- Parameters:
CV
- the CV to readp
- the listener that will be notified of the read- Throws:
ProgrammerException
- if unable to communicate
-
readCV
default void readCV(java.lang.String CV, ProgListener p, int startVal) throws ProgrammerException
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)
- Parameters:
CV
- the CV to readp
- the listener that will be notified of the readstartVal
- a hint of what the current value might be, or 0- Throws:
ProgrammerException
- if unable to communicate
-
confirmCV
void confirmCV(java.lang.String CV, int val, ProgListener p) throws ProgrammerException
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)
- Parameters:
CV
- the CV to confirmval
- the value to confirmp
- the listener that will be notified of the confirmation- Throws:
ProgrammerException
- if unable to communicate
-
getSupportedModes
@Nonnull java.util.List<ProgrammingMode> getSupportedModes()
Get the list ofProgrammingMode
supported by this Programmer. If the order is significant, earlier modes are better.- Returns:
- the list of supported modes or an empty list
-
setMode
void setMode(ProgrammingMode p)
Set the programmer to a particular mode.Mode is a bound parameter; mode changes fire listeners.
Only modes returned by
getSupportedModes()
are supported. If an invalid mode is requested, the active mode is unchanged.- Parameters:
p
- a valid node returned bygetSupportedModes()
or null; null is ignored ifgetSupportedModes()
is not empty
-
getMode
ProgrammingMode getMode()
Get the current programming mode- Returns:
- the current mode or null if none is defined and no default mode is defined
-
getCanRead
boolean getCanRead()
Checks the general read capability, regardless of mode- Returns:
- true if the programmer is capable of reading; false otherwise
-
getCanRead
boolean getCanRead(java.lang.String addr)
Checks the general read capability, regardless of mode, for a specific address- Parameters:
addr
- the address to read- Returns:
- true if the address can be read; false otherwise
-
getCanWrite
boolean getCanWrite()
Checks the general write capability, regardless of mode- Returns:
- true if the programmer is capable of writing; false otherwise
-
getCanWrite
boolean getCanWrite(java.lang.String addr)
Checks the general write capability, regardless of mode, for a specific address- Parameters:
addr
- the address to write to- Returns:
- true if the address can be written to; false otherwise
-
getWriteConfirmMode
@Nonnull Programmer.WriteConfirmMode getWriteConfirmMode(java.lang.String addr)
Learn about whether the programmer does any kind of verification of write operations- Parameters:
addr
- A CV address to check (in case this varies with CV range) or null for any- Returns:
- The confirmation behavior that can be counted on (might be better in some cases)
-
notifyProgListenerEnd
default void notifyProgListenerEnd(ProgListener p, int value, int status)
wrapper to callProgListener.programmingOpReply(int, int)
that verifies the specified progListener is not null.- Parameters:
p
- listener to notifyvalue
- result valuestatus
- code from jmri.ProgListener
-
addPropertyChangeListener
void addPropertyChangeListener(java.beans.PropertyChangeListener p)
-
removePropertyChangeListener
void removePropertyChangeListener(java.beans.PropertyChangeListener p)
-
decodeErrorCode
@Nonnull java.lang.String decodeErrorCode(int i)
-
dispose
default void dispose()
Free up system resources. Overriding classes should be capable of this being called multiple times as per theDisposable
interface. Called when disposing of a disposable.Note there are no assurances this method will not be called multiple times against a single instance of this Disposable. It is the responsibility of this Disposable to protect itself and the application from ensuring that calling this method multiple times has no unwanted side effects.
- Specified by:
dispose
in interfaceDisposable
-
-