001package jmri;
002
003/**
004 * Represent a digital I/O on the layout.
005 * 
006 * @author Daniel Bergqvist Copyright (C) 2018
007 */
008public interface DigitalIO extends NamedBean {
009
010    /**
011     * State value indicating output is on.
012     */
013    static final int ON = 0x02;
014
015    /**
016     * State value indicating output is off.
017     */
018    static final int OFF = 0x04;
019
020    /**
021     * Show whether state is stable.
022     * 
023     * For turnouts, a consistent state is one you can safely run trains over.
024     * For lights, it's a state which is either on or off, not in between.
025     *
026     * @return true if state is valid and the known state is the same as commanded
027     */
028    boolean isConsistentState();
029
030    /**
031     * Change the commanded state, which results in the relevant command(s)
032     * being sent to the hardware. The exception is thrown if there are problems
033     * communicating with the layout hardware.
034     *
035     * @param s the desired state
036     */
037    @InvokeOnLayoutThread
038    void setCommandedState(int s);
039
040    /**
041     * Query the commanded state. This is a bound parameter, so you can also
042     * register a listener to be informed of changes.
043     *
044     * @return the commanded state
045     */
046    int getCommandedState();
047    
048    /**
049     * Query the known state. This is a bound parameter, so you can also
050     * register a listener to be informed of changes. A result is always
051     * returned; if no other feedback method is available, the commanded state
052     * will be used.
053     *
054     * @return the known state
055     */
056    int getKnownState();
057
058    /**
059     * Request an update from the layout soft/hardware. May not even happen, and
060     * if it does it will happen later; listen for the result.
061     */
062    @InvokeOnLayoutThread
063    void requestUpdateFromLayout();
064    
065}