Source code

001package jmri.jmrix.loconet;
002
003import jmri.InstanceManager;
004import jmri.Programmer;
005import jmri.ProgrammingMode;
006import jmri.beans.PropertyChangeSupport;
007import jmri.jmrit.decoderdefn.DecoderFile;
008import jmri.jmrit.decoderdefn.DecoderIndexFile;
009import jmri.jmrit.roster.Roster;
010import jmri.jmrit.roster.RosterEntry;
011import jmri.jmrix.ProgrammingTool;
012import jmri.jmrix.loconet.lnsvf1.Lnsv1Device;
013import jmri.jmrix.loconet.lnsvf1.Lnsv1Devices;
014import jmri.jmrix.loconet.lnsvf1.Lnsv1MessageContents;
015import jmri.managers.DefaultProgrammerManager;
016//import jmri.progdebugger.ProgDebugger;
017
018import jmri.util.ThreadingUtil;
019import jmri.util.swing.JmriJOptionPane;
020
021import javax.annotation.concurrent.GuardedBy;
022import java.util.List;
023
024/**
025 * LocoNet LNSV1 Devices Manager
026 * <p>
027 * A centralized resource to help identify LocoNet "LNSV1 Format"
028 * devices and "manage" them.
029 * <p>
030 * Supports the following features:
031 *  - LNSV1 "discovery" process supported via BROADCAST call
032 *  - LNSV1 Device "destination address" change supported by writing a new value to LNSV 0 (close session next)
033 *  - LNSV1 Device "reconfigure/reset" not supported/documented
034 *  - identification of devices with conflicting "destination address"es (warning before program start)
035 *  - identification of a matching JMRI "decoder definition" for each discovered
036 *    device, if an appropriate definition exists (only 1 value is matched, checks for LNSVf1 protocol support)
037 *  - identification of matching JMRI "roster entry" which matches each
038 *    discovered device, if an appropriate roster entry exists
039 *  - ability to open a symbolic programmer for a given discovered device, if
040 *    an appropriate roster entry exists
041 *
042 * @author B. Milhaupt Copyright (c) 2020
043 * @author Egbert Broerse (c) 2021, 2025
044 */
045
046public class Lnsv1DevicesManager extends PropertyChangeSupport
047        implements LocoNetListener, jmri.Disposable {
048    private final LocoNetSystemConnectionMemo memo;
049    @GuardedBy("this")
050    private final Lnsv1Devices lnsv1Devices;
051
052    // constant for thread name, with memo prefix appended.
053    static final String ROSTER_THREAD_NAME = "rosterMatchingListLnsv1DM";
054
055    public Lnsv1DevicesManager(@javax.annotation.Nonnull LocoNetSystemConnectionMemo memo) {
056        this.memo = memo;
057        if (memo.getLnTrafficController() != null) {
058            memo.getLnTrafficController().addLocoNetListener(~0, this);
059        } else {
060            log.error("No LocoNet connection available, this tool cannot function"); // NOI18N
061        }
062        synchronized (this) {
063            lnsv1Devices = new Lnsv1Devices();
064        }
065    }
066
067    public synchronized Lnsv1Devices getDeviceList() {
068        return lnsv1Devices;
069    }
070
071    public synchronized int getDeviceCount() {
072        return lnsv1Devices.size();
073    }
074
075    public void clearDevicesList() {
076        synchronized (this) {
077            lnsv1Devices.removeAllDevices();
078        }
079        jmri.util.ThreadingUtil.runOnLayoutEventually( ()-> firePropertyChange("DeviceListChanged", true, false));
080    }
081
082    /**
083     * Extract module information from a LNSVf1 READ_ONE REPLY message.
084     * If not already in the lnsv1Devices list, try to find a matching decoder definition (by address number and programming mode)
085     * and add it. Skip if already in the list.
086     *
087     * @param m The received LocoNet message. Note that this same object may
088     *            be presented to multiple users. It should not be modified
089     *            here.
090     */
091    @Override
092    public void message(LocoNetMessage m) {
093        if (Lnsv1MessageContents.isSupportedSv1Message(m)) {
094            if ((Lnsv1MessageContents.extractMessageType(m) == Lnsv1MessageContents.Sv1Command.SV1_READ) &&
095                    (Lnsv1MessageContents.extractMessageVersion(m) > 0)) { // which marks replies from devices
096                // it's an LNSV1 Read_One Reply message, decode contents:
097                Lnsv1MessageContents contents = new Lnsv1MessageContents(m);
098                int vrs = contents.getVersionNum();
099                int addrL = contents.getSrcL();
100                int subAddr = contents.getSubAddress();
101                int sv = contents.getSvNum();
102                int val = contents.getSvValue();
103                log.debug("Lnsv1DevicesManager got read reply: vrs:{}, address:{}/{} cv:{} val:{}", vrs, addrL, subAddr, sv, val);
104
105                synchronized (this) {
106                    if (lnsv1Devices.addDevice(new Lnsv1Device(addrL, subAddr, sv, val, "", "", vrs))) {
107                        log.debug("new Lnsv1Device added to table");
108                        // Annotate the discovered device LNSV1 data based on address
109                        for (int i = 0; i < lnsv1Devices.size(); ++i) { // find the added item
110                            Lnsv1Device dev = lnsv1Devices.getDevice(i);
111                            if ((dev.getDestAddrLow() == addrL) && (dev.getDestAddrHigh() == subAddr)) {
112                                // Try to find a roster entry which matches the device characteristics
113                                log.debug("Looking for adr {} in Roster", dev.getDestAddr());
114
115                                // threadUtil off GUI for Roster reading decoderfiles cf. LncvDevicesManager
116                                ThreadingUtil.newThread(() -> {
117                                    List<RosterEntry> rl;
118                                    try {
119                                        // requires nonnull default for jmri.jmrit.roster.RosterConfigManager
120                                        rl = Roster.getDefault().getEntriesMatchingCriteria(
121                                                Integer.toString(dev.getDestAddr()), // composite DCC address
122                                                null, null, null,
123                                                null); // TODO filter on progMode LNSV1 only on new roster entries
124                                        log.debug("Lnsv1DeviceManager found {} matches in Roster", rl.size());
125                                        if (rl.isEmpty()) {
126                                            log.debug("No corresponding roster entry found");
127                                        } else if (rl.size() == 1) {
128                                            log.debug("Matching roster entry found");
129                                            dev.setRosterEntry(rl.get(0)); // link this device to the entry
130                                            String title = rl.get(0).getDecoderModel() + " (" + rl.get(0).getDecoderFamily() + ")";
131                                            // fileFromTitle() matches by model + " (" + family + ")"
132                                            DecoderFile decoderFile = InstanceManager.getDefault(DecoderIndexFile.class).fileFromTitle(title);
133                                            if (decoderFile != null) {
134                                                // TODO check for LNSV1 mode
135                                                dev.setDecoderFile(decoderFile); // link to decoderFile (to check programming mode from table)
136                                                log.debug("Attached a decoderfile");
137                                            } else {
138                                                log.warn("Could not attach decoderfile {} to entry", rl.get(0).getFileName());
139                                            }
140                                        } else { // matches > 1
141                                            JmriJOptionPane.showMessageDialog(null,
142                                                    Bundle.getMessage("WarnMultipleLnsv1ModsFound", rl.size(), addrL, subAddr),
143                                                    Bundle.getMessage("WarningTitle"), JmriJOptionPane.WARNING_MESSAGE);
144                                            log.info("Found multiple matching LNSV1 roster entries. " + "Cannot associate any one to this device.");
145                                        }
146
147                                    } catch (Exception e) {
148                                        log.error("Error creating Roster.matchingList: {}", e.getMessage());
149                                    }
150                                }, ROSTER_THREAD_NAME + memo.getSystemPrefix()).start();
151                                // this will block until the thread completes, either by finishing or by being cancelled
152
153                                // notify listeners of pertinent change to device list
154                                firePropertyChange("DeviceListChanged", true, false);
155                            }
156                        }
157                    } else {
158                        log.debug("LNSV1 device was already in list");
159                    }
160                }
161            } else {
162                log.debug("LNSV1 message not a READ REPLY [{}]", m);
163            }
164        } else {
165            log.debug("LNSV1 message not recognized");
166        }
167    }
168
169    public synchronized Lnsv1Device getDevice(int vrs, int addr) {
170        for (int i = 0; i < lnsv1Devices.size(); ++ i) {
171            Lnsv1Device dev = lnsv1Devices.getDevice(i);
172            if ((dev.getSwVersion() == vrs) && (dev.getDestAddr() == addr)) {
173                return dev;
174            }
175        }
176        return null;
177    }
178
179    public ProgrammingResult prepareForSymbolicProgrammer(Lnsv1Device dev, ProgrammingTool t) {
180        synchronized(this) {
181            if (lnsv1Devices.isDeviceExistant(dev) < 0) {
182                return ProgrammingResult.FAIL_NO_SUCH_DEVICE;
183            }
184            int destAddr = dev.getDestAddr();
185            if (destAddr == 0) {
186                return ProgrammingResult.FAIL_DESTINATION_ADDRESS_IS_ZERO;
187            }
188            int deviceCount = 0;
189            for (Lnsv1Device d : lnsv1Devices.getDevices()) {
190                if (destAddr == d.getDestAddr()) {
191                    deviceCount++;
192                }
193            }
194            log.debug("prepareForSymbolicProgrammer found {} matches", deviceCount);
195            if (deviceCount > 1) {
196                return ProgrammingResult.FAIL_MULTIPLE_DEVICES_SAME_DESTINATION_ADDRESS;
197            }
198        }
199
200        if ((dev.getRosterName() == null) || (dev.getRosterName().isEmpty())) {
201            return ProgrammingResult.FAIL_NO_MATCHING_ROSTER_ENTRY;
202        }
203
204        // check if roster entry still present in Roster
205        RosterEntry re = Roster.getDefault().entryFromTitle(dev.getRosterName());
206        if (re == null) {
207            log.warn("Could not open LNSV1 Programmer because {} not found in Roster. Removed from device",
208                    dev.getRosterName());
209            dev.setRosterEntry(null);
210            jmri.util.ThreadingUtil.runOnLayoutEventually( ()-> firePropertyChange("DeviceListChanged", true, false));
211            return ProgrammingResult.FAIL_NO_MATCHING_ROSTER_ENTRY;
212        }
213        String name = re.getId();
214
215        DefaultProgrammerManager pm = memo.getProgrammerManager();
216        if (pm == null) {
217            return ProgrammingResult.FAIL_NO_APPROPRIATE_PROGRAMMER;
218        }
219        Programmer p = pm.getAddressedProgrammer(false, dev.getDestAddr());
220        if (p == null) {
221            return ProgrammingResult.FAIL_NO_ADDRESSED_PROGRAMMER;
222        }
223
224        //if (p.getClass() != ProgDebugger.class) { // Debug in Simulator
225            // ProgDebugger is used for LocoNet HexFile Sim; uncommenting above line allows testing of LNSV1 Tool
226            if (!p.getSupportedModes().contains(LnProgrammerManager.LOCONETOPSBOARD)) {
227                return ProgrammingResult.FAIL_NO_LNSV1_PROGRAMMER;
228            }
229            p.setMode(LnProgrammerManager.LOCONETSV1MODE);
230            ProgrammingMode prgMode = p.getMode();
231            if (!prgMode.equals(LnProgrammerManager.LOCONETSV1MODE)) {
232                return ProgrammingResult.FAIL_NO_LNSV1_PROGRAMMER;
233            }
234        //}
235
236        t.openPaneOpsProgFrame(re, name, "programmers/Comprehensive.xml", p); // NOI18N
237        return ProgrammingResult.SUCCESS_PROGRAMMER_OPENED;
238    }
239
240    @Override
241    public void dispose(){
242        if (memo.getLnTrafficController() != null) {
243            memo.getLnTrafficController().removeLocoNetListener(~0, this);
244        }
245    }
246
247    public enum ProgrammingResult {
248        SUCCESS_PROGRAMMER_OPENED,
249        FAIL_NO_SUCH_DEVICE,
250        FAIL_NO_APPROPRIATE_PROGRAMMER,
251        FAIL_NO_MATCHING_ROSTER_ENTRY,
252        FAIL_DESTINATION_ADDRESS_IS_ZERO,
253        FAIL_MULTIPLE_DEVICES_SAME_DESTINATION_ADDRESS,
254        FAIL_NO_ADDRESSED_PROGRAMMER,
255        FAIL_NO_LNSV1_PROGRAMMER
256    }
257
258    private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(Lnsv1DevicesManager.class);
259
260}