TCPmaker : Visual Tour    Changing Your Layout and Regenerating Code  

Page 1


Both TCPmaker and its sister product, HIDmaker, work by generating source code that we expect you to modify.

People ask us, from time to time, what they should do if they get reasonably far down the development path, to the point where they have modified the generated code, and suddenly realize that they need to add another variable and re-generate code.

What happens to the modifications they have already added to the as-generated code? People ask us:

  • "Does your product parse my modified code and add new generated code around it?"
    • [Answer: No, this would add greatly to the complexity and cost of our products.]
  • "Are my code additions overwritten, and therefore lost?" 
    • [Answer: No, of course not!]
  • "If not, do I have to type in those code modifications all over again, by hand?" 
    • [Answer: Happily, NO!]

 As this tutorial explains in detail, TCPmaker and HIDmaker both save up to 10 previous versions of key files of your generated source code, so your modifications to this code are not lost. 

Getting your code modifications into the latest version of regenerated source code can be done simply, either by copy and paste operations, or very quickly with a low cost differencing tool such as the exquisite Beyond Compare product by Scooter Software at www.scootersoftware.com.  (The standard version of Beyond Compare costs $30 at the time of this writing, and they offer a 30-day free trial.) 

As we will demonstrate in this tutorial, Beyond Compare is so powerful that you can copy the changes into the re-generated code of your project in a matter of 5 to 15 minutes, with complete accuracy.





Page 2


The most common reason for doing this is to enhance an existing project.

If you decide, after having modified your generated source code, that you want to add more controls or variables to your TCPmaker project, then it is beyond doubt that the safest and best way to do that is to load your existing project into TCPmaker, make your changes, and generate source code all over again.

We will actually go through that process in this tutorial, starting with a working project which has been modified by adding and debugging "real I/O" code. 

We will then load the existing project file into TCPmaker to add a few more controls and variables.  We'll show you which files get saved (hint: these are the ones you are most likely to have customized), and which files just get overwritten (hint: these are the files you are not at all likely to have modified yourself).





Page 3


There is also another alternative that you can try.

Suppose you want to make a new project that is based on a previous project, but you want to leave your previous project unchanged.  You might do this if you are developing an new version of your product, and you still want to keep the source code of the previous product version intact, for maintenance purposes. You might also do something like this if you want to make a second version of your project, with a completely different appearance for your TCPmaker layout: sort of like giving your project a new "skin."

To do this, you can copy some or all of the TCPmaker project files to a clean new directory, and generate new source code for your new project in that new directory. Once you have generated source code in the new directory, you can quickly copy the modifications from files in the old version to files in the new version.

We'll show an example of doing something like that, i.e. making a new project that is based on a previous one, as the subject of our next tutorial.  But you need to complete this present tutorial first.  So, let's go!





Page 4


For our first example, we'll take an "earlier version" of the SmPx8 example project in your TCPmaker Pro installation.  For brevity, we'll only concern ourselves with the C18 code of our earlier project, but the same principles can be applied to code generated for any of our supported compilers.

The screen shot below shows this earlier version running on the Microchip PICDEM .net2 demo board.  (We have turned the pot a few times to make a curve on the Pl plotter control on the PC browser screen.)

  • Notice that this layout has only 3 LED indicators connected to the switches on the demo board: the demo board has 4 switches, so we ought to add another Ld control.
  • Similarly, we'd like to add another Pb pushbotton on our browser display, to light up one more of the LEDs on the demo board.
  • We'd also like to reduce the size of the spinning Microchip logo, so it is less obtrusive and does not cover up the lower right corner of the Pl plotter control on the screen.

 

  Click on the image for page view.




Page 5


To make these changes, we'll start TCPmaker, and we'll load our existing project. There are several ways to do this.

If, as in this case, you have worked on this particular project recently, it will appear in the Most Recently Used file list at the bottom of TCPmaker's File menu, so you can just click on that menu item (pointed at by the big red arrow labeled "1") to re-open the existing project file.

 

  Click on the image for page view.




Page 6


In any case, you can always open an existing TCPmaker project file (extension *.tpr) by clicking on menu item File | Open Project... and navigating to the correct project directory.

  Click on the image for page view.




Page 7


Opening an existing project will take you to the "Select Compilers" page of the TCPmaker wizard.

In our case, we are only interested in re-generating C18 code.  However, if you wanted, you could also check other compilers, to generate or re-generate code for them as well.

Since we are re-generating code for an existing project, notice what happens when we now click the Next button...

  Click on the image for page view.




Page 8


