JMRI: Adding A New System

We list the files that are modified and created in the order they were done in this case; other orders may also work, and you might not need to do all these.

In this particular case, we started by copying an existing system implementation (SECSI). This effects how we ordered this, and made the basic process move pretty quickly.

Duplicate an existing system

Create a duplicate file tree

Using whatever tool that useful to you, duplicate the src/jmri/jmrix subtree corresponding to the existing system you want to copy.

Clean out the CVS directories

It is absolutely critical that you remove the CVS subdirectories from the duplicate directory tree you just created. If you don't do this, you will have difficult-to-diagnose problems when you try to commit this to CVS.

To check that you've done that, use a command like:
find . -name CVS -print

Change the package name information

Using your favorite editor, change all the package names in the new files to their new location. In this example, that was a bulk replace of "jmri.jmrix.secsi" with "jmri.jmrix.powerline".

At this point, make sure you can compile. This code isn't consistent yet, but it should compile.

Check copyright dates

Because you've copied a system that might not have been touched for a while, go through and add the current year (and if need be, your name) to the copyright notices in all the files.

Create CVS structure

In this step, we put the basic CVS structure in place.

• Add all the directories you've created to CVS. In the example, this was:
  cvs add powerline powerline/serialdriver powerline/serialmon
cvs add powerline/configurexml powerline/serialdriver/configurexml
• Add all the COPYING files:
  cvs add powerline/COPYING powerline/*/COPYING powerline/*/*/COPYING
• Add all the .cvsignore files:
  cvs add powerline/.cvsignore powerline/*/.cvsignore powerline/*/*/.cvsignore
• Finally, commmit those files (but only those files):
  cvs commit -m"usual file" powerline

At this point, make sure you can compile.

Do Basic Migration

Migrate names

Using your favorite editor, change all occurances of the old system name into the new one.

bbedit `grep -irl secsi powerline/`

Then search for and replace, perhaps not literally, all the occurances.

At this point, make sure you can compile.

Create Basic Tests

Duplicate directory

Following the steps above, duplicate the directory for the previous systems tests, creating a new directory in test/jmri/jmrix to contain the tests. Remove the CVS subdirectories, change the package names, check the copyright dates, create the CVS structure, and migrate the names.

At this point, make sure you can compile both the main code (which wasn't changed in this step) and the tests.

You should also be able to successfully run the tests in your new system (although they were created for the old system's functionality): ant tests &&./runtest.csh jmri.jmrix.powerline.SerialTest

Connect Basics to Rest of System

Connect to configuration menus

Edit the jmri/jmrix/ActiveSystemsMenu.java file (two places), src/jmri/jmrix/JmrixConfigPane.java (one place) and src/jmri/jmrix/SystemsMenu.java (one place) files to add the new system.

Don't commit this to CVS yet!

At this point, make sure you can compile and run DecoderPro, and that your new system appears in the preferences panel.

Connect to test tree

Edit the test/jmri/jmrix/JmrixTest.java file to invoke your new system tests.

Don't commit this to CVS yet!

At this point, when you "ant alltest", your new system's test should be run.

Migrate to Basic Functionality

Update connection options

Speeds, etc, in powerline/serialdriver/SerialDriverAdapter.java.

Get send/receive communications working

The first step is to get communications working so that you can send a message from the "Send Command" window, and see it and the response in the "Monitor" window.

Make It Easy to Use

Add Possible Startup Items

Edit src/apps/ActionListBundle.properties to add appropriate items.

Complete the documentation

Create The Help Tree

Start by duplicating, then edit, don't forget to update the index.

You'll also have to change the locations on the various frames

ant javadoc

Create the JavaDocs, and fix any new (or old) problems.

Add the system to the "hardware" web pages

Edit help/en/html/hardware/index.shtml