Source code

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