§1.  Introduction

The examples provided in NutDAC_GUI can be executed either as applets or as stand alone applications. You can create your applications as applets integrated in web pages that could be downloaded from the Ethernut's web server (or any other server). This can be very convenient, as all the code of the user application (both, the one running in the microcontroller and the one in the PC) will be stored in the microcontroller, and the only requirement for executing the whole application would be to have a PC with a java enabled browser.

Let's try it out with our recently created mygui application (see the Creating new applications tutorial).

Versions used for this tutorial

• NutDAC_Micro-1.12
• NutDAC_GUI-2.2
• ant. Apache Ant version 1.7.0 compiled on August 29 2007
• jre 1.6
• jdk 1.6

§2.  Create a jar file containing the applet

Our application uses many libraries, and we want to ship them all together in a jar file. However the libraries are rather large for a small microcontroller, and yet many classes are not used. In order to reduce the size of the final jar file, we will use proguard, a program that analyzes the code, removes unused parts and optimizes and obfuscates it.

Check that proguard.jar is in the ext/build directory. If not:

• If you have installed NutDAC_GUI sources execute
  jose@Aut-019:~/PEM-workspace/mygui$ ant importExt
  This target actually copies from NutDAC_GUI all the external resources and third party libraries required to build a stand alone application.
• If you have not installed NutDAC_GUI sources, you can try to download and use the latest version.

The build.xml has a target that takes care of creating the applet and calling proguard

§3.  Sign the applet

All the examples provided in NutDAC_GUI will open sockets to connect to the Ethernut, and might also open files in the local computer to save data. Most likely your applications will do the same. By default applets are not considered “trusted” because they are applications downloaded and started automatically by the browser. “Untrusted” applets are subject to security restrictions that allow socket connections only to the originating host and don't allow access to local files. One way to overcome this limitation is to sign the applet, so that it becomes “trusted”. You need a certificate to sign your applets, or alternatively a key. To generate your own key you can use for example keytool. We will not explain the details about how to use keytool, but only simple steps that get the job done.

• Generate a key. Of course, if you have already a key that you can use you don't need to do this.
  jose@Aut-019:~$ keytool -genkey -alias nutdac
  The previous command generates a keystore (a file to store keys) that is by default stored in a hidden file in your home directory with the name “keystore”, and creates a key with the alias “nutdac”. This is the alias name that we have been using in the NutDAC project, but you can choose your own name. By default the key generated will be valid for 6 months. Should you want a longer period, include the -validity flag in the previous command. When you run the command you will be asked a series of questions, like the ones that we present here with our answers. Use you own answers.
  Enter keystore password:
  Re-enter new password:
  What is your first and last name?
    [Unknown]:  Your Name
  What is the name of your organizational unit?
    [Unknown]:  Automation and Systems Dept.
  What is the name of your organization?
    [Unknown]:  Aalto University
  What is the name of your City or Locality?
    [Unknown]:  Espoo
  What is the name of your State or Province?
    [Unknown]:  Espoo
  What is the two-letter country code for this unit?
    [Unknown]:  Fi Is CN=Your Name, OU=Automation and Systems Dept., O=Aalto University, L=Espoo, ST=Espoo, C=Fi correct?
    [no]:  yes
  Enter key password for <myalias>
          (RETURN if same as keystore password):
• Sign the applet. Now you have a key stored in a keystore located in the file ~/.keystore with which you can sign your applets. The next step is to tell build.xml which key are you using (its alias), and the password to open the keystore. Edit build.xml and find the properties keyalias and keystorepass and put your alias and password respectively. It should look like this
  <!-- Key alias and keystore password to sign the applet -->
          <property name="keyalias" value="nutdac" />
          <property name="keystorepass" value="secret" />
  By default the signjar ant task assumes that the keystore to use is ~/.keystore, that is, the one we just created in this example. When we created this tutorial we used the password “secret” for the keystore and the key with the “nutdac” alias. Put your own alias and password. Now we are ready to sign the applet with
  jose@Aut-019:~/PEM-workspace/mygui$ ant signApplet
  Buildfile: build.xml
  
  signApplet:
   [signjar] Signing JAR: /home/jose/PEM-workspace/mygui/www/Mygui-applet.jar to /home/jose/PEM-workspace/mygui/www/Mygui-applet.jar as nutdac
    [signjar]
    [signjar] Warning:
    [signjar] The signer certificate will expire within six months.
    [signjar] Enter Passphrase for keystore:
  BUILD SUCCESSFUL Total time: 1 second

§4.  Prepare the www directory

The www directory is dedicated to the files that will be uploaded to the microcontroller's http server. We have an ant task dedicated to prepare the www directory before uploading it to the web server. It is meant for whatever automatic preparations the www directory might need. At the moment it only copies Mygui-applet.jar to the www directory

