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 <sdk_root_location>/platform/simplelinkstudio/library_project_vs/lib_smtp/Debug, and the source code is under <sdk_root_location>/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:<reverse-path> [SP <mail-parameters> ] <CRLF>
• Step 5: Sends the destination email to the SMTP server. RCPT TO:<forward-path> [ SP <rcpt-parameters> ] <CRLF>
• Step 6: Sends the "DATA" message to the server, indicates client is ready to construct the body of the email. DATA <CRLF>
• Step 7: Sends actual message, preceded by FROM, TO, Subject, Message, and end message with <CR><LF>.<CR><LF>
• 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 <sdk_root_location>/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

Usage

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 <sdk_root_location>/examples/email directory: <syntaxhighlight lang="c"> /* Predefined popular email services. */

1. define GMAIL_SERVER_ADDRESS "smtp.gmail.com" /* Google SMTP server. 465: SSL required, 587: TLS required */
2. define GMAIL_SERVER_PORT 587
3. define YAHOO_MAIL_SERVER_ADDRESS "smtp.mail.yahoo.com" /* Yahoo SMTP server. 465/587. SSL required */
4. define YAHOO_MAIL_SERVER_PORT 587
5. define OUTLOOK_MAIL_SERVER_ADDRESS "smtp-mail.outlook.com" /* Outlook.com SMTP server. 25/587. TLS required */
6. define OUTLOOK_MAIL_SERVER_PORT 587

/* Enter your source email account information */

1. define SRC_EMAIL_USERNAME "<username>@<domain>"
2. define SRC_EMAIL_PASSWORD "<password>"
3. define SRC_EMAIL_ADDRESS SRC_EMAIL_USERNAME
4. define SRC_EMAIL_SERVER_FAMILY SL_AF_INET
5. define SRC_EMAIL_SERVER_ADDRESS GMAIL_SERVER_ADDRESS /* Choose one from above, or enter your own value */
6. define SRC_EMAIL_SERVER_PORT GMAIL_SERVER_PORT /* Choose one from above, or enter your own value */
7. define SRC_EMAIL_SERVER_SECURITY SL_SO_SEC_METHOD_SSLv3_TLSV1_2
8. define SRC_EMAIL_SERVER_CIPHER SL_SEC_MASK_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
9. define SRC_EMAIL_SERVER_USE_STARTTLS 1 /* Set to 1 to enable STARTTLS */

/* Set the current device date and time in order to verify certificate coming from the email server */

1. define DEVICE_YEAR 2016
2. define DEVICE_MONTH 1
3. define DEVICE_DATE 1
4. define DEVICE_HOUR 0
5. define DEVICE_MINUTE 0
6. define DEVICE_SECOND 0

</syntaxhighlight>

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.

• help

Usage:
        help [command name]

Description:
        To know more about the command name.

Available commands:

help                setemail            getemailconfig      clearemail

sendemail

• setemail

Usage:
        setemail [-help] -d <recipient's email> -j <subject> -m <message>

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.

• getemailconfig

Usage:
        getemailconfig [-help]

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

• clearemail

Usage:
        clearemail [-help]

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

• sendemail

Usage:
        sendemail [-help]

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

Limitations/Known Issues

None