001package jmri; 002 003import java.util.EnumSet; 004 005/** 006 * DCC Speed Step Mode. 007 * 008 * <hr> 009 * This file is part of JMRI. 010 * <p> 011 * JMRI is free software; you can redistribute it and/or modify it under the 012 * terms of version 2 of the GNU General Public License as published by the Free 013 * Software Foundation. See the "COPYING" file for a copy of this license. 014 * <p> 015 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 016 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 017 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 018 * 019 * @author Austin Hendrix Copyright (C) 2019 020 */ 021@javax.annotation.concurrent.Immutable 022public enum SpeedStepMode { 023 // NOTE: keep these up to date with xml/schema/locomotive-config.xsd 024 UNKNOWN("unknown", 1, 0.0f, "SpeedStepUnknown"), 025 // NMRA DCC standard speed step modes. 026 NMRA_DCC_128("128", 126, "SpeedStep128"), // Remember there are only 126 non-stop values in 128 speed. 027 NMRA_DCC_28("28", 28, "SpeedStep28"), 028 NMRA_DCC_27("27", 27, "SpeedStep27"), 029 NMRA_DCC_14("14", 14, "SpeedStep14"), 030 // Non-DCC speed step modes. 031 MOTOROLA_28("motorola_28", 28, "SpeedStep28Motorola"), // Motorola 28 speed step mode. 032 TMCC_32("tmcc_32", 32, "SpeedStep32TMCC"), // Lionel TMCC 32 speed step mode. 033 TMCC_200("tmcc_200", 200, "SpeedStep200TMCC"), // Lionel TMCC Legacy 200 speed step mode. 034 INCREMENTAL("incremental", 1, 1.0f, "SpeedStepIncremental"); 035 036 SpeedStepMode(String name, int numSteps, String description) { 037 this(name, numSteps, 1.0f / numSteps, description); 038 } 039 040 SpeedStepMode(String name, int numSteps, float increment, String description) { 041 this.name = name; 042 this.numSteps = numSteps; 043 this.increment = increment; 044 this.description = Bundle.getMessage(description); 045 } 046 047 public final String name; 048 049 /** 050 * The Number of steps, e.g. 126 for DCC 128 051 */ 052 public final int numSteps; 053 054 /** 055 * The increment between steps, e.g. 1 / 126 for DCC 128 056 */ 057 public final float increment; 058 public final String description; 059 060 /** 061 * Get a locale friendly Step Mode Description. 062 * For just "128" use name() 063 * @return e.g. "128 SS" 064 */ 065 @Override 066 public String toString() { 067 return description; 068 } 069 070 /** 071 * Convert a human-readable string to a DCC speed step mode. 072 * 073 * @param name string version of speed step mode; example "128" 074 * @return matching SpeedStepMode 075 * @throws IllegalArgumentException if name does not correspond to a valid speed step mode. 076 */ 077 static public SpeedStepMode getByName(String name) { 078 for (SpeedStepMode s : SpeedStepMode.values()) { 079 if (s.name.equals(name)) { 080 return s; 081 } 082 } 083 throw new IllegalArgumentException("Invalid speed step mode: " + name); 084 } 085 086 /** 087 * Convert a localized name string to a DCC speed step mode. 088 * 089 * @param name localized string version of speed step mode; example "128" 090 * @return matching SpeedStepMode 091 * @throws IllegalArgumentException if name does not correspond to a valid speed step mode. 092 */ 093 static public SpeedStepMode getByDescription(String name) { 094 for (SpeedStepMode s : SpeedStepMode.values()) { 095 if (s.description.equals(name)) { 096 return s; 097 } 098 } 099 throw new IllegalArgumentException("Invalid speed step mode: " + name); 100 } 101 102 static public EnumSet<SpeedStepMode> getCompatibleModes( 103 EnumSet<SpeedStepMode> command_station_modes, 104 EnumSet<SpeedStepMode> decoder_modes) { 105 EnumSet<SpeedStepMode> result = command_station_modes.clone(); 106 result.retainAll(decoder_modes); 107 return result; 108 } 109 110 static public SpeedStepMode bestCompatibleMode( 111 EnumSet<SpeedStepMode> command_station_modes, 112 EnumSet<SpeedStepMode> decoder_modes) { 113 EnumSet<SpeedStepMode> result = getCompatibleModes(command_station_modes, decoder_modes); 114 return bestMode(result); 115 } 116 117 static public SpeedStepMode bestMode(EnumSet<SpeedStepMode> modes) { 118 if(modes.contains(NMRA_DCC_128)) { 119 return NMRA_DCC_128; 120 } else if(modes.contains(TMCC_32)) { 121 return TMCC_32; 122 } else if(modes.contains(NMRA_DCC_28)) { 123 return NMRA_DCC_28; 124 } else if(modes.contains(MOTOROLA_28)) { 125 return MOTOROLA_28; 126 } else if(modes.contains(NMRA_DCC_27)) { 127 return NMRA_DCC_27; 128 } else if(modes.contains(NMRA_DCC_14)) { 129 return NMRA_DCC_14; 130 } 131 return UNKNOWN; 132 } 133 134 static public EnumSet<SpeedStepMode> getCompatibleModesForProtocol(LocoAddress.Protocol protocol) { 135 switch (protocol) { 136 case DCC: 137 case DCC_LONG: 138 case DCC_SHORT: 139 return EnumSet.of( 140 // NMRA Speed step modes. 141 SpeedStepMode.NMRA_DCC_128, 142 SpeedStepMode.NMRA_DCC_28, 143 SpeedStepMode.NMRA_DCC_27, 144 SpeedStepMode.NMRA_DCC_14, 145 // Incremental speed step mode, used by LENZ XPA 146 // XpressNet Phone Adapter. 147 SpeedStepMode.INCREMENTAL, 148 // TMCC mode, since some NMRA decoder models are used 149 // for TMCC locomotives. 150 SpeedStepMode.TMCC_32); 151 case MFX: 152 return EnumSet.of( 153 // NMRA Speed step modes. 154 SpeedStepMode.NMRA_DCC_128, 155 SpeedStepMode.NMRA_DCC_28, 156 SpeedStepMode.NMRA_DCC_27, 157 SpeedStepMode.NMRA_DCC_14, 158 // Incremental speed step mode, used by LENZ XPA 159 // XpressNet Phone Adapter. 160 SpeedStepMode.INCREMENTAL, 161 // MFX decoders also support Motorola speed step mode. 162 SpeedStepMode.MOTOROLA_28); 163 case MOTOROLA: 164 return EnumSet.of(SpeedStepMode.MOTOROLA_28); 165 case SELECTRIX: 166 case M4: 167 case OPENLCB: 168 case LGB: 169 // No compatible speed step modes for these protocols. 170 // NOTE: these protocols only appear to be used in conjunction 171 // with ECOS. 172 break; 173 default: 174 // Unhandled case; no compatible speed step mode. 175 break; 176 } 177 return EnumSet.noneOf(SpeedStepMode.class); 178 } 179}