Before progressing to the more exhausting tutorials, which eventually demonstrate some of the more advanced features of both TINE clients and TINE servers, you can go through the following steps to get a feeling for some of the basic features, tools, API calls, etc.
Step 1 (download) :
First, download the TINE distribution for your unix platform. For the sake of this tutorial, we shall assume that you're using some brand of Linux. Also download the java distribution, as we will make some simple java clients (without writing code or using a java IDE!). Unzip and untart the tineLinux.tar.gz and the tineJava.tar.gz files into your preferred location. Let's say that you have chosen to unzip everything into ~/tine.install.
So your install directory might look something like:
Step 2 (installation):
In the non-windows distributions, the binaries have not yet been built, as it is in general best to build the binaries on your particular platform (with your libc, etc.). So please run the setup script (or setup64, if you are using 64-bit Linux or setupFreeBSD, if you are using FreeBSD). This will make all of the relevant libraries and some useful command line tools. When 'setup' finished it should have told you the next steps to take, but we'll repeat them here below.
- Edit the file cshosts.csv found in the tine/database subdirectory. You should replace the ip address it contains with the ip address of the tine equipment name server(s) (ENS) for your site. Right now you don't have one! You will soon. And for this tutorial, we will work 'inside-the-box' with one local instance of the ENS.
So either put the address of your host machine in this csv column or use the loopback address, 127.0.0.1.
- Now run the 'installAsRoot' script. But as the name of the script implies, you should become super user. This script will install the libraries '/usr/lib' and the tine include files in '/usr/include/tine'. It will also put the command line tools in '/usr/bin'.
Theorectially, you don't really need to do this, but life is a lot easier if you do, because you would otherwise have to edit the Makefiles which make the central services and specify new locations for the libraries and include files. - Now cd to the 'tine/servers' directory and run the 'makeall' script. This will make all of the central servers found in the distribution as well as an example Sine Generator server, which we will use in this tutorial.
The setup script has not set the environment variable 'TINE_HOME', which should point to the directory containing the cshosts.csv file, because it doesn't know what shell you are using. You'll have to do this yourself in your .bashrc (if you use bash) or .cshrc if you use the c shell, etc. (e.g. export TINE_HOME=/usr/etc/tine for bash). If 'cshost.csv' is missing or cannot be located, a TINE application will try to determine the ENS address by asking the Domain Name Server for the ip address of a host called tineens on the local domain. Your domain will certainly not have such an entry at this stage of the game!
Step 3 (The Equipment Name Server):
Go to the Go to the tine.install/tine/servers/ENS/bin directory in another shell and start the Equipment Name Server (ENS) by typing './ens'. We could have started it in the background from within the same shell, but for purposes of instruction we will want to check the output to the console as we move along. Later we can see how to do the same thing when a server is in fact running in the background. At the command prompt of the ENS type 'set debug=1'
So far this is the only TINE server running at your 'site'. It is of course a very special server and is found in the TINE context "SITE".
Step 4 (The Instant Client):
Now we will start the install the tine Java applications. In this case, we do not have to build any of the binaries, but instead simply 'install' them.
HOWEVER, you should have java 1.7 or higher installed on your machine, or the java applications will not start! As before, you should cd to the tine.install/tine/java directory and run the installAsRoot script. This script simply places the java applications in /usr/local/tine and, for your convenience, an application startup script for the "Instant Client" in /usr/bin. In particular, the java "Instant Client" can be started by typing 'JClient' at the command line. When you do this, you should notice some output on the console screen of the ENS, namely the Instant Client has asked it for the list of available contexts and servers. At this stage it got back a list of 1 context "SITE" containing a single server "ENS". And you can browse its 'properties' and 'devices' with the Instant Client. The Instant Client will also display, in addition to the registered contexts, a de-facto context called "DEFAULT", which is in effect equivalent to 'no context specified'. If a device server name is otherwise unambiguous, you can thus access it without specifying the context. For our present case if you select context = DEFAULT or context = SITE you will see the same servers. Note: as we started the ENS from scratch, it created its initial database with itself as the only entry.
If you select some of these device server entries and have a look at the output on the ENS console you will see some activity (as we have set the debug level to '1').
This reflects the fact that by selecting a new server, the client program (the Instant Client) must acquire the server's address and it goes about this by asking the ENS. The address is then cached locally. When you select the server call "ENS", you then ask it specifically for its properties and devices. Hence you will also see output at the console in this case as well.
This is all not really very interesting at this stage, so let's start a real server.
Step 5 (The Sine Generator Server):
In another terminal, go to the tine.install/tine/servers/SineGenerator/bin and start the Sine Generator Server by typing './sinegen'
When the Sine Generator starts, you should see more output on the ENS screen. Namely, this new server has 'plugged' itself into the system by informing the ENS that it is starting. It will try to register itself as a new device server called 'WinSineServer' in a context called 'TEST'. If you have a look at the ENS console you will see some of the 'plug-and-play' activity on the screen. In the end, the new FEC and device server are accepted (as there can't be any name conflicts at this early stage) and the ENS updates (and backs out to disk and re-reads) its database.
This Sine Server is another 'console' server just like the ENS itself so you can set the debug level to 1 (or higher) in the same way here.
Step 6 (Accessing the Server with the Instant Client):
Find the new server called 'LxSineServer' in the instant client. (NOTE: it might be called 'SoSineServer' if you are on Solaris, 'WinSineServer' if you are on Windows, etc.). You won't be able to find it immeadiately, because it's new. So go to the options menu of the Intant Client and click on 'Reload Names'.
Now you should see a new context called 'TEST' with a single server called 'LxSineServer'.
You can access any of the properties shown and see what they do. There are 10 instances of a sine curve, given device names 'SineGen0' through 'SineGen9'. Each has properties 'Sine', 'Amplitude', 'Frequency', 'Phase', 'Noise', and 'SineInfo'. The property 'Sine' is a read-only 'Spectrum' type property (or WaveForm or Trace, if you prefer) and naturally displays itself as a polyline trace.
The properties 'Amplitude', 'Frequency', 'Phase', and 'Noise' are read/write Channel type properties. This means you can read all or a subset of the amplitudes with a single call. If you ask for more than one amplitude, the selected Device Name gives the starting index, and the results are 'naturally' displayed as a histogram (whose x-axis indicates the individual devices).
You can override the display mode in the instant client by selecting any of the modes offered in the Draw Mode combo box. And by unchecking the 'Suggest Draw Mode' checkbox, you can disable the automatic display mode selection.
Note that in the above display, the amplitude of the initial sine generator (SineGen0) has already been changed away from the (factory installed) value of 256.0.
Step 7 (A Simple Client Application):
Let's try to make our own client application.
Let's start the Container Object Manager, (COMA). Start this application by going to the directory tine.install/tine/java/apps/ComaStart and typing './ComaStart' at the command line.
When the application starts, you should see nothing but an empty frame:
You can strech the frame to some size that you like, so make it a bit bigger, and then enter 'EDIT' mode by holding the CTRL key down while you press the right mouse click button somewhere over the empty frame. You know if the key events were accepted properly if the mouse cursor becomes a 'hand' and the application's caption appends '[ edit mode ]' to the title bar. If you then (while in EDIT mode) click the middle mouse button (or your wheel, if your mouse has a wheel) you should see a menu containing possible acop beans to add to the application. Note: The processing of click events is some times tricky here, so you might have to click the middle button a couple of times to entre EDIT mode.
Add a 'new ACOP' (which is actually an ACOP chart control), a 'new Dial Knob', a 'new Slider'. These are all 'ACOP' beans (ACOP stands for Advanced Component Oriented Programming). Leave EDIT mode, the same way you came, i.e. CTRL + right mouse button.
Now you've got some graphics on your application, but they don't, as yet, do anything. The magic of ACOP beans lets you browse and connect them at run time (as well as as design time), so position the mouse pointer somewhere over the chart and issue a right-mouse click. You should see an option menu appear.
Choose "Preferences", and a property 'customizer' for the chart appears.
From among the options appearing on the left side panel, choose 'Connections' and you should see a browser panel appear on the right hand side. Find the property "Sine" for the Sine Generator by selecting context "TEST", Device Server "WinSineServer", Device "SineGen0", and finally property "Sine". You can leave everything else as it is and click on the 'Add' button (note: you can have several active plots on the same chart, but we'll stop here). And then click close. The default Access Rate is 1000 milliseconds (i.e. 1 Hz), you can also set this to a higher rate if you want to see faster updates. The ACOP Access mode "POLL" means the polling rate at the server and that the server should send the data at each scheduled timer event. It does NOT mean that the client application polls the server!
Now move the mouse over the ACOP Dial Knob and issue a right-mouse click so as to bring up the popup menu and select 'Preferences'. The ACOP Dial Knob customizer should appear. Once again, select 'Connection' and browse your way to the 'Amplitude' property and click the 'Connect' button.
Before you select 'Close', select the 'Value Display/Advanced' item from the left hand panel, and make sure the 'editable' property is set to 'true'! Remember the property 'Amplitude' is also a 'settable' property.
We won't detail the procedure here, but you can follow the same steps above for attaching the 'Amplitude' to the ACOP Dial Knob in attaching the 'Frequency' to the ACOP Slider. Note: Make sure the 'connect' the property to the control. At the time of this writing, there is an intermittent bug in the run-time bean which tends to show 'editible' as 'true' when it isn't, so you might have to set it to 'false' and then re-set it to 'true' in order to send setting to the server.
You can save your 'application' by re-entering EDIT mode, issuing a middle button click and select 'Save' from the popup menu. The COMA application can take the saved file name as a command line argument in order to start up with your previous changes.
Step 8 (Command Line Tools):
You can open up a command prompt and test some of the command line tools, such as 'tget' or 'tmonitor', etc. Most of these tools are covered in the more advanced tutorials. But as a preview of things to come, type 'tget' at the command prompt. You should see a 'usage' text. Then try typing 'tget /TEST/WinSineServer/SineGen0 Amplitude'. If you do this, you should see 10 values returned, namely all amplitudes for the Sine Generator Devices beginning with SineGen0. To just get the single value for SineGen0, type 'tget /TEST/WinSineServer/SineGen0 Amplitude 1 float'. To get the value for SineGen1, type 'tget /TEST/WinSineServer/SineGen1 Amplitude 1 float', etc. Note that if you've followed the steps so far, your client application hasn't changed the values of Amplitude or Frequency at all for SineGen1 to SineGen9 from their startup values.
Step 9 (FEC Remote Panel):
You can sample some of the other applications that the install package put in tine.install/tine/java/apps if you'd like. For instance, start the "Remote FEC Panel" by going to tine.install/tine/java/apps/TineApps and typing './FECRemoteControl' at the command prompt. This will start up by querying the ENS for the available contexts and offer the available FECS (FEC View) or Device Servers for the selected context. It will Show the servers in context "SITE" when it starts, because we have so far, only two contexts, "SITE", and "TEST" and combo box selector is alphabetically ordered. Select context "TEST" and you will not at first see any servers to examine. That is because the LxSineServer belongs to Sub-system "TEST" as well, and the FEC Remote Panel does not show Sub-system "TEST" by default (the check box is not checked). So check this check box, and you should see the LxSineServer appear in the grid. You can then 'tab' your way around looking at the clients attached to the server (you are attach automatically via the FEC Remote panel itself), the current contracts in server's contract table, the server's log file, etc. You will not be able to restart or otherwise 'control' the FEC at this stage, as we have no control daemon running.
Step 10 (More Advanced Tasks):
We haven't coded anything so far, either at the server side or the client side. We have simply had a look at a Sine Generator Server, useful for testing client appications. And we have made a 'simple' client application using the Container Object MAnager (COMA) and ACOP beans. 'Rich' client applications are, of course, another matter and are taken up in the more advanced tutorials. The nice thing about building COMA applications is that there is no external 'framework'. The framework is 'built-in', so to speak. We did not start Eclipse, NetBean, or anything else in order to build the application. Indeed, we do not even need to know that it is a java application.
We'll leave java server applications for the more advanced tutorials, but you can have a look at the code used to generate the sine generator. Go to tine.install/tine/servers/SineGenerator/source and have a look at the project.
The 'meat' of the server program is in the module sineqm.c (with corresonding header sineqm.h). As an exersize you might see how you would go about adding a property called "Attenuation", which would degrade the overall amplitude along the x-axis. This would be modelled on the 'Amplitude' property, namely it should be 'settable' for a single device and delivery a multi-channel array (if desired) upon read. If you're really feeling adventurous, you can add a field called 'attenuation' to the structure used in the "SineInfo" property. This is already fairly advanced, but the c-code here is not to hard to follow.
This simple server application is, as you see, written in straight c. You can also think about how you would re-write it in c++. This server application was NOT generated with the TINE Server wizard (another tutorial). You might want to use the TINE server wizard to try to reproduce the server code used here, i.e. to get an idea of what the Server wizard can do. One thing it cannot do yet, is to preserve user changes if the server wizard is re-applied to an existing project! (It does, however, make a backup of the previous code modules).