Because you may have modified the existing file MainDemo.c (not necessary, but possible in TCPmaker projects), TCPmaker brings up a message dialog that lets you decide whether you need to keep your existing version of this file (in order to preserve your changes).

If you have made any modifications to the MainDemo.c file, you must answer YES to prevent this file from being overwritten by TCPmaker.

  Click on the image for page view.




Page 9


Similarly, TCPmaker will ask if you want to save the existing file HardwareProfile.h.

If you have made any modifications to the HardwareProfile.h file, you must answer YES to prevent this file from being overwritten by TCPmaker.

 

  Click on the image for page view.




Page 10


In exactly the same way, TCPmaker will ask you if you want to preserve the existing file TCPIPConfig.h.

 

If you have made any modifications to the TCPIPConfig.h file, you must answer YES to prevent this file from being overwritten by TCPmaker.

  Click on the image for page view.




Page 11


Answering that last question will take you to the next page of the TCPmaker wizard.

As the big red arrow points, click on the "Design Your Web Page..." button to enter the Visual Page Designer.

  Click on the image for page view.




Page 12


Remember that we wanted to add one more LED (class Ld) indicator, and one more button (class Pb) to our layout.

However, we musn't forget to add new variables to carry data between these new controls on the PC browser screen and our board, over the ethernet connection.

The screen shot below shows the variables we have presently. We will want to add integer variables named D5 and Btn3. 

  Click on the image for page view.




Page 13


We will use Copy / Paste operations to duplicate existing variables, in order to save time.

To begin, we select existing variable Btn2, and then right click on its row in the grid to bring up a popup menu.  We click popup menu item "Copy variable(s)" to copy variable Btn2 to the clipboard.

 

  Click on the image for page view.




Page 14


Then, once we have copied Btn2 to the clipboard, we select the blank line of the grid just after the last existing variable, and right click again to get a popup menu.

This time, we click the menu item "Paste variable(s) here".

  Click on the image for page view.




Page 15


This duplicates our variable Btn3, but gives it an arbitrary name that isn't what we want. We need to edit this new variable to change its name.

We could edit this variable by right clicking the new variable, pointed to by the red arrow, and then clicking "Edit this variable..." on the popup menu.

However, it is faster to just double click on the new variable to bring up the editing dialog directly.

  Click on the image for page view.




Page 16


Once we bring up the Edit a Variable dialog, we see that we will want to edit two properties:

We want to change the variable's name to Btn3.

The comment (left over from the variable Btn2 that we duplicated) is almost right, which is why we chose to duplicate an existing variable. We'll just make a few quick edits, changing the number '2' to the number '3' in two places.

 

  Click on the image for page view.




Page 17


Once we have made our quick edits (arrows 1 and 2), we are done editing, and can dismiss the dialog by clicking the OK button (arrow 3).

  Click on the image for page view.




Page 18


In a similar fashion, we duplicate variable D4 and edit it to make variable D5 (arrow 1). We just have to remember to put the correct pin name, RJ3, in the comment (arrow 2).

  Click on the image for page view.




Page 19


Now we're ready to add our new controls. We click on the "Step 2" tab page to see our layout.

Again, we'll use Copy / Paste operations, this time to duplicate existing controls.

 

  Click on the image for page view.




Page 20


To do that, we select an existing Ld control, and then right click on it to bring up a popup menu.

 

  Click on the image for page view.




Page 21


Now, right click on the layout to bring up a popup menu, and click menu item "Paste Item."

  Click on the image for page view.




Page 22


This will paste a copy of the Ld control to the design.  You will have to drag it to the position you want, and perhaps use the Advanced Properties group to make fine adjustments to its _x and _y coordinates to position the control precisely.

 

  Click on the image for page view.




Page 23


Now that we have placed our new control, we use its property page to associate the new variable with it.

Note that, because we duplicated an existing control that was associated with variable Btn2, our new control is also associated with Btn3 (red arrow).

We need to be sure to change the i property to associate our new control with our new variable Btn3.

 

 

  Click on the image for page view.




Page 24


Hmm.  As we prepare to add the new Pb button control and associate it with new variable D5, we notice that the labels of the existing Pb button controls are wrong.  For example, the label of the top button (currently selected) says "LED RJ0", but it is associated with variable D1, whose comment is "Diode D1 connected to RJ7".

Oops.

So, now's the time to fix stuff like that.

  Click on the image for page view.




Page 25


Once we fix the labels of the existing Pb controls, we use copy / paste operations to duplicate the red Pb button control, and then edit its properties to associate our new D5 variable with it.

