SimpleLink CC3120/CC3220 Host Driver  Version 2.0.1.18
Simplifies the implementation of Internet connectivity
SimpleLink Driver

Introduction

The SimpleLink(tm) CC31xx/CC32xx family allows to add Wi-Fi and networking capabilities to low-cost embedded products without having prior Wi-Fi, RF or networking expertise.
The CC31xx/CC32xx is an ideal solution for microcontroller-based sensor and control applications such as home appliances, home automation and smart metering.
The CC31xx/CC32xx has integrated a comprehensive TCP/IP network stack, Wi-Fi driver and security supplicant leading to easier portability to microcontrollers, to an ultra-low memory footprint, all without compromising the capabilities and robustness of the final application.

Module Names

To make it simple, TI's SimpleLink CC31xx/CC32xx platform capabilities were divided into modules by topic (Silo).
These capabilities range from basic device management through wireless network configuration, standard BSD socket and much more.
Listed below are the various modules in the SimpleLink CC31xx/CC32xx driver:

  1. Device - Controls the behaviour of the CC31xx/CC32xx device (start/stop, events masking and obtaining specific device status)
  2. FileSystem - Provides file system capabilities to TI's CC31XX that can be used by both the CC31XX device and the user.
  3. NetApp - Activates networking applications, such as: HTTP Server, DHCP Server, Ping, DNS and mDNS.
  4. NetCfg - Controls the configuration of the device addresses (i.e. IP and MAC addresses)
  5. NetUtil - Networking related commands and configuration
  6. Socket - Controls standard client/server sockets programming options and capabilities
  7. Wlan - Controls the use of the WiFi WLAN module including:
    • Connection features, such as: profiles, policies, SmartConfig(tm)
    • Advanced WLAN features, such as: scans, rx filters and rx statistics collection
  8. UserEvents - Function prototypes for event callback handlers

Persistency

The SimpleLink(tm) device support few different persistency types for settings and configurations:

  • Temporary - Effective immediately but returned to default after reset
  • System Persistent - Effective immediately and kept after reset according
    • to system persistent mode
  • Persistent - Effective immediately and kept after reset regardless the system persistent mode
  • Optionally Persistent- Effective immediately and kept after reset according to a parameter in the API call
  • Reset - Persistent but effective only after reset

    For all Set/Get function in this guide, the type of persistency per relevant parameters will be described as part of the function description

Porting Guide

The porting of the SimpleLink host driver to any new platform is based on few simple steps.
This guide takes you through this process step by step. Please follow the instructions carefully to avoid any problems during this process and to enable efficient and proper work with the device.
Please notice that all modifications and porting adjustments of the driver should be made in the user.h header file only. Keeping this method ensure smoothly transaction to new versions of the driver in the future!
The porting process consists of few simple steps:

  1. Create user.h for the target platform
  2. Select the capabilities set
  3. Bind the device enable/disable line
  4. Writing your interface communication driver
  5. Choose your memory management model
  6. OS adaptation
  7. Set your asynchronous event handlers
  8. Testing

For host interface details please refer to: https://processors.wiki.ti.com/index.php/CC31xx_Host_Interface

Please see the rest of the page for more details about the different steps.

Step 1 - Create your own user.h file

The first step is to create a user.h file that will include your configurations and adjustments.
The file should be located in the porting directory (the porting directory is in the same level as the source directory)
It is recommended to use the empty template provided as part of this driver or file of other platform such as MSP432 or CC3220, from one of the wide range of example applications provided by Texas Instruments.

Step 2 - Select the capabilities set required for your application

Texas Instruments built 3 different predefined sets of capabilities that would fit most of the target applications.
It is recommended to try and choose one of this predefined capabilities set before going to build your own customized set. If you find compatible set you can skip the rest of this step.

The available sets are:

  1. SL_TINY - Compatible to be used on platforms with very limited resources. Provides the best in class low foot print in terms of Code and Data consumption.
  2. SL_SMALL - Compatible to most common networking applications. Provide the most common APIs with decent balance between code size, data size, functionality and performances
  3. SL_FULL - Provide access to all SimpleLink functionalities

