To better understand how to design your project, let's talk about how your project will work when it is finished.
When your finished device is connected to the Ethernet, and you point your web browser at your device's address, here is what happens:
1) Your web browser sends an HTTP request for a file called "index.htm".
2) As your browser figures out how to display this file, it sees that it must also get a file called "run.swf", so it gets that one from your device as well.
3) File "run.swf" is actually a very compact Flash class library, so the browser starts its Flash plugin, which starts "run.swf" running.
4) Library "run.swf" gets another file from your device, "run.xml", which contains info about your content: the Variables and Controls that it uses. When the library reads "run.xml", it then displays the (first or "index" page of) your TCPmaker layout, showing all the controls you have positioned on that page.
5) Then, library "run.swf" begins exchanging messages and data with your device, and the Controls displayed on the browser screen become responsive.
Click on the image for page view.
When you click or drag a TCPmaker control on the browser screen, data will usually be sent between the PC and the micro. Exactly what happens depends on the specific control.
Some controls are meant to send data from the PC to your device.
For instance, if you press down on a simple rectangular Pushbutton control, then a message containing integer data will be sent from the PC to your device to indicate that the pushbutton is now "down."
When you release the mouse button over that same PushButton control, then another message gets sent from the PC to your device, to indicate that the pushbutton is now "up" again.
Each of those messages holds the data in an Integer Variable that you have created for that purpose, and which you have "associated" with that pushbutton control.
During the design process, you used the Visual Page Designer to create that variable, giving it some meaningful name like "D1" and a meaningful comment like "LED D1 connected to RJ7". TCPmaker will also create a short Id string for this variable, which is how the variable is actually identified in the messages sent between the PC and the micro.
In the code it generates for your device, TCPmaker will declare variables with the names and types that you created in the Visual Page Page Designer (like D1), along with places to send and receive this variable.
You also created the Pushbutton control in the Visual Page Designer, and when you set the control's properties, you associated a specific Variable like D1 with the control. In the case of the Pushbutton control, you did this by setting the control's i property to the Id of the Integer variable D1 (by simply selecting the name of the Variable from a drop down list).
By associating an Integer Variable with a Pushbutton Control, this tells run.swf that any time you press or release this particular Pushbutton control, the PC must set the value of the associated Integer Variable (D1 in this case), and then send a message to the micro device which contains this associated Variable.
This happens automatically: you don't need to write any code to make this happen.
What you DO have to write code for, is to actually do something with the data when it arrives at the micro device.
In the case of our Pushbutton control associated with Integer variable D1, TCPmaker will generate an Event Handler in your micro code, which is just a little routine that is called whenever that variable is sent from the PC.
TCPmaker cannot know in advance what sort of hardware you may have on your board design, so it leaves this routine empty, so you can fill it in with code that is appropriate. (Hey, we had to leave you something to do!)
Here's what you might add to your micro code in this case (your code shown in boldface type):
// Event handler for variable: D1 - Diode D1 connected to RJ7
// Variable has just arrived, so add your code
//to DO something with it here:
LED0_IO = D1;
Note: LED0_IO has been #defined in file HardwareProfile.h of the project as:
#define LED0_IO (PORTJbits.RJ0)
All you had to do was to add 1 line of code to light up the LED, by just assigning to its port pin the variable that was just sent from the PC. That's the power of TCPmaker!
Let's sum up what we've seen so far. To send an integer data item from the PC to the micro device, here's what you need to actually do:
- In the Visual Page Designer, create an Integer Variable to hold the data item. Give this variable a meaningful name and a unique ID.
- Also in the Visual Page Designer, create a suitable Control (e.g. a Pushbutton) somewhere on your layout, and set the i property of this control by selecting the Integer Variable you created in the previous step (i.e., select the name of the variable from a dropdown list of all the Integer Variables that you have created thus far). This will associate the Variable with the Control.
- Save your layout, and let TCPmaker generate your code. The code generator will create an integer variable of this name in your micro source code, and generate an Event Handler for this Integer Variable, that will automatically be called any time the state of the Control is changed.
- All you need to do is add a little code to that Event Handler to make use of the new value of the Integer Variable that was just sent to the device.
As we'll see in the next section, sending a Numeric Variable from the PC to the device follows a similar process. It's just a little different because a Numeric Variable displays a floating point value on the PC browser, but only communicates a scaled integer equivalent to the micro, using the automatic scaling properties mn, mx, pn, and px of the Numeric Variable. (That way, the micro code doesn't have to do any floating point math.)
Remember, this scaling process happens automatically in run.swf: you don't need to add any code to make this happen.
Here is what you need to actually do:
- In the Visual Page Designer, create a Numeric Variable to hold the data item. Give it a unique (and meaningful) name and Id.
- Set the automatic scaling properties mn, mx, pn, and px of this Numeric Variable.
- Also in the Visual Page Designer, create a suitable Control (e.g. a Horizontal Slider) that can change this Numeric Variable.
- Associate the Variable with the n property of the Control, by selecting the name of the variable from the dropdown list.
- Save your layout, and let TCPmaker generate your code. The code generator will create an integer variable of this name in your micro source code (to hold the integer equivalent of your Numerical Variable), and generate an Event Handler for this Numeric Variable, that will automatically be called any time the state of the Control is changed.
- All you need to do is add a little code to that Event Handler to make use of the new integer equivalent value of the Numeric Variable that was just sent to the device.
What if we want to send an Integer or Numeric Variable from the device to the PC?
The process has some similarities to what we've seen so far:
- We still need to create a Variable to hold the data.
- We also need a Control in our content layout that can display that value. (For example, an LED indicator can show an On / Off value sent from the device.)
- We need to associate the Variable with the n property of the Control.
- TCPmaker's code generator will declare an integer variable in the micro code that has the same name as the Integer Variable you create in the Visual Page Designer.
- And we still use the principle of Direct Transfer of Variables, so we will assign to this variable the value we want to send to the PC, and then tell the micro to send this variable.
What's different from what we've been doing so far is that an Event Handler is meant for data that is sent OUT from the PC to the device. If we are going to send a value IN to the PC, where do we put the micro code to do this, and what exactly does this code have to do?
To send a data item from the device to the PC browser, you must do 3 things:
1) Assign a value to the variable, e.g.:
MyVar = 5; // or it could be an A/D converter result
2) Set the transmit flag for that variable to true (any non-zero value), e.g.:
MyVarTxFlag = 1;
3) Synchronize these actions to the MicroTrace Server by doing the above steps
in one of the general mtServer Event* handlers below. (We suggest putting
these in the mtEndOfMessage() event handler.) Doing so will make
everything operate smoothly.
You could synchronize these actions by placing them in one of the receive
event handlers discussed above.
If the variable you are sending to the PC is a Numeric Variable, remember that you are supposed to assign a value (to the integer variable that TCPmaker has declared for this variable) that lies between the values of the mn and mx properties of that Numeric Variable, before you set the TxFlag. When received by run.swf on the PC side, the Numeric Variable will automatically scale the integer value you sent, to a floating point value in the range between the values of the variable's pn and px properties.
* We will discuss the general mtServer Events in a later tutorial.
How do I send a String Variable?
Well, actually, we don't recommend that you send or receive String Variables directly. String variables are intended to be formatting objects that are only used inside run.swf on the PC.
Rather than sending a String Variable, you send the variable or variables that are associated with the String Variable's argument list (the v property). On the PC, these variables will get handled automatically, and applied to the format string in the s property of the String Variable.
But What if I Want to Send or Receive a String?
Certain TCPmaker Controls are designed to send or receive strings. We call these Communication Controls, and they include:
Mt - Multi-line Text control (for strings sent to the PC)
It - Input Text control. Intended to let you type and send strings to the micro device, but can also display strings sent from the micro to the PC.
Tx - Text control, meant to be static text for titles, but micro can send strings to it for display of warnings or whatever you need.
TCPmaker will declare (in the generated micro code) a character array for each of these Communication Controls, with the same name it gave the control itself (e.g. It1), and a matching transmit flag (e.g. It1TxFlag) to use for sending the contents of the character array to the PC.
In the case of an It control, which is designed to send a string to the micro device, TCPmaker will also generate a receive Event Handler that will be called whenever the It sends a string to the device.
Can a single Variable be associated with more than one Control?
Certainly. You can associate a single Integer, Numeric, or String variable with as many different Controls as you like. There are some very good reasons for doing so:
- You may want to display the same value in multiple ways, using different kinds of controls.
- You may want to display the same value on multiple pages of your TCPmaker content layout.
- You may want to test your layout's behavior by temporarily associating, with many other controls in the layout, a variable that is controlled by a Pushbutton or Horizontal Slider. When you test your layout on the Step 3 tab page of the Visual Page Designer, you'll be able to easily change the value of this test variable, and see how your other controls behave. Then, when you are satistied, you can associate the correct variables with your controls again before you exit the Visual Page Designer and generate code.