Staging:CC3120 Email

Overview
This is a sample application demonstrating how to send emails using SMTP (Simple Mail Transfer Protocol).

Application Details
SMTP is an Internet standard for electronic mail (email) transmission. First defined by RFC 821 in 1982, it was last updated in 2008 with the Extended SMTP additions by RFC 5321—which is the protocol in widespread use today. For more information regarding STMP, please refer to Wikipedia Article: SMTP.

In thie example, the user is able to use the Simplelink Wi-Fi devices to access email servers in order to send emails. See the following diagram:



SMTP Library Details
This application requires a separate SMTP library in order to run. The compiled library can be found under /platform/simplelinkstudio/library_project_vs/lib_smtp/Debug, and the source code is under /netapps/smtp/client.

TI provides the ready-to-use SMTP library to simplfy your development time for client-server communication that typically requies the line-by-line commands as mentioned above.

The library follows the step-by-step SMTP communication process:
 * Step 1:  An SMTP session is initiated when a client opens a connection to a server and the server responds with an opening message. Create buffer, read, so we can check for 220 'OK' from server.
 * Step 2:  The client normally sends the HELO command to the server, indicating the client's identity. In addition to opening the session, use of EHLO indicates that the client is able to process service extensions and requests that the server provide a list of the extensions it supports.
 * Step 2.1: If using STARTTLS, the client sends the STARTTLS command and wait for server's confirmation. If the server accepts STARTTLS, a confirmation message with code 220 will return. The client can start transforming the socket.
 * Step 2.2: Once socket transformation completes, the client sends EHLO again. The server should respond with code 220 again as well.
 * Step 3:  The client sends the AUTH command with SASL (Simple Authentication and Security Layer). Reference: RFC-4616.
 * Step 4:  The SMTP transaction starts with a MAIL command which includes the sender information. MAIL FROM: [SP  ] 
 * Step 5:  Sends the destination email to the SMTP server. RCPT TO: [ SP  ] 
 * Step 6:  Sends the "DATA" message to the server, indicates client is ready to construct the body of the email. DATA 
 * Step 7:  Sends actual message, preceded by FROM, TO, Subject, Message, and end message with .
 * Step 8:  Terminate session by sending the QUIT command and closes socket.

Prerequisite

 * 1x CC3120BOOST
 * 1x CC31XXEMUBOOST
 * 1x Micro-USB cable
 * 1x Windows PC with:
 * Visaul Studio Community 2015 (minimum)
 * 1x 2.4GHz AP with internet access

Source Files Details

 * main.c - Initializes the device in default configuration and creates two task 'mainTask' and 'CmdTask'
 * cmd_email.c - Implementation to handle all user inputs for Scan Policy
 * email.c - Implementation to exercise all Scan Policy commands
 * str.c - Defines all command option and message strings

Library source (located under /netapps/smtp/client):
 * smtp_client.c: The core code of the SMTP library.

Key Simplink API used

 * sl_Socket - creates socket
 * sl_Connect - connects to the SMTP server
 * sl_Close - terminates socket
 * sl_Send - sends packets to the SMTP server
 * sl_Recv - recevies incoming packets from the SMTP server
 * sl_SetSockOpt - sets the socket security method and cypher, and transform the socket into TLS socket using STARTTLS protocol

Using a correct certificate file
In the ImageCreator tool, flash the certificate under the following location: /sys/cert/ca.der

Configuring Source Email Account
Although this application has a command line interface to dynamically input email content, users still need to modify the source code in order to configure the target SMTP server that the users want to use.

To simplify the process, email_common.h is the only file users will need to modify, and it's located under the /examples/email directory:

Here are the essential fields that you'll need to modify in order to run this demo:
 * SRC_EMAIL_USERNAME - your source email address (for example, bob@gmail.com)
 * SRC_EMAIL_PASSWORD - the password associated with your email address
 * SRC_EMAIL_SERVER_ADDRESS - the SMTP server your email address is based on. In this demo code, we have already provided the server address and port number for 3 most popular email services - Gmail, Yahoo mail, and Outlook.com. However, you can use any SMTP-supported email servers.
 * SRC_EMAIL_SERVER_PORT - the SMTP server port number
 * SRC_EMAIL_SERVER_SECURITY - security method to be used during account authentication. SL_SO_SEC_METHOD_SSLv3_TLSV1_2 is used here so the system automatically chooses the highest possible security method.
 * SRC_EMAIL_SERVER_CIPHER - the security cipher to be used along with the server. Please check your email server to make sure such cipher is supported.
 * SRC_EMAIL_SERVER_USE_STARTTLS - set to 1 for using STARTTLS, 0 otherwise. For details about STARTTLS, please refer to Wikipedia article: STARTTLS.
 * DEVICE_YEAR/DEVICE_MONTH/DEVICE_DATE/DEVICE_HOUR/DEVICE_MINUTE/DEVICE_SECOND - Please change these fields to your current date and time in order to validate the server certifcate.

Example Use Cases and Outputs
Here's an example run that a user with the Gmail account sends email to an TI email address.
 * 1. Sets source email address, password, server properties in the email_common.h file mentioned above.
 * 2. Connect the boards, compile, and run the application. Please refer to CC31xx SimpleLink Studio for setup details.
 * 3. Upon getting the prompt for user input in the console window, enter the desination email address, email subject, and email message with the following command:

command>>:setemail -d ***@ti.com -j CustomeEmailSubject -m MyEmailMessage Email configured successfully.
 * 4. Making sure all configurations are correct before sending the email. Use the getemailconfig command to display the configuration:

command>>:getemailconfig Email Server Family:         2 Email Server Address:        74.125.30.109 Email Server Port:           587 Email Server Security Method: 4 Email Server Security Cypher: 65536 Source Email Username:       ***@gmail.com Source Email Password: Source Email Address:        ***@gmail.com Destination Email Address:   ***@ti.com Email Subject:               CustomeEmailSubject Email Message:               MyEmailMessage
 * 5. Send the email by using the command sendemail. You should see the email being delivered within seconds after completion. The console prints out all conversation details for you to take a look at how messages are being exchanged between the client and the server.

command>>:sendemail

The sceenshot below shows the complete step-by-step process mentioned above.



Commands
A full list of all available commands for this application is listed below.

Usage: help [command name]
 * help

Description: To know more about the command name.

Available commands:

help               setemail            getemailconfig      clearemail

sendemail

Usage: setemail [-help] -d  -j -m
 * setemail

Description: Sets email content parameter. Note that source email configureation can only be done in the code. -d     The recipient's email address. -j     The email subject. -m     The email message. -help  Display this help.

Usage: getemailconfig [-help]
 * getemailconfig

Description: Gets the current email content. -help  Display this help.

Usage: clearemail [-help]
 * clearemail

Description: Clears all email content. -help  Display this help.

Usage: sendemail [-help]
 * sendemail

Description: Sends the email and clears local content. -help  Display this help.

Limitations/Known Issues
None