In the examples provided with NutDAC_GUI you will see that the www directory contains a file called index.html, which is the page that the http server sends by default. This page has embedded the applet of the corresponding application. Edit www/index.html and replace the names of the main class to execute and the jar library. The resulting file should look like this

§5.  Upload the www directory to the Ethernut

The Ethernut3 and the Ethernut2 use the SD card and the external serial flash respectively to store the files for the http server.

First of all you have to prepare your Ethernut, that is, program it and check its connectivity.

• Program the microcontroller with the adc_dio example provided by NutDAC_Micro. The adc_dio example starts the http server and xflash file system right after booting (be sure to do the same in your own program)
  jose@Aut-019:~/PEM-workspace/mygui$ cd ~/ethernut/nut-app/NutDAC_Micro/app/adc_dio/
  jose@Aut-019:~/ethernut/nut-app/NutDAC_Micro/app/adc_dio$ make rebuild
  the “rebuild” target will recompile the NutDAC_Micro libraries and the adc_dio application. Finally program the microcontroller with your favourite method. If you have configured NutOS so that you can use make burn, you can also use it from the NutDAC_Micro applications.
  jose@Aut-019:~/ethernut/nut-app/NutDAC/app/adc_dio$ make burn
• Check the IP of your Ethernut, which can be seen in the nutdac-config.h configuration file.
  jose@Aut-019:~/ethernut/nut-app/NutDAC/app/adc_dio$ cat nutdac-config.h | grep MYIP
  #define MYIP    "192.168.0.100"
  All the examples provided in NutDAC (Micro and GUI) use by default this IP for the Ethernut. Note that it is an IP of private network, and you have to make sure that your computer can send packets to that network. If your computer does not have an IP of that network, most likely you will need to create an IP alias. For example
  jose@Aut-019:~/ethernut/nut-app/NutDAC/app/adc_dio$ sudo ifconfig eth1:1 192.168.0.10
  Now make sure that you can reach your Ethernut, with for example ping.
  jose@Aut-019:~/ethernut/nut-app/NutDAC/app/adc_dio$ ping 192.168.0.100
  PING 192.168.0.100 (192.168.0.100) 56(84) bytes of data.
  64 bytes from 192.168.0.100: icmp_seq=1 ttl=64 time=5.67 ms
  64 bytes from 192.168.0.100: icmp_seq=2 ttl=64 time=1.22 ms
   --- 192.168.0.100 ping statistics ---
  2 packets transmitted, 2 received, 0% packet loss, time 1001ms
  rtt min/avg/max/mdev = 1.225/3.450/5.675/2.225 ms

Then upload the www directory to the Ethernut. Here we have different procedures depending on the platform that we are using

• Ethernut2. NutDAC_Micro uses Michael Fisher's Xflash file system to store the web pages in the external serial flash memory of the Ethernut2 board. The microcontroller is running a tiny TFTP server that accepts a special file containing the root directory of the microcontroller's http server. This file has to be created with crxflash, a tool that accepts as an argument a directory and collects all its files into a file (called xflash.bin) ready to be sent to the microcontroller. crxflash is included in NutDAC_GUI as an external resource (in the directory ext/utils directory). It has been programmed for Windows, but luckily wine can execute it without problems in linux, so if you are a linux user, install wine. You can call crxflash manually and use any tftp client to upload the files to the microcontroller, but we have also prepared a Makefile that will take care of this automatically.
  • First edit the Makefile and change the name of the project. Find the line
    PROJ=AdcDio
    and change it to
    PROJ=Mygui
  • Create xflash.bin. You will need to have crxflash in the ext/utils directory (if you have installed NutDAC_GUI sources, ant importExt did/does the job for you). To create the file to upload to the microcontroller type
    jose@Aut-019:~/PEM-workspace/mygui$ make xflash.bin
  • Upload xflash.bin to the microcontroller. You will need a TFTP client installed in your computer. The Makefile is prepared to use the clients “atftp” in Linux and “tftp” in windows, so be sure to have them installed properly (“sudo apt-get install atftp” in Ubuntu). Edit the Makefile and find the line containing
    ETHERNUT_IP = 192.168.0.100
    If you used another IP for your Ethernut, put the right one. Now upload the file to the microcontroller with
    jose@Aut-019:~/PEM-workspace/mygui$ make tftp
• For Ethernut3 NutDAC uses the PHAT file system and the SD card to store the files. Thus simply copy the content of the www directory into a SD card, connect the card to the Ethernut3 and reboot your Ethernut3

Now you can open your java enabled browser and go to the address http://192.168.0.100/. You should see something like this

§6.  In Short

Once that you have gone through all the process and verified that all the steps work, that is:

• You have programmed your Ethernut (with the http running) and checked its connectivity
• You can sign applets using the ant tool

then you only need one command to prepare the www directory including the applet

To upload the www directory to the Ethernut2

and to the Ethernut3 copy it to the root of its CF card and reboot.