Step 3 - Bind the device enable/disable output line

The CC3120 has two external hardware lines that can be used to enable/disable the device.

  • nReset
  • nHib - provides mechanism to enter the device into the least current consumption mode. In this mode the RTC value is kept.

The driver manipulates the enable/disable line automatically during sl_Start / sl_Stop.
Not connecting one these lines means that the driver could start only once (sl_Stop will not work correctly and might lead to failure latter on) and the internal provisioning mechanism could not be used.
To bind these lines the following defines should be defined correctly:

  • sl_DeviceEnable
  • sl_DeviceDisable

If some initializations required before the enable/disable macros are called the user can use also the following optional define

  • sl_DeviceEnablePreamble

Step 4 - Writing your interface communication driver

The SimpleLink CC3120 has two standard communication interfaces

  • SPI
  • UART

The device detects automatically the active interface during initialization. After the detection, the second interface could not be used.
To wrap the driver for the communication channel the following functions should be implemented:

  1. sl_IfOpen
  2. sl_IfClose
  3. sl_IfRead
  4. sl_IfWrite
  5. sl_IfRegIntHdlr

The way these functions are implemented has direct effect on the performances of the SimpleLink device on this target platform. DMA and Jitter Buffer should be considered.
In some platforms the user need to mask the IRQ line when this interrupt could be masked.
The driver can call the mask/unmask whenever is needed. To allow this functionality the user should implement also the following defines:

  • sl_IfMaskIntHdlr
  • sl_IfUnMaskIntHdlr

By default the driver is writing the command in few transactions to allow zero-copy mechanism.
To enable a Jitter buffer for improving the communication line utilization, the can implement also the following defines:

  • sl_IfStartWriteSequence
  • sl_IfEndWriteSequence

Step 5 - Choose your memory management model

The SimpleLink driver support two memory models:

  • Static (default)
  • Dynamic

To enable the dynamic memory, the following pre-processor define should be set:
#define SL_MEMORY_MGMT_DYNAMIC

And the following macros should be defined and supplied:

  • sl_Malloc
  • sl_Free

Using the dynamic mode will allocate the required resources on sl_Start and release these resource on sl_Stop.

Step 6 - OS adaptation

The SimpleLink driver could run on two kind of platforms:

  1. Non-Os / Single Threaded (default)
  2. Multi-Threaded

When building a multi-threaded application. the following pre-processor define must be set:
#define SL_PLATFORM_MULTI_THREADED

If you choose to work in multi-threaded environment under operating system you will have to provide some basic adaptation routines to allow the driver to protect access to resources for different threads (locking object) and to allow synchronization between threads (sync objects). In additional the driver support running without dedicated thread allocated solely to the SimpleLink driver. If you choose to work in this mode, you should also supply a spawn method that will enable to run function on a temporary context.

Step 7 - Set your asynchronous event handlers routines

The SimpleLink device generate asynchronous events in several situations. These asynchronous events could be masked. In order to catch these events you have to provide handler routines. Please notice that if you not provide a handler routine and the event is received, the driver will drop this event without any indication of this drop.

Step 8 - Run diagnostic tools to validate the correctness of your porting

The driver is delivered with some porting diagnostic tools to simplify the porting validation process and to reduce issues latter. It is very important to follow carefully this process.

The diagnostic process include:

  1. Validating interface communication driver
  2. Validating basic work with the device

Annex Persistency

The SimpleLink(tm) device support few different persistency types for settings and configurations:

  • Temporary - Effective immediately but returned to default after reset
  • System Persistent - Effective immediately and kept after reset according
    • to system persistent mode
  • Persistent - Effective immediately and kept after reset regardless the system persistent mode
  • Optionally Persistent- Effective immediately and kept after reset according to a parameter in the API call
  • Reset - Persistent but effective only after reset

License

Copyright (C) 2016 Texas Instruments Incorporated - https://www.ti.com/

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

  Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

  Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the
  distribution.

  Neither the name of Texas Instruments Incorporated nor the names of
  its contributors may be used to endorse or promote products derived
  from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.