Oh, and we gave the new button a yellow color and a correct label, "LED RJ3" that matches the comment of the D5 variable.

Finally, we shrank the big Px animation that shows the spinning logo.

The result is shown in the screen shot below.

  Click on the image for page view.




Page 26


At this point, we are done with our changes to the layout, so we follow the usual steps to save our layout and generate code, making sure to save the project file as we exit TCPmaker.

The Windows Explorer screen shot below shows the contents of the subdirectory

  PIC\MCHP_C18\TCPmaker\

subdirectory, under our project directory C:\Trace\TCPmakerPro\Projects\Partial\. This subdirectory is where the generated code goes, and where the generated MPLAB project file is found.

The red arrows are pointing to the only two new file names in this subdirectory: mtGen.h0 and mtGen.c0.  These are the previous versions of the files mtGen.h and mtGen.c, which contain the "real I/O" code that you added to these files.  These files were renamed from mtGen.c to mtGen.c0, and from mtGen.h to mtGen.h0, just before the code generator generated new files.

The files mtGen.h and mtGen.c that we see now are the newly regenerated versions, which do not contain your "real I/O" code snippets, until you copy those snippets from the .c0 and .h0 files into the new .c and .h files.

If you re-generate code a second time, then the new version of mtGen.c will be copied to a new file mtGen.c1, just before a new file mtGen.c is generated.  A similar process of renaming occurs with mtGen.h as well.

If you keep re-generating code again and again, this process will continue until you have created mtGen.c9 and mtGen.h9.  If at this point you try to regenerate code one more time, TCPmaker will warn you, and give you a chance to move or rename mtGen.c0 and mtGen.h0, before it renames the previous mtGen.c to mtGen.c0, and renames the previous mtGen.h to mtGen.h0.

As long as you understand what is happening, you should never be in danger of losing your "real I/O" code additions.  You have plenty of opportunity to save and transfer your "real I/O" code snippets to your newly re-generated files.

   

  Click on the image for page view.




Page 27


Now, we could use a program editor like MPLAB to copy the "real I/O" code snippets from mtGen.c0 to the corresponding places in our newly regenerated mtGen.c, using copy / paste operations.  We could repeat the process and copy any additions we might have made in our old version mtGen.h0 to our newly regenerated mtGen.h.

However, there is a better, faster way, using a file differencing program like Beyond Compare.  This inexpensive and very popular tool is now in its 3rd major version. We will now show how you can use this powerful tool to quickly and easily move the code snippets from the old files to the new ones.

Beyond Compare integrates its commands into Windows Explorer, so you can right click on a file name and select Beyond Compare commands from the popup menu, as we see in the screen shot below.

We start the process by selecting file mtGen.c0, which is really the previous version of mtGen.c and which contains our "real I/O" code additions.  We then right click on this file name, and on the popup menu that comes up, we click Select Left File for Compare. 

  Click on the image for page view.




Page 28


Next, we select the newly regenerated mtGen.c, and then right click on that file name. On the popup menu that comes up, we click Compare to "mtGen.c0".

This will bring up Beyond Compare 3, showing a side-by-side comparison of these two source files, as shown on the next page of this tutorial.

 

  Click on the image for page view.




Page 29


This is the file comparison view of Beyond Compare 3. The first file we selected, our old version mtGen.c0, is shown on the left side, and the newly regenerated mtGen.c is shown on the right side.

Line-by-line differences in actual, compilable code between the two sides are shown highlighted in red.

Differences in comments are shown highlighted in blue.

The line we are pointing to only exists in the file on the left. The file display on the right indicates a hatched pattern at this point, indicating that nothing is present at the corresponding point in the newly regenerated mtGen.c file on the right.

When we click on the little yellow arrow on the left side (pointed at by our giant red arrow), we see that...

  Click on the image for page view.




Page 30


... our code snippet gets copied to correct place in the file on the right side! (See arrow 1)

At the same time, we see that the highlighting has gone away from this line, because these two lines are no longer different.  We do see a yellow band just to the left of the line we have just copied on the right side, indicating that this line has been copied but not yet saved.

We also see that the little floppy disk icon in the upper right has lit up, indicating that the newly regenerated file mtGen.c on the right has just been modified, and needs to be saved at some point.

We can continue this single-click copy process, copying code snippets from the old version on the left to the new version on the right, scrolling down through the files to find new differences that need to be copied.

Or, we can have Beyond Compare 3 find the next difference for us, if we click the small yellow down arrow on the tool bar (see our big red arrow 3).

  Click on the image for page view.




