Example Summary
---------------
This application demonstrates the use of HTTP connection over the TLS/SSL layer
(HTTPS) to connect an IoT product, securely, to a cloud service provider called
Exosite. This demo is built to work with the EK-TM4C129EXL also called Crypto
Connected LaunchPad.

Set-Up
------
The following steps are required before building the "secure-iot" application.
These steps are covered in detail in other sections in this Readme.
  1. Install toolchain - The supported toolchains with links to download are
     specified in the section "Supported Toolchains".
  2. Install TI-RTOS v2.16.00.08 or later and get the source code of wolfSSL
     v3.8.0 or later. Refer the Section "Build - TI-RTOS and wolfSSL" for
     detailed instructions.
  3. Build wolfSSL library with TI-RTOS support - Covered in the Section
     "Build - TI-RTOS and wolfSSL".
  4. In "cloud_task.h", change the code marked by "USER STEP" if needed.
  5. Add the public key of the root certificate to the application. This step
     is already completed and not required. For details refer the section
     "Root Certificate" of this readme.

Supported Toolchains
--------------------
The following toolchains are supported:
  Code Composer Studio (CCS) v6.1 or later - http://www.ti.com/tool/ccstudio

Build - TI-RTOS and wolfSSL
---------------------------
This application runs on TI-RTOS and uses wolfSSL library with support for
TM4C hardware ciphers, for TLS functionality.  This application builds with the
following version of TI-RTOS and wolfSSL.
        TI-RTOS - v2.16.00.08 or later
        wolfSSL - v3.8.0 or later

Read the following wiki for details on downloading and installing TI-RTOS and
wolfSSL.
    http://processors.wiki.ti.com/index.php/Using_wolfSSL_with_TI-RTOS

The "secure_iot" application, by default, expects the following installation
locations for
  1. TI-RTOS - c:/ti/

After the build is complete, wolfSSL Libraries will be located in the folder
'<WOLFSSL_INSTALL_ROOT>/tirtos/packages/ti/net/wolfSSL/lib/'.

The following library files for CCS are generated:
    TM4C hardware cipher support    - wolfssl_tm4c_hw.aem4f
    wolfSSL software cipher support - wolfssl.aem4f

Root Certificate
----------------
Since this demo uses TLS/SSL protocol, a root certificate is required to
establish a connection with a cloud server. The root certificate required for
this demo is already included, in the file "certificate.h".

To include a root certificate
  1. Download the certificate from the Certificate Authority website in .pem
     format. For this demo, the certificate was downloaded from "Equifax Secure
     Certificate Authority" website (in .pem format)
     https://www.geotrust.com/resources/root-certificates/
  2. Open this .pem file and copy the contents between "BEGIN CERTIFICATE" and
     "END CERTIFICATE" lines.
  3. Add the copied lines to the "certificate.h" file, under the buffer
     "g_pui8Cert".
     Note: Add blackslash at end of each new line.

Build - Secure IoT Demo
-----------------------
Please complete all the requried steps under the section "Set-Up", before
following the steps below.

1. Import the CCS project into CCS workspace.
2. Update Compiler "Include Options" for
        TI-RTOS Products - TivaWare and NDK (Use correct versions in the path)
        wolfSSL.
3. Update Linker "File Search Path" for
        TI-RTOS - TivaWare libraries (Use correct versions in the path)
        wolfSSL libraries.
4. Build the application by using the menu option "Project->Build Project".

Example Description
-------------------
This application records various board activities by a user and periodically
reports it to a cloud server managed by Exosite.  The data is transferred
securely using HTTPS.

The example starts the TCP/IP networking stack and the wolfSSL stack.  When the
networking stack receives an IP address from the DHCP server, it is printed to
the console.  A new task called the Cloud Task is created to manage access to
the cloud server.

The cloud task synchronizes time with an NTP server.  The correct time is
needed to validate server certificate during TLS/SSL handshake process.  The
NTP server IP address is got by resolving the URL "time.nist.gov", which
resolves to a new IP every time.  Once the time is synced, the cloud task
attempts to connect to the Exosite server.  If a valid CIK is not found in
EEPROM, the cloud task requests a new CIK.  The CIK is needed for communicating
with the Exosite server.  On possessing a valid CIK, the cloud task writes to
and reads from the Exosite server once every second using HTTPS POST and GET
requests.

A command task manages all access to UART0 including a command-line based
interface to send commands to the EK-TM4C129EXL board.  To access UART0 through
a terminal window use the settings 115200-8-N-1.  On the terminal, print the
command "help" for a list of commands.  These commands can
  * Control board resources like led state.
  * Interact with Exosite server to play TicTacToe game or send alerts.
  * Update settings like NTP server, proxy server or email address for alerts.
  * Print useful information like MAC address or help information.
  * Request a new CIK.
  * Attempt to connect to the Exosite server.

Example Usage
-------------
  1. Follow the instructions under the section "Let's get started!" in the
     "Quick Start Guide" located at http://www.ti.com/lit/pdf/spmz862, to
      a. Open an account with the Exosite Portal and register the EK-TM4C129EXL
         board with Exosite Portal
      b. Connect the EK-TM4C129EXL board's Ethernet and Debug port correctly
      c. Set-up a terminal window.
  2. Then progam the secure_iot application to the EK-TM4C129EXL board.
  3. Reset the board. A banner and MAC address will be printed on the console
     followed by messages about
      a. Acquiring IP Address status
      b. NTP Server connection status
      c. Exosite Server connection status
  4. Once the connection to Exosite server is successful, a new CIK will be
     acquired and printed on the console if the Crypto Connected LaunchPad is
     connecting to Exosite server for the first time. Otherwise the CIK stored
     in EEPROM will be displayed.
  5. From here on, a command prompt is displayed unless an error occurs or the
     user issues a command.
  6. Open a browser and enter the URL "ti.exosite.com".
  7. Log into your account and click on the registered EK-TM4C129EXL board.
  8. A dashboard will be displayed and the "STATUS" widget would show "ONLINE".
  9. The LED can be controlled and the number of button presses of EK-TM4C129EXL
     switches (USR_SW1 and USR_SW2) can be monitored from this dashboard.
 10. The user can also play TicTacToe game and register an email to receive
     alerts.

Troubleshooting:
  1. If for some reason the default NTP server does not work, enter a different
     NTP server using the command "ntp" when prompted.
  2. If the local internet connection requires the use of a proxy server, then
     the proxy server setting can be entered using the command-line interface
     with the command "proxy help".

Additional Information
----------------------
For additional details on TI-RTOS, refer to the TI-RTOS web page at:
http://www.ti.com/tool/ti-rtos

For additional details on wolfSSL, refer to the wolfSSL web site at:
https://wolfssl.com