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    // The type of address reported in a RailCom message
031    // is encoded using the LocoAddress.Protocol enum
032
033    /**
034     * Set the numeric DCC address reported back
035     */
036    void setDccAddress(LocoAddress address);
037    
038    /**
039     * Get the DCC address 
040     * @return the number part (not mode) of the reported DCC address or -1
041     */
042    LocoAddress getDccAddress();
043
044    /**
045     * An enum representing the decoder orientation reported
046     * in a RailCom message. The wiring of the RailCom detection hardware
047     * defines the correspondence between the A and B orientations
048     * and the facing direction on the track.
049     */
050    public enum Orientation {
051        UNKNOWN(0x00),      // historical values should they be needed in scripts
052        EAST(0x10),         // was ORIENTA
053        WEST(0x20);         // was ORIENTB
054        
055        private final int type;
056        Orientation(int type) {
057            this.type = type;
058        }
059        
060        public int getValue() { return type; }
061        
062        public static Orientation getFromInt( int type ) {
063            for (Orientation e : values() ) {
064                if (e.type == type) return e;
065            }
066            return UNKNOWN; // if no match
067        }
068    }
069
070    /**
071     * An enum representing the decoder direction of motion
072     * reported in a RailCom message.
073     */
074    public enum Direction {
075        FORWARD,
076        BACKWARD,
077        UNKNOWN
078    }
079    
080    /**
081     * An enum representing whether the decoder reports moving
082     * in a RailCom message.
083     */
084    public enum Motion {
085        MOVING,
086        STATIONARY,
087        UNKNOWN
088    }
089    
090    /**
091     * An enum representing the DCC track signal quality  reported in
092     * in a RailCom message.
093     */
094    public enum QoS {
095        GOOD,
096        POOR,
097        UNKNOWN
098    }
099
100    /**
101     * Set the orientation reported back from a
102     * device
103     *
104     * @param type the orientation to set
105     */
106    void setOrientation(Orientation type);
107
108    /**
109     * Gets the Orientation of the Rail Com device on the track
110     *
111     * @return current orientation
112     */
113    Orientation getOrientation();
114
115    /**
116     * Set the direction of motion reported back from a
117     * device
118     *
119     * @param type the direction to set
120     */
121    void setDirection(Direction type);
122
123    /**
124     * Gets the direction of motion of the Rail Com device on the track
125     *
126     * @return current direction
127     */
128    Direction getDirection();
129
130    /**
131     * Set the motion state reported back from a
132     * device
133     *
134     * @param type the motion state to set
135     */
136    void setMotion(Motion type);
137
138    /**
139     * Gets the motion  state of the Rail Com device on the track
140     *
141     * @return current motion state
142     */
143    Motion getMotion();
144
145    /**
146     * Set the Quality of Service state reported back from a
147     * device
148     *
149     * @param type the QoS state to set
150     */
151    void setQoS(QoS type);
152
153    /**
154     * Gets the Quality of Service state of the Rail Com device on the track
155     *
156     * @return current QoS state
157     */
158    QoS getQoS();
159
160    /**
161     * Method for a RailCom Reader to set the Actual speed reported back from a
162     * device. -1 if the speed is unavailable or unknown.
163     *
164     * @param actualSpeed the speed.
165     */
166    void setActualSpeed(int actualSpeed);
167
168    /**
169     * Gets the actual speed reported by the RailCom device as a representation
170     * 128 speed steps
171     *
172     * @return -1 if not set.
173     */
174    int getActualSpeed();
175
176    /**
177     * Method for a RailCom Reader to set the Actual Load back from a device.
178     *
179     * @param actualLoad the load
180     */
181    void setActualLoad(int actualLoad);
182
183    /**
184     * Gets the actual load reported by decoder the RailCom device.
185     *
186     * @return -1 if not set.
187     */
188    int getActualLoad();
189
190    /**
191     * Method for a RailCom Reader to set the actual temperate reported back
192     * from a device.
193     *
194     * @param actualTemp the temperature
195     */
196    void setActualTemperature(int actualTemp);
197
198    /**
199     * Gets the actual temperate reported by the RailCom device. Location is
200     * configured in CV876 (RP.9.3.2)
201     *
202     * @return -1 if not set.
203     */
204    int getActualTemperature();
205
206    /**
207     * Method for a RailCom Reader to set the fuel level reported back from a
208     * device.
209     *
210     * @param fuelLevel the fuel level
211     */
212    void setFuelLevel(int fuelLevel);
213
214    /**
215     * Gets the remaining fuel level as a % Fuel level CV879 (RP.9.3.2)
216     *
217     * @return -1 if not set.
218     */
219    int getFuelLevel();
220
221    /**
222     * Method for a RailCom Reader to set the water level reported back from a
223     * device.
224     *
225     * @param waterLevel the water level
226     */
227    void setWaterLevel(int waterLevel);
228
229    /**
230     * Gets the remaining fuel level as a % Water level CV878 (RP.9.3.2)
231     *
232     * @return -1 if not set.
233     */
234    int getWaterLevel();
235
236    /**
237     * Method for a RailCom Reader to set the location reported back from a
238     * device.
239     *
240     * @param location the location
241     */
242    void setLocation(int location);
243
244    /**
245     * Gets the Last Location that the RailCom device was identified in Location
246     * is configured in CV876 (RP.9.3.2)
247     *
248     * @return -1 if not set.
249     */
250    int getLocation();
251
252    /**
253     * Method for a RailCom Reader to set the routing number reported back from
254     * a device.
255     *
256     * @param routingno the routing number
257     */
258    void setRoutingNo(int routingno);
259
260    /**
261     * Gets the routing number that the RailCom device wishes to travel. Route
262     * Number is configured in CV874 (RP.9.3.2)
263     *
264     * @return -1 if not set.
265     */
266    int getRoutingNo();
267
268    /**
269     * Gets the value of a CV reported back from the RailCom device.
270     *
271     * @param cv CV number that the value relates to.
272     * @return the value of the CV, or 0 if none has yet been collected
273     */
274    int getCV(int cv);
275
276    /**
277     * Sets the value of a CV reported back from the decoder.
278     *
279     * @param cv    CV number that the value relates to.
280     * @param value Value of the CV
281     */
282    void setCV(int cv, int value);
283
284    /**
285     * Set the CV number of the next expected value to be returned in a RailCom
286     * Packet.
287     *
288     * @param cv the expected CV
289     */
290    void setExpectedCv(int cv);
291
292    /**
293     * Get the expected CV to be returned in a RailCom Packet.
294     *
295     * @return the expected CV
296     */
297    int getExpectedCv();
298
299    /**
300     * Set the value of the CV that has been read from the RailCom packet.
301     *
302     * @param value the CV value
303     */
304    void setCvValue(int value);
305
306    /**
307     * Get a list of the CVs last seen for this RailCom device.
308     *
309     * @return a list of CVs
310     */
311    List<Integer> getCVList();
312
313}