  Introduction
  ------------
  This is a sample Java application which simulates a tank: its level, 
  temperature and the status of the In/Out valves.

  Every 2 seconds the sample updates the status of the simulated tank 
  parameters, this includes the randomly generated temperature and the level 
  calculated based on the status of the valves. Every 10 seconds the status of 
  these variables is checked and new samples are pushed to Device Cloud.

  When the application is launched it will automatically connect to Device 
  Cloud. Once a connection is established, the application starts the tank 
  monitoring and the new values are pushed to Device Cloud:

    - Level: Simulated based on a maximum volume and input/output flow values.
    - Temperature: Simulated with half degree increase/decrease. It is random 
      between a maximum and minimum value.
    - Valve-In/Valve-Out state: Status of the tank valves, ON when the valve is
      opened, OFF when the valve is closed. Remotely controllable through 
      Device Cloud, using the device request feature.

  This sample also waits for incoming data requests to open/close the tank's 
  valves.

  Before running the example, please read through the information below and
  configure all necessary items.

     1) Device Cloud by Etherios
        Device Cloud easily connects your device running Cloud Connector 
        (Step 2) and the WEB application (Step 3) even when firewalls are in 
        use.

        To learn more about Device Cloud visit following the web page: 

        http://www.etherios.com/devicecloud

     2) Cloud Connector by Etherios
        Software which allows you to easily integrate any M2M device with Device
        Cloud.
     
     3) WEB application
        A WEB application using Google App Engine has been developed to remotely
        monitor and control your device. It can be executed directly from the 
        App Engine, where it is hosted, on any PC with an Internet connection.
        You can learn more about Google App Engine here:

        https://developers.google.com/appengine/

        Our app can be found here:

        http://device-cloud-tank-demo.appspot.com

  Using these pieces the Simulated Tank example demonstrates the following:

     - Based on the valve's state the application estimates the tank level 
       percentage which is also reported to Device Cloud. The temperature is 
       simulated with a half degree increase/decrease between a maximum and a 
       minimum value and it is reported to Device Cloud as well.

     - The WEB application, hosted on App Engine, can monitor and change the 
       simulated tank valves from any location. It also monitors current tank 
       level percentage and temperature, all through Device Cloud using the Web 
       Services API.
       
     - Data Services can be used to monitor historic tank level and temperature.

     - The connection between the device running this sample and the WEB 
       application is established via Device Cloud.


  Main files
  ----------
    * com.etherios.connector.tank.MainApp.java:
      Main application class. Instantiates and starts the Cloud Connector object.

    * com.etherios.connector.tank.ConnectorEventsListener.java: 
      Class which handles the connector events.

    * com.etherios.connector.tank.TankMonitor.java:
      Class which monitors the tank and sends data points to the Cloud.

    * com.etherios.connector.tank.SimulatedTank.java:
      Class which simulates a tank.

    * connector_config.txt:
      Cloud Connector general settings.


  Requirements
  ------------
  To run this example you will need:
    * A PC connected to the Internet to host and run the application.
    * A Device Cloud account.
      For further information on how to create a Device Cloud account go to
      the 'Creating a Device Cloud Account' topic of the Getting Started.


  Example setup
  -------------
    1) Ensure Cloud Connector is properly configured.
       This can be done editing the 'connector_config.txt' file which is 
       located in the 'res' folder of the project. Make sure that the 
       'vendor_id' field is filled with your account Vendor ID.
       
       For further information on how to configure the 'connector_config.txt'
       file, go to the 'Cloud Connector Configuration' topic of the
       Developer's Guide.

    2) Ensure the device is registered in your Device Cloud account.
       By default, it is registered automatically because the Device ID is 
       provisioned from Device Cloud. If you want to modify this behavior, 
       read the 'Device ID Type' section (Developer's Guide > Cloud Connector 
       Configuration > General Settings).

    3) The Application Descriptor needs the following API Permissions:
      
        java.io.FilePermission "<<ALL FILES>>" "read"
        java.util.PropertyPermission "*" "read,write"
        javax.microedition.io.AccessPointPermission "*"
        javax.microedition.io.Connector.file.read
        javax.microedition.io.Connector.file.write
        javax.microedition.io.SocketProtocolPermission "socket://:*"
        javax.microedition.io.SocketProtocolPermission "socket://*:*"
        javax.microedition.io.SSLProtocolPermission "ssl://:*"
        javax.microedition.io.SSLProtocolPermission "ssl://*:*"
        javax.microedition.location.LocationPermission "location" "location"

    4) The Etherios public certificate is imported to the device's keystore.
       For further information, read the 'Adding the Etherios Certificate to
       Your Device' topic inside 'Creating and Building a Java Project with 
       Cloud Connector support' of the Developer's Guide.


  Running the example
  -------------------
  The example is already configured, so all you need to do is to build and
  launch the application. Refer to the general instructions about how to build, 
  run, and debug the examples for further information.

  To verify that the application is running successfully, follow these steps:

     1) To access the Tank Simulation Demo from a browser on your desktop use

        http://device-cloud-tank-demo.appspot.com

     2) To access the demo you will need to provide the Device Cloud server 
        where your account is registered and your Device Cloud Username and 
        Password. Click the 'Login' button after entering this information.

     3) Go to the 'Devices' tab and select the device called 'Emulator' from the
        list. Click 'Save' and the tab called 'Tank' will be automatically 
        activated.

  The Tank Simulation application will continually send data to Device Cloud
  that will be interpreted and displayed in the browser. You can monitor and
  change the status of the tank by selecting it.

  If you click on the valves within the WEB application, the level will vary
  accordingly:

     o Tank level should be affected in the following way:

        - If Valve-In is closed and Valve-Out is closed, it should not vary.
        - If Valve-In is open and Valve-Out is closed, level should increase.
        - If Valve-In is open and Valve-Out is open, level should decrease slowly.
        - If Valve-In is closed and Valve-Out is open, level should decrease faster.

     o Temperature is simulated by the application. Please, remember that the 
       refresh time of the WEB app is 20 seconds.

  The 'Simulated Tank' on the left side shows the current status of the tank:
  level, temperature and valves.

  Use the 'Show Histograms' button to display some charts where the tank
  level, temperature and valve status are represented.

  NOTE: if you change the tank location and want to see the new location on the
  map located on the right side, click the 'Save' button of the 'Devices' tab.

  The simulated tank data (level, temperature, Valve-In and Valve-Out status) 
  can be also reviewed from Device Cloud, under the 'Data Services > Data 
  Streams' section.
