001package jmri;
002
003import java.util.List;
004
005/**
006 * RailCom represents a RailCom enabled decoder that might be fitted to a
007 * specific piece of rolling stock to uniquely identify it.<br>
008 * RailCom is a registered trademark of Lenz GmbH.
009 * <p>
010 * This implementation of RailCom is an extension of @see IdTag and holds the
011 * additional information that can be supplied by the decoder as defined in
012 * RP-9.3.2
013 * <p>
014 * This file is part of JMRI.
015 * <p>
016 * JMRI is free software; you can redistribute it and/or modify it under the
017 * terms of version 2 of the GNU General Public License as published by the Free
018 * Software Foundation. See the "COPYING" file for a copy of this license.
019 * <p>
020 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
021 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
022 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
023 *
024 * @author Kevin Dickerson Copyright (C) 2012
025 * @author Bob Jacobsen    Copyright (C) 2026
026 * @since 2.99.4
027 */
028public interface RailCom extends AddressedIdTag {
029
030    /**
031     * An enum representing the type of address reported
032     * in a RailCom message.
033     */
034    public enum AddressType {
035        /**
036         * Represemts that we do not know the address type of the
037         * decoder. This is the initial state of a newly created object before.
038         */
039        NO_ADDRESS,
040        
041        /**
042         * Represents that the address type reported back is Short.
043         */
044        SHORT_ADDRESS,
045        
046        /**
047         * Represents that the address type reported back is Long.
048         */
049        LONG_ADDRESS,
050        
051        /**
052         * Represents that the address type reported back is part of a
053         * Consist.
054         */
055        CONSIST_ADDRESS
056    }
057
058    /**
059     * An enum representing the decoder orientation reported
060     * in a RailCom message. The wiring of the RailCom detection hardware
061     * defines the correspondence between the A and B orientations
062     * and the facing direction on the track.
063     */
064    public enum Orientation {
065        UNKNOWN(0x00),      // historical values should they be needed in scripts
066        ORIENTA(0x10),
067        ORIENTB(0x20);
068        
069        private final int type;
070        Orientation(int type) {
071            this.type = type;
072        }
073        
074        public int getValue() { return type; }
075        
076        public static Orientation getFromInt( int type ) {
077            for (Orientation e : values() ) {
078                if (e.type == type) return e;
079            }
080            return UNKNOWN; // if no match
081        }
082    }
083
084    /**
085     * Method for a RailCom Reader to set the orientation reported back from a
086     * device
087     *
088     * @param type the orientation to set
089     */
090    void setOrientation(Orientation type);
091
092    /**
093     * Gets the Orientation of the Rail Com device on the track
094     *
095     * @return current orientation
096     */
097    Orientation getOrientation();
098
099    /**
100     * Method for a RailCom Reader to set the Actual speed reported back from a
101     * device
102     *
103     * @param actualSpeed the speed
104     */
105    void setActualSpeed(int actualSpeed);
106
107    /**
108     * Gets the actual speed reported by the RailCom device as a representation
109     * 128 speed steps
110     *
111     * @return -1 if not set.
112     */
113    int getActualSpeed();
114
115    /**
116     * Method for a RailCom Reader to set the Actual Load back from a device.
117     *
118     * @param actualLoad the load
119     */
120    void setActualLoad(int actualLoad);
121
122    /**
123     * Gets the actual load reported by decoder the RailCom device.
124     *
125     * @return -1 if not set.
126     */
127    int getActualLoad();
128
129    /**
130     * Method for a RailCom Reader to set the actual temperate reported back
131     * from a device.
132     *
133     * @param actualTemp the temperature
134     */
135    void setActualTemperature(int actualTemp);
136
137    /**
138     * Gets the actual temperate reported by the RailCom device. Location is
139     * configured in CV876 (RP.9.3.2)
140     *
141     * @return -1 if not set.
142     */
143    int getActualTemperature();
144
145    /**
146     * Method for a RailCom Reader to set the fuel level reported back from a
147     * device.
148     *
149     * @param fuelLevel the fuel level
150     */
151    void setFuelLevel(int fuelLevel);
152
153    /**
154     * Method for a RailCom Reader to set the water level reported back from a
155     * device.
156     *
157     * @param waterLevel the water level
158     */
159    void setWaterLevel(int waterLevel);
160
161    /**
162     * Gets the remaining fuel level as a % Fuel level CV879 (RP.9.3.2)
163     *
164     * @return -1 if not set.
165     */
166    int getFuelLevel();
167
168    /**
169     * Gets the remaining fuel level as a % Water level CV878 (RP.9.3.2)
170     *
171     * @return -1 if not set.
172     */
173    int getWaterLevel();
174
175    /**
176     * Method for a RailCom Reader to set the location reported back from a
177     * device.
178     *
179     * @param location the location
180     */
181    void setLocation(int location);
182
183    /**
184     * Gets the Last Location that the RailCom device was identified in Location
185     * is configured in CV876 (RP.9.3.2)
186     *
187     * @return -1 if not set.
188     */
189    int getLocation();
190
191    /**
192     * Method for a RailCom Reader to set the routing number reported back from
193     * a device.
194     *
195     * @param routingno the routing number
196     */
197    void setRoutingNo(int routingno);
198
199    /**
200     * Gets the routing number that the RailCom device wishes to travel. Route
201     * Number is configured in CV874 (RP.9.3.2)
202     *
203     * @return -1 if not set.
204     */
205    int getRoutingNo();
206
207    /**
208     * Gets the value of a CV reported back from the RailCom device.
209     *
210     * @param cv CV number that the value relates to.
211     * @return the value of the CV, or 0 if none has yet been collected
212     */
213    int getCV(int cv);
214
215    /**
216     * Sets the value of a CV reported back from the decoder.
217     *
218     * @param cv    CV number that the value relates to.
219     * @param value Value of the CV
220     */
221    void setCV(int cv, int value);
222
223    /**
224     * Set the CV number of the next expected value to be returned in a RailCom
225     * Packet.
226     *
227     * @param cv the expected CV
228     */
229    void setExpectedCv(int cv);
230
231    /**
232     * Get the expected CV to be returned in a RailCom Packet.
233     *
234     * @return the expected CV
235     */
236    int getExpectedCv();
237
238    /**
239     * Set the value of the CV that has been read from the RailCom packet.
240     *
241     * @param value the CV value
242     */
243    void setCvValue(int value);
244
245    /**
246     * Get a list of the CVs last seen for this RailCom device.
247     *
248     * @return a list of CVs
249     */
250    List<Integer> getCVList();
251
252}