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 CC32xx, from one of the wide range of example applications provided by Texas Instruments.

Step 2 - Bind the device enable/disable output line

The CC31xx 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 CC31xx 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