Page 31


This screen shot shows that some differences should be ignored by you.  This particular example shows the Receive Event Dispatch Table for both files.  Since we added a new variable D5 to the project, the table on the right side has a new entry 

   &D5_Info

which is not present on the table on the left, since that version did not have a variable D5. This is a kind of difference that you should leave alone.  (The comment

    // DO NOT EDIT THIS LIST.

should be a clue, as is the fact that nothing is present in the old file at this point, but something IS present in the new file, where we have added some variables and controls.)

 

  Click on the image for page view.




Page 32


Multi-line code snippets can be copied with a single click. Notice that several lines are highlighted in color (one comment line followed by two actual code lines), and that a square bracket extends downward from the little yellow arrow in the gutter that we are pointing to.

All we need to do is to click on the little yellow arrow in the gutter...

  Click on the image for page view.




Page 33


... and we see that our 3 lines have been copied to the file on the right, with just a single click from us.  

You can see that copying all the "real I/O" code snippets from the old version mtGen.c0 to newly generated file mtGen.c can go very quickly, in just a few minutes. 

We continue this process of finding the next difference, and if warranted, copying the next difference (which may consist of multiple lines of code) to the new file on the right.

 

  Click on the image for page view.




Page 34


The screen shot below shows what happens when we reach the sendLedStates() function.

This function is provided in the newly generated mtGen.c in commented out form, beginning with a /*  multi-line comment start character sequence, as shown in the file on the right side (arrow 1).

Note that on the left side, this character sequence has been removed in order to enable the function.

We can remove the comment start character sequence on the right by clicking on the little yellow arrow next to the cross-hatched "empty line" area on the left side (see arrow 2).

When we do that, Beyond Compare 3 will copy the lines indicated by the bracket extending below the yellow arrow, which includes the "empty line".

  Click on the image for page view.




Page 35


After we do that, we see that Beyond Compare 3 has copied the "empty line" from the left side to the right side, effectively deleting the line containing the /* character sequence that had disabled the sendLedStates() function.  (See arrow 1.)

Before we go on, we need to be sure to copy the other two snippets shown below:

The snippet at arrow 2 should be copied as-is, to get rid of the matching "close comment" character sequence */ after the end of the function.

The snippet at arrow 3 has to do with the fact that some of these Tx flags in the sample code correspond to variables that have not been defined in this project. Since we have now added a variable D5 to the new file on the right, we'd like to just copy 3 of the 4 highlighted lines pointed to by arrow 3 from the left side to the right side.

We'll see how to do that on the next page of this tutorial.

 

  Click on the image for page view.




Page 36


To copy part of a snippet, we use the mouse to highlight just the lines we want to copy to the other side.

We have done that in the screen shot below, and we see that Beyond Compare 3 has highlighted these newly selected lines in green.  We also see that it has placed a new green arrow in the gutter on the left, with a new bracket extending below it.

We can copy just the 3 lines that we have selected, by clicking on the little green arrow in the left gutter.  After we click the green arrow...

  Click on the image for page view.




Page 37


... we see that the lines we wanted have in fact been copied, and the line we wanted left behind still shows up as a highlighted difference.

Good!

We continue the process of working our way down the file, copying snippets (or perhaps parts of snippets if warrented.)

 

  Click on the image for page view.




Page 38


We know when we have reached the last difference between the two files, because the down arrow in the toolbar (pointed at by our big red arrow 1) turns dark.

Notice that the up arrow on the toolbar is still yellow.  Clicking on this toolbar up arrow can take you to the next difference above the current position.  Because we found that we had to leave some file differences alone, we expected that this up arrow would remain yellow.

Once we click on the yellow arrow in the left gutter that copies the last difference to the file on the right...

  Click on the image for page view.




Page 39


... we are ready to click the little floppy disk icon in the upper right corner of the right side, to save our updated file mtGen.c. This file now contains the most up to date newly generated code for our new set of variables and controls, AND it has the "real I/O" code that we had added to the old version of mtGen.c, which is still intact in file mtGen.c0.

The next step will be to use Beyond Compare 3 to copy any code we might have added to file mtGen.h0, the old version of mtGen.h.  (We may not have made any changes to the generated code in mtGen.h0. If so, then no changes are needed in the new mtGen.h.)

Note: we still have to fill in any Receive Event handlers in the file mtGen.c for the new variables we have added to our project.  We might also want to add other code as well. We can do this kind of work in MPLAB again, as our development continues. 

  Click on the image for page view.



Text Author: Dr. Bob Miller   Copyright Notice and Author Information