Texas Instruments SimpleLink Wi-Fi BoosterPack CC3120 Manual

CC3120, CC3220 SimpleLink™ Wi-Fi®and
Internet of Things Network Processor
Programmer's Guide
Literature Number: SWRU455A
February 2017–Revised March 2017

2SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
Contents
Contents
1 Overview........................................................................................................................... 12
1.1 Introduction.................................................................................................................. 12
1.2 Acronyms and Terminologies............................................................................................. 15
1.3 Key Features................................................................................................................ 15
1.4 Host Driver Overview ...................................................................................................... 16
1.4.1 Host Interface...................................................................................................... 16
1.4.2 OS versus Non-OS................................................................................................ 17
1.4.3 Quick Reference................................................................................................... 17
1.4.4 Porting to Different Platforms.................................................................................... 19
2 Networking Application....................................................................................................... 20
2.1 Introduction.................................................................................................................. 21
2.1.1 Wi-Fi Connectivity................................................................................................. 21
2.1.2 Traffic Types ....................................................................................................... 22
2.1.3 Security............................................................................................................. 23
2.1.4 User Experience................................................................................................... 23
2.1.5 Power Consumption .............................................................................................. 23
2.1.6 Provisioning........................................................................................................ 24
2.2 Basic Examples ............................................................................................................ 24
2.2.1 Wi-Fi Doorbell ..................................................................................................... 24
2.2.2 Power Socket ..................................................................................................... 24
2.2.3 Wi-Fi Tag........................................................................................................... 25
3 Device............................................................................................................................... 26
3.1 Introduction.................................................................................................................. 27
3.2 Key Features................................................................................................................ 27
3.3 Start and Stop .............................................................................................................. 27
3.3.1 Start................................................................................................................. 27
3.3.2 Stop ................................................................................................................. 27
3.3.3 Hibernate and Shutdown......................................................................................... 28
3.3.4 Lock State.......................................................................................................... 28
3.3.5 Initialization Sequence............................................................................................ 28
3.4 Host Interface............................................................................................................... 29
3.4.1 SPI Interface ....................................................................................................... 29
3.4.2 UART Interface .................................................................................................... 30
3.5 Version....................................................................................................................... 32
3.6 Event Mask.................................................................................................................. 32
3.7 Time and Date.............................................................................................................. 32
3.8 MAC Address............................................................................................................... 33
3.9 Device Name................................................................................................................ 33
3.10 Domain Name .............................................................................................................. 34
3.11 Device Status............................................................................................................... 34
3.12 Persistent Configuration................................................................................................... 35
3.13 Errors ........................................................................................................................ 35
4 WLAN ............................................................................................................................... 37
4.1 Introduction.................................................................................................................. 38
4.2 Key Features................................................................................................................ 38

www.ti.com
3
SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback Copyright © 2017, Texas Instruments Incorporated
Contents
4.3 Station (STA)................................................................................................................ 38
4.3.1 General Description............................................................................................... 38
4.3.2 Configurations and Settings...................................................................................... 38
4.3.3 Connection ......................................................................................................... 41
4.3.4 Events and Errors................................................................................................. 44
4.4 Access Point ................................................................................................................ 45
4.4.1 General Description............................................................................................... 45
4.4.2 Configurations and Settings...................................................................................... 45
4.4.3 Set Network Configuration ....................................................................................... 50
4.4.4 Station Management.............................................................................................. 51
4.4.5 Events and Errors................................................................................................. 52
4.4.6 Limitations.......................................................................................................... 52
4.5 Wi-Fi Direct.................................................................................................................. 53
4.5.1 General Description............................................................................................... 53
4.5.2 Supported Features............................................................................................... 53
4.5.3 Configurations and Settings...................................................................................... 53
4.5.4 Connection ......................................................................................................... 57
4.5.5 Events and Errors................................................................................................. 60
4.5.6 Limitations.......................................................................................................... 62
4.6 WLAN Security ............................................................................................................. 62
4.6.1 Personal Security.................................................................................................. 62
4.6.2 Enterprise Security................................................................................................ 63
4.6.3 WPS................................................................................................................. 65
4.7 Scan.......................................................................................................................... 66
4.7.1 General Description............................................................................................... 66
4.7.2 Configuration (AP/STA)........................................................................................... 66
4.7.3 Usage............................................................................................................... 67
4.7.4 Miscellaneous...................................................................................................... 67
4.8 Calibrations.................................................................................................................. 67
5 Network Addresses ............................................................................................................ 69
5.1 Introduction.................................................................................................................. 70
5.2 Key Features................................................................................................................ 70
5.3 Addressing .................................................................................................................. 70
5.3.1 IPv4 Addresses.................................................................................................... 71
5.3.2 IPv6 Addresses.................................................................................................... 72
5.3.3 DNS Addresses.................................................................................................... 73
5.4 DHCPv4 client .............................................................................................................. 73
5.4.1 Modes............................................................................................................... 73
5.4.2 Address Release .................................................................................................. 74
5.5 DHCPv4 Server............................................................................................................. 75
5.5.1 Enable and Disable the DHCP Server ......................................................................... 75
5.5.2 Set DHCP Server Parameters .................................................................................. 75
5.6 DNS Server ................................................................................................................. 76
5.7 Errors and Asynchronous Events ....................................................................................... 76
6 Socket............................................................................................................................... 79
6.1 Introduction.................................................................................................................. 80
6.2 Key Features................................................................................................................ 80
6.3 Socket Types ............................................................................................................... 80
6.4 BSD API..................................................................................................................... 81
6.5 Socket Working Flow ...................................................................................................... 82
6.5.1 TCP ................................................................................................................. 82
6.5.2 UDP................................................................................................................. 86
6.5.3 RAW ................................................................................................................ 88

www.ti.com
4SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
Contents
6.6 DNS.......................................................................................................................... 90
6.7 Operation Modes........................................................................................................... 91
6.7.1 Nonblocking Mode ................................................................................................ 91
6.7.2 Trigger Mode....................................................................................................... 92
6.8 IP Fragmentation........................................................................................................... 95
6.9 Errors ........................................................................................................................ 95
7 Secure Socket.................................................................................................................... 97
7.1 Introduction.................................................................................................................. 98
7.2 Key Features................................................................................................................ 98
7.3 Opening a Secure Socket................................................................................................. 98
7.4 Trusted Root-Certificate Catalog......................................................................................... 99
7.5 Options and Features Use................................................................................................ 99
7.5.1 Set SSL Version................................................................................................... 99
7.5.2 Set Cipher Suites ................................................................................................ 100
7.5.3 Set Certificates, Root CA, Private Key, and DH Files ...................................................... 100
7.5.4 Disable the Use of the Trusted Root-Certificate Catalog................................................... 101
7.5.5 Set ALPN List .................................................................................................... 102
7.5.6 Set Domain Name for Verification............................................................................. 102
7.5.7 Upgrade Nonsecured Socket to Secured..................................................................... 102
7.5.8 Get Connection Parameters.................................................................................... 104
7.6 Supported Cryptographic Algorithms................................................................................... 104
7.7 Common Errors and Asynchronous Events........................................................................... 105
7.7.1 Using Socket Asynchronous Events in SSL.................................................................. 105
7.7.2 Common Errors .................................................................................................. 106
8 File System...................................................................................................................... 107
8.1 Introduction ................................................................................................................ 110
8.2 Key Features .............................................................................................................. 110
8.3 File System Characteristics ............................................................................................. 111
8.4 Write a File................................................................................................................. 111
8.4.1 Introduction ....................................................................................................... 111
8.4.2 Create a File versus Open for Write .......................................................................... 112
8.4.3 Create a File...................................................................................................... 113
8.4.4 Open a File for Write ............................................................................................ 115
8.4.5 Write an Opened File............................................................................................ 115
8.4.6 Close an Opened (for Write) File .............................................................................. 116
8.4.7 Close an Opened (for Write) Secure-Signed File ........................................................... 117
8.5 Read a File ................................................................................................................ 118
8.5.1 Open a File for Read............................................................................................ 118
8.5.2 Read an Opened File ........................................................................................... 118
8.5.3 Close an Opened (for Read) File.............................................................................. 119
8.6 Delete a File............................................................................................................... 119
8.7 Rename a File............................................................................................................. 120
8.8 File System Helper Functions........................................................................................... 120
8.8.1 Get File Information ............................................................................................. 120
8.8.2 Get Storage Information ........................................................................................ 121
8.8.3 Get List of Files .................................................................................................. 121
8.9 Bundle Protection......................................................................................................... 121
8.9.1 Bundle File States ............................................................................................... 122
8.9.2 Bundle States .................................................................................................... 123
8.9.3 Commit a Bundle ................................................................................................ 124
8.9.4 Rollback a Bundle ............................................................................................... 124
8.9.5 Retrieve the Bundle and Files State........................................................................... 124
8.9.6 CC3220 Bundle Aspects........................................................................................ 124

www.ti.com
5
SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback Copyright © 2017, Texas Instruments Incorporated
Contents
8.10 File Commit Feature...................................................................................................... 125
8.10.1 File Commit Process ........................................................................................... 125
8.11 File Rollback Process .................................................................................................... 126
8.12 Programming.............................................................................................................. 126
8.12.1 Creation of the Programming Image......................................................................... 126
8.13 Restore to Factory........................................................................................................ 128
8.13.1 Restore to Factory by the Host ............................................................................... 129
8.13.2 Restore to Factory by Using the SOP ....................................................................... 130
8.14 Security Alerts............................................................................................................. 131
8.15 Design Consideration .................................................................................................... 131
8.15.1 Choosing SFLASH Type....................................................................................... 131
8.15.2 Software Design Consideration............................................................................... 131
8.15.3 Retrieving Info Regarding SFLASH Usage.................................................................. 132
8.15.4 SFLASH Size.................................................................................................... 132
8.15.5 Storage Usage Information ................................................................................... 133
9 HTTP Server..................................................................................................................... 134
9.1 Introduction ................................................................................................................ 137
9.1.1 Built-in Configuration Pages.................................................................................... 137
9.1.2 RESTful APIs..................................................................................................... 137
9.1.3 Custom Static Pages............................................................................................ 138
9.1.4 Host Application Interface ...................................................................................... 140
9.2 Key Features .............................................................................................................. 140
9.3 Configurations and Settings............................................................................................. 141
9.4 RESTful API Processing................................................................................................. 142
9.4.1 Ping................................................................................................................ 142
9.4.2 IP Configuration.................................................................................................. 142
9.4.3 URN Configuration............................................................................................... 143
9.4.4 WLAN Profiles.................................................................................................... 143
9.4.5 WLAN Scan....................................................................................................... 144
9.4.6 Provisioning Confirmation ...................................................................................... 145
9.4.7 Connection Policy................................................................................................ 145
9.4.8 Station Action..................................................................................................... 145
9.4.9 AP Black List ..................................................................................................... 145
9.4.10 Date and Time .................................................................................................. 146
9.5 Device Parameter Querying Through HTTP (Device Tokens)...................................................... 146
9.5.1 Retrieving Tokens Through GET Request ................................................................... 147
9.5.2 Embedded Tokens............................................................................................... 147
9.5.3 System Information.............................................................................................. 147
9.5.4 Version Information.............................................................................................. 148
9.5.5 Network Information............................................................................................. 148
9.5.6 Ping Results...................................................................................................... 150
9.5.7 Connection Policy Status ....................................................................................... 150
9.5.8 Provisioning....................................................................................................... 151
9.5.9 Display Profile Information...................................................................................... 151
9.5.10 P2P Information................................................................................................. 151
9.5.11 Host Tokens..................................................................................................... 153
9.6 Resource Search Order.................................................................................................. 153
9.6.1 GET Request Search Order.................................................................................... 153
9.6.2 POST Request Search Order.................................................................................. 154
9.6.3 PUT and DELETE Request Search Order ................................................................... 154
9.7 Host HTTP Requests Processing....................................................................................... 154
9.7.1 Metadata (TLVs) Description................................................................................... 155
9.7.2 GET Processing.................................................................................................. 157

www.ti.com
6SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
Contents
9.7.3 POST Processing................................................................................................ 160
9.7.4 PUT Processing.................................................................................................. 164
9.7.5 DELETE Processing............................................................................................. 164
9.8 Security..................................................................................................................... 164
9.8.1 Authentication .................................................................................................... 164
9.8.2 Secure Connection .............................................................................................. 164
9.9 Other........................................................................................................................ 165
9.9.1 Processing of Parallel Requests............................................................................... 165
10 mDNS.............................................................................................................................. 166
10.1 Introduction ................................................................................................................ 167
10.2 Key Features .............................................................................................................. 167
10.3 Configurations and Settings............................................................................................. 167
10.4 Query....................................................................................................................... 168
10.4.1 One Shot Query................................................................................................. 168
10.4.2 Continuous Query .............................................................................................. 168
10.4.3 Mask Services................................................................................................... 168
10.5 Get Service List ........................................................................................................... 169
10.6 Advertisement............................................................................................................. 170
10.6.1 Registering mDNS Services................................................................................... 170
10.6.2 Unregistering mDNS Services ................................................................................ 170
10.6.3 Advertisement Settings ........................................................................................ 171
10.7 Limitations ................................................................................................................. 172
11 Rx Filters......................................................................................................................... 173
11.1 Introduction ................................................................................................................ 174
11.2 Matching Process......................................................................................................... 175
11.2.1 Filter Matching .................................................................................................. 175
11.2.2 Tree Traversal................................................................................................... 177
11.3 Examples of Filter Use................................................................................................... 178
11.3.1 Example 1 ....................................................................................................... 178
11.3.2 Example 2 ....................................................................................................... 178
11.4 Filter Creation ............................................................................................................. 179
11.4.1 Filter Type ....................................................................................................... 179
11.4.2 Filter Flags....................................................................................................... 179
11.4.3 Rule Structure for Header Filters ............................................................................. 180
11.4.4 Rule Structure for Combined Filters.......................................................................... 184
11.4.5 Filter Trigger..................................................................................................... 184
11.4.6 Rx Filter Action.................................................................................................. 187
11.5 Managing Filters .......................................................................................................... 189
11.5.1 Enable and Disable Filters..................................................................................... 189
11.5.2 Get Filter Status................................................................................................. 189
11.5.3 Removing a Filter............................................................................................... 190
11.5.4 Storing Filters into the SFLASH .............................................................................. 190
11.5.5 Update Filter Arguments....................................................................................... 190
12 Ping ................................................................................................................................ 191
12.1 General Description ...................................................................................................... 192
12.2 Start and Stop Ping....................................................................................................... 192
12.3 Limitations ................................................................................................................. 193
13 Transceiver...................................................................................................................... 194
13.1 Introduction ................................................................................................................ 195
13.2 Key Features .............................................................................................................. 195
13.3 Configurations and Setting .............................................................................................. 195
13.3.1 Open Transceiver Socket...................................................................................... 195

www.ti.com
7
SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback Copyright © 2017, Texas Instruments Incorporated
Contents
13.3.2 Close Transceiver Socket ..................................................................................... 196
13.3.3 Send Data ....................................................................................................... 196
13.3.4 Receive Data.................................................................................................... 197
13.4 Internal Packet Generator ............................................................................................... 197
13.5 CW.......................................................................................................................... 198
13.6 Changing Socket Properties............................................................................................. 198
13.6.1 Change Operating Channel ................................................................................... 198
13.6.2 Change Default PHY Data Rate.............................................................................. 199
13.6.3 Change Tx Power .............................................................................................. 200
13.6.4 Change Number of Frames to Transmit (Internal Packet Generator) ................................... 200
13.6.5 Change 802.11b Preamble.................................................................................... 200
13.6.6 Set CCA Threshold............................................................................................. 200
13.6.7 Set Tx Frames Time-out....................................................................................... 201
13.6.8 Enable or Disable Sending ACKs ............................................................................ 201
13.7 Limitations ................................................................................................................. 201
14 Power Managment ............................................................................................................ 202
14.1 Introduction ................................................................................................................ 203
14.1.1 LPDS ............................................................................................................. 203
14.1.2 802.11 Power Save............................................................................................. 203
14.1.3 Low Power versus Latency.................................................................................... 203
14.1.4 Power Modes versus Device Modes......................................................................... 203
14.2 Key Features .............................................................................................................. 203
14.3 Configurations and Settings............................................................................................. 204
14.3.1 Changing Power Policy ........................................................................................ 204
14.3.2 Enabling Fast Connect......................................................................................... 204
14.4 Network Applications and Power Consumption....................................................................... 204
14.4.1 mDNS ............................................................................................................ 204
14.4.2 HTTP Server .................................................................................................... 204
14.5 Design Guidelines ........................................................................................................ 205
14.5.1 LSI and Packet Loss ........................................................................................... 205
14.5.2 PHY Calibration Mode ......................................................................................... 205
15 Provisioning..................................................................................................................... 206
15.1 Introduction ................................................................................................................ 207
15.2 Key Features .............................................................................................................. 207
15.3 Provisioning Process Overview......................................................................................... 207
15.3.1 Configuring a Profile............................................................................................ 207
15.3.2 Confirming a Profile ............................................................................................ 207
15.4 Host Provisioning Application Flow..................................................................................... 208
15.5 Configuration Modes ..................................................................................................... 210
15.5.1 AP Provisioning................................................................................................. 210
15.5.2 SC Provisioning................................................................................................. 210
15.5.3 AP and SC Provisioning ....................................................................................... 210
15.5.4 AP and SC and External Configuration Provisioning ...................................................... 210
15.6 Starting and Stopping the Provisioning Process...................................................................... 210
15.7 Auto-Provisioning ......................................................................................................... 211
15.8 Delivering Feedback to the User ....................................................................................... 211
15.8.1 External Confirmation .......................................................................................... 212
15.9 External Configuration.................................................................................................... 212
15.10 Common Events and Errors ............................................................................................ 213
15.10.1 Provisioning Status Event.................................................................................... 213
15.10.2 Provisioning Profile-Added Event ........................................................................... 214
15.10.3 Reset Request Event......................................................................................... 214
15.10.4 Errors ........................................................................................................... 214

www.ti.com
8SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
Contents
15.10.5 Host Commands During Provisioning ...................................................................... 214
15.11 Usage Examples ......................................................................................................... 216
15.11.1 Successful SmartConfig Provisioning ...................................................................... 216
15.11.2 Unsuccessful SmartConfig Provisioning ................................................................... 217
15.11.3 Successful SmartConfig Provisioning With AP Fallback................................................. 218
15.11.4 Successful AP Provisioning.................................................................................. 219
15.11.5 Successful AP Provisioning With Cloud Confirmation.................................................... 220
15.11.6 Using External Configuration Method: WAC............................................................... 221
15.11.7 Successful SmartConfig Provisioning While External Configuration Enabled......................... 222
16 Crypto Utilities ................................................................................................................. 223
16.1 Introduction ................................................................................................................ 224
16.1.1 API and Usage.................................................................................................. 224
16.1.2 Limitations and Constraints.................................................................................... 227
16.1.3 Errors............................................................................................................. 227
16.2 Secured Content Delivery ............................................................................................... 228
16.2.1 Process Flow.................................................................................................... 228
16.2.2 Encrypted File Format.......................................................................................... 230
17 Porting the Host Driver...................................................................................................... 231
17.1 Introduction ................................................................................................................ 232
17.2 Create Platform Porting File............................................................................................. 233
17.3 Select Capabilities Set ................................................................................................... 233
17.4 Bind the Device Enable/Disable Line .................................................................................. 235
17.5 Implement the Interface Communication Abstract Layer............................................................ 235
17.6 Choose Memory-Management Model.................................................................................. 237
17.7 Implement OS Adaptation Layer........................................................................................ 237
17.7.1 Sync Objects .................................................................................................... 237
17.7.2 Locking Objects................................................................................................. 238
17.8 Implement Timestamp Services ........................................................................................ 238
17.9 Set Asynchronous Event Handler Routines........................................................................... 238
A Host APIs......................................................................................................................... 240
B Persistency...................................................................................................................... 242
Revision History........................................................................................................................ 246

www.ti.com
9
SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback Copyright © 2017, Texas Instruments Incorporated
List of Figures
List of Figures
1-1. SimpleLink Wi-Fi Solution Block Diagram............................................................................... 13
1-2. Networking Subsystem Block Diagram.................................................................................. 14
1-3. Quick Host APIs Reference............................................................................................... 18
1-4. Host Driver Adaptation Modules (Platform-Dependent)............................................................... 19
2-1. Wi-Fi Connectivity.......................................................................................................... 22
3-1. Typical CC3120 Setup (SPI).............................................................................................. 30
3-2. Typical CC3120 Setup (UART)........................................................................................... 31
4-1. Tx Output Power vs Tx Power Settings................................................................................. 40
5-1. DHCPv4 IP Acquisition Modes ........................................................................................... 74
6-1. TCP Socket Flow........................................................................................................... 83
6-2. UDP Socket Flow........................................................................................................... 86
6-3. Trigger Mode Flow ......................................................................................................... 93
8-1. Image Creator Log........................................................................................................ 133
9-1. Configuration Pages...................................................................................................... 137
9-2. Changing Configuration.................................................................................................. 138
9-3. Reading Configuration ................................................................................................... 138
9-4. Static Pages............................................................................................................... 139
9-5. Custom Pages With Device Tokens.................................................................................... 139
9-6. Static Pages With Host Tokens......................................................................................... 140
9-7. Host Application Interface ............................................................................................... 140
9-8. GET Request Flow ....................................................................................................... 153
9-9. POST Request Flow...................................................................................................... 154
9-10. PUT and DELETE Request Flow....................................................................................... 154
9-11. GET Request With and Without Fragmentation ...................................................................... 157
9-12. POST Processing Flow .................................................................................................. 160
9-13. Delayed Response ....................................................................................................... 162
11-1. Rx Filters................................................................................................................... 175
11-2. Rx Filter Match Flow...................................................................................................... 176
11-3. Example 1 ................................................................................................................. 178
11-4. Example 2 ................................................................................................................. 179
15-1. The Provisioning Environment .......................................................................................... 208
15-2. The Provisioning Process................................................................................................ 209
15-3. Successful SmartConfig Provisioning.................................................................................. 216
15-4. Unsuccessful SmartConfig Provisioning............................................................................... 217
15-5. Successful SmartConfig Provisioning With AP Fallback ............................................................ 218
15-6. Successful AP Provisioning ............................................................................................. 219
15-7. Successful AP Provisioning With Cloud Confirmation ............................................................... 220
15-8. External Configuration Method: WAC.................................................................................. 221
15-9. Successful SmartConfig Provisioning While External Configuration Enabled.................................... 222
16-1. Secure Content Delivery................................................................................................. 229
16-2. File Format................................................................................................................. 230
17-1. User.h Location ........................................................................................................... 233

www.ti.com
10 SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
List of Tables
List of Tables
1-1. Acronyms and Terminologies............................................................................................. 15
1-2. Key Features................................................................................................................ 15
1-3. Software Modules of the Host Driver .................................................................................... 16
2-1. Design Considerations for Doorbell Applications ...................................................................... 24
2-2. Design Considerations for Power Socket Application ................................................................. 25
2-3. Design Considerations for Tag Applications............................................................................ 25
3-1. Key Features................................................................................................................ 27
3-2. SPI Configuration........................................................................................................... 29
3-3. UART Settings.............................................................................................................. 30
3-4. Common Asynchronous Error Events................................................................................... 35
3-5. Common Error Codes ..................................................................................................... 36
4-1. Key Features................................................................................................................ 38
4-2. Default Parameters in Station Mode..................................................................................... 39
4-3. Common Errors............................................................................................................. 44
4-4. AP Default Parameters.................................................................................................... 45
4-5. Common Errors............................................................................................................. 52
4-6. Wi-Fi Direct Default Parameters.......................................................................................... 53
4-7. Common Errors............................................................................................................. 61
4-8. Supported Personal Security Types ..................................................................................... 62
4-9. Calibration Modes.......................................................................................................... 68
5-1. Key Features................................................................................................................ 70
5-2. Addressing .................................................................................................................. 70
5-3. DHCP Server Defaults..................................................................................................... 75
5-4. Major Asynchronous Events in NetApp Silo............................................................................ 76
5-5. Major Asynchronous Events in NetCfg Silo............................................................................. 77
5-6. Major Errors While Calling sl_NetCfgSet................................................................................ 77
6-1. Key Features................................................................................................................ 80
6-2. BSD APIs.................................................................................................................... 81
6-3. Multicast ..................................................................................................................... 88
6-4. Operational Modes......................................................................................................... 91
6-5. Asynchronous Error Events............................................................................................... 96
6-6. Common Error Status Codes............................................................................................. 96
7-1. Key Features................................................................................................................ 98
7-2. Related Files .............................................................................................................. 101
7-3. Cryptographic Algorithms................................................................................................ 105
7-4. Common Errors ........................................................................................................... 106
8-1. Key Features .............................................................................................................. 110
8-2. Secure Files ............................................................................................................... 111
8-3. Creation Flags............................................................................................................. 114
8-4. Bundle Protection......................................................................................................... 122
8-5. Bundle States ............................................................................................................. 123
9-1. Key Features .............................................................................................................. 140
9-2. Configuration Options .................................................................................................... 141
9-3. Ping Options............................................................................................................... 142
9-4. IP Configurations.......................................................................................................... 142
9-5. URN Configurations ...................................................................................................... 143
9-6. WLAN Profiles............................................................................................................. 143

www.ti.com
11
SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback Copyright © 2017, Texas Instruments Incorporated
List of Tables
9-7. WLAN EAP Profiles ...................................................................................................... 144
9-8. Erase Profiles ............................................................................................................. 144
9-9. WLAN Scan................................................................................................................ 144
9-10. Connection Policies....................................................................................................... 145
9-11. Station Action.............................................................................................................. 145
9-12. AP Control ................................................................................................................. 146
9-13. Date and Time ............................................................................................................ 146
9-14. System Information Tokens ............................................................................................. 147
9-15. Version Information Tokens ............................................................................................. 148
9-16. Network Information Tokens ............................................................................................ 148
9-17. Ping Results Tokens ..................................................................................................... 150
9-18. Connection Policies Status Tokens .................................................................................... 150
9-19. Provisioning Tokens...................................................................................................... 151
9-20. Display Profile Information Tokens..................................................................................... 151
9-21. P2P Information Tokens ................................................................................................. 152
9-22. TLV Structure.............................................................................................................. 155
9-23. HTTP Metadata Types................................................................................................... 155
9-24. Internal Metadata Types................................................................................................. 155
9-25. Metadata Breakout Examples........................................................................................... 156
10-1. Key Features .............................................................................................................. 167
11-1. Possible Triggers ......................................................................................................... 176
11-2. Possible Rules ............................................................................................................ 177
11-3. Possible Actions .......................................................................................................... 177
11-4. Possible Compare Functions............................................................................................ 181
11-5. Rule Types................................................................................................................. 182
11-6. Rule Types Layers........................................................................................................ 185
13-1. Key Features .............................................................................................................. 195
14-1. Power and Latency....................................................................................................... 203
14-2. Key Features .............................................................................................................. 203
14-3. Power Policy............................................................................................................... 204
15-1. Key Features .............................................................................................................. 207
15-2. Provisioning Status ....................................................................................................... 213
15-3. Errors....................................................................................................................... 214
16-1. Key Features .............................................................................................................. 224
16-2. Common Errors ........................................................................................................... 227
17-1. : Selecting Capabilities................................................................................................... 234
A-1. Host APIs .................................................................................................................. 240
B-1. Persistency Settings...................................................................................................... 242

12 SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
Overview
SimpleLink, Internet-on-a chip, Texas Instruments, SmartConfig are trademarks of Texas Instruments.
ARM, Cortex are registered trademarks of ARM Limited.
Bluetooth is a registered trademark of Bluetooth SIG, Inc.
Google is a registered trademark of Google, Inc.
Wi-Fi, Wi-Fi Direct are registered trademarks of Wi-Fi Alliance.
All other trademarks are the property of their respective owners.
Chapter 1
SWRU455A–February 2017–Revised March 2017
Overview
The CC3120 and CC3220 devices are part of the SimpleLink™ microcontroller (MCU) platform which
consists of Wi-Fi®,Bluetooth®low energy, Sub-1 GHz and host MCUs, which all share a common, easy-
to-use development environment with a single core software development kit (SDK) and rich tool set. A
one-time integration of the SimpleLink platform enables you to add any combination of the portfolio’s
devices into your design, allowing 100 percent code reuse when your design requirements change. For
more information, visit www.ti.com/simplelink.
The SimpleLink Wi-Fi Internet-on-a chip™ family of devices from Texas Instruments™ provides a suite of
integrated protocols for Wi-Fi and Internet connectivity, to dramatically simplify the implementation of
Internet-enabled devices and applications.
This document provides software (SW) programmers with all of the required knowledge for working with
the networking subsystem of the SimpleLink Wi-Fi devices. This guide provides basic guidelines for writing
robust, optimized networking host applications, and describes the capabilities of the networking
subsystem. The guide contains some example code snapshots, to give users an idea of how to work with
the host driver. More comprehensive code examples can be found in the formal software development kit
(SDK). This guide does not provide a detailed description of the host driver APIs.
This chapter gives a brief introduction to the networking subsystem, lists the key features of the device,
and provides an overview of the host driver.
1.1 Introduction
The SimpleLink Wi-Fi CC3120 wireless network processor allows the connection of any low-cost, low-
power microcontroller (MCU) to the Internet of Things (IoT), using standard communication interfaces
such as SPI or UART.
The SimpleLink Wi-Fi CC3220x is a wireless MCU with an integrated high-performance ARM®Cortex®-M4
MCU, built-in Wi-Fi, and a networking subsystem, allowing developers to write an entire application with a
single-chip solution.
The CC3120 and CC3220 devices are the second generation of TI’s Internet-on-a chip solutions. This
generation introduces new features and capabilities that further simplify connectivity of devices to the
Internet. The new capabilities include:
• Support for IPv6
• Improved Wi-Fi provisioning
• Improved power consumption
• More concurrent opened BSD and SSL/TLS sockets
• HTTPS – Integrated secure http server
• File system security capabilities
• Image programming
• Wi-Fi access point (AP) with support of up to four stations

WLAN
Networking Subsystem
Host Interface
Network Stack
Network Applications
Services
Host
6LPSOH/LQNŒ+RVW'ULYHU
SPI/UART
Device Wlan NetApp NetCfg NetUtil FSSocket
www.ti.com Introduction
13
SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback Copyright © 2017, Texas Instruments Incorporated
Overview
Figure 1-1 shows a block diagram of the SimpleLink Wi-Fi solution at a high level.
Figure 1-1. SimpleLink Wi-Fi Solution Block Diagram
In the CC3220 wireless MCU the host is a Cortex-M4 core, the networking subsystem is built into the
device as an additional peripheral, and the interface between the Cortex-M4 Core and the networking
subsystem is internal.
The host driver is the same for the CC3120 and CC3220, and the networking capabilities are similar for
both devices. The network stack is fully implemented in the networking subsystem, thereby offloading the
networking activities from the host MCU.
A simple application that only sends a UDP datagram on the local network requires minimum APIs as
follows:
sl_Start Start the SimpleLink device in Wi-Fi Station mode
sl_WlanConnect Connect to a Wi-Fi network
sl_Socket Create a socket
sl_SendTo Sends UDP data
sl_Close Close the socket
sl_Stop Stops the SimpleLink device
NOTE: The target application can choose to use the preferred networks option (profiles), instead of
using the sl_WlanConnect command. This option allows the host application to completely
offload the entire management of the WLAN connection.

WLAN
Networking Subsystem
Host Interface
Secure FS
STA APP2P
IPv6
Network Stack
Network ApplicationsServices
Scan Policy
Programming
Secure Content Delivery
DHCP Client/Server
MDNS
HTTP Server
Transceiver / NS
Bypass IPv4
ICMP IGMP IPv6 ICMP/NDP MLD
Ping
DNS
TCP UDP
Rx Filter
RAW
BSD SSL
ARP
PM Policy
Provisioning
Host
SPI/UART
Secure FS
Time and Date
(RTC)
Crypto Util
6LPSOH/LQNŒ+RVW'ULYHU
Interface(SPI/UART) Driver OS Adaptation Layer
Device Wlan NetApp NetCfg NetUtil FSSocket
Introduction www.ti.com
14 SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
Overview
Figure 1-2 shows a more detailed block diagram of the networking subsystem.
Figure 1-2. Networking Subsystem Block Diagram

www.ti.com Acronyms and Terminologies
15
SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback Copyright © 2017, Texas Instruments Incorporated
Overview
1.2 Acronyms and Terminologies
Table 1-1 lists the acronyms and terms used in this document.
Table 1-1. Acronyms and Terminologies
Acronym/Terminology Description
Host Host refers to an embedded MCU running the SimpleLink software driver and uses the SimpleLink
device as a networking peripheral
AP Wi-Fi access point
STA Wi-Fi station
FW Firmware software
LAN Local area network
WLAN Wireless local area network
IE Information element
OUI Organization unique identifier
P2P Wi-Fi Direct®or peer-to-peer (P2P)
GO Wi-Fi Direct group owner
OS Operating system
1.3 Key Features
Table 1-2 lists the key features of the CC3120 and CC3220 devices.
Table 1-2. Key Features
Feature Description
Wi-Fi standards 802.11b/g/n station
802.11b/g access point with support for up to four stations
Wi-Fi Direct client / group owner
Wi-Fi channels 1–13
Personal and Enterprise
Wi-Fi security WEP, WPA/WPA2 PSK, WPA2 Enterprise (802.1x)
Wi-Fi provisioning SmartConfig™ technology, Wi-Fi Protected Setup (WPS2), access point mode with internal HTTP
web server
IP protocols IPv4/IPv6
IP addressing Static IP, LLA, DHCPv4, DHCPv6 with DAD
Cross layer ARP, ICMPv4, IGMP, ICMPv6, MLD, NDP
Transport UDP, TCP
SSLv3.0/TLSv1.0/TLSv1.1/TLSv1.2
RAW
Network applications and
utilities Ping
HTTP/HTTPS web server (including dynamic user call backs and RESTful API support)
mDNS
DNS-SD
DHCP server
Host interface UART/SPI

Host Driver Overview www.ti.com
16 SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
Overview
Table 1-2. Key Features (continued)
Feature Description
Security Secure key storage
Trusted root-certificate catalog
TI root-of-trust public key
File system security
Secure boot
Secure content delivery
Initial secure programming
Debug security
Software tamper detection
Cloning protection
Power management Enhanced power policy management uses 802.11 power save, and deep-sleep power modes
Other Transceiver
Programmable Rx filters with events trigger mechanism
1.4 Host Driver Overview
The SimpleLink Wi-Fi Internet-on-a chip devices provide comprehensive networking functionality that
offloads networking activities from the host MCU. TI provides a user-friendly host-software driver to
simplify the integration and development of networking applications using the SimpleLink Wi-Fi devices.
This host driver can easily be ported to most platforms and operating systems (OSs). The host driver is
written in strict ANSI-C (C89) and requires a minimal platform adaptation layer (porting layer).
The driver has a small memory footprint, and can run on 8-, 16-, or 32-bit MCUs with any clock speed (no
performance or real-time dependency). Using SPI, both big- and little-endian MCUs are seamlessly
supported. With UART, only little endian is supported.
The APIs of the SimpleLink host driver are arranged in several logical and simple modules (silos).
Table 1-3 provides a high-level description of these silos.
Table 1-3. Software Modules of the Host Driver
Silo Description
Device Provides interface to hardware and general functionality, such as start/stop or set, and get configurations in the device
level
WLAN Provides interface to WLAN 802.11 protocol-related functionality, such as mode (station, access point, or Wi-Fi
Direct), provisioning, connection profiles, and connection policy
Socket Provides interface to sockets and adheres to BSD sockets. BSD sockets are the most common interface today for
internet connectivity.
NetApp Provides interface to several networking services including the HTTP server service, DHCP server service, and
MDNS client\server service
NetCfg Provides interface to configure different networking parameters, such as setting the MAC address and IP address
settings (DHCP/Static)
NetUtil Provides interface to several network utilities, such as crypto utility, which provides a method for authenticating the
device
FS Provides interface for storing and reading files through a secure file system managed on the serial flash component
1.4.1 Host Interface
The SimpleLink device supports two physical host interfaces: SPI and UART. The same host driver can
work with each of these interfaces by using an interface driver adaptation layer.
More information on the adaptation layer is in the host interface section, see Chapter 3 and Chapter 17.

www.ti.com Host Driver Overview
17
SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback Copyright © 2017, Texas Instruments Incorporated
Overview
1.4.2 OS versus Non-OS
The same driver can work on platforms running an OS, and platforms without an operating system (non-
OS).
An OS adaptation layer is used for binding the host driver and the target OS. The driver already comes
with a built-in adaptation layer for platforms running without an OS. Other platforms require a simple OS
adaptation layer.
This adaptation layer must wrap two major objects:
• Sync object – Object intended to synchronize between different contexts and interrupt routines
• Lock object – Object intended to protect a shared resource
The driver pre-allocates all the required OS resources (dynamic or static according to the setting) on
calling sl_Start. The number of allocated objects is calculated according to the maximum concurrent
actions required by the user.
The SimpleLink host driver does not use its own processing context. To bind a context to the driver, the
user can implement a spawn mechanism, or use the built-in spawn mechanism provided by the driver. If
the built-in mechanism is used, the host application must create dedicated context to the driver and call
sl_Task from this context. For platforms without an OS, the application must call to the sl_Task function
repeatedly from its main loop.
1.4.3 Quick Reference
Figure 1-3 shows a quick reference to the entire set of APIs provided by the host driver.

Host Driver Quick APIs Reference
sl_Start
sl_Stop
sl_DeviceGet
sl_DeviceSet
sl_DeviceEventMaskGet
sl_DeviceEventMaskSet
sl_Task
sl_DeviceUartSetMode
sl_RegisterEventHandler
sl_WlanConnect
sl_WlanDisconnect
sl_WlanProfileAdd
sl_WlanProfileGet
sl_WlanProfileDel
sl_WlanSet
sl_WlanGet
sl_WlanPolicySet
sl_WlanPolicyGet
sl_WlanGetNetworkList
sl_WlanRxStatStart
sl_WlanRxStatStop
sl_WlanRxStatGet
sl_WlanSetMode
sl_WlanProvisioning
sl_WlanRxFilterAdd
sl_Socket
sl_Listen
sl_Accept
sl_Bind
sl_Close
sl_Connect
sl_Select
sl_Send
sl_SendTo
sl_Recv
sl_RecvFrom
sl_GetSockOpt
sl_SetSockOpt
sl_NetCfgSet
sl_NetCfgGet
sl_NetUtilSet
sl_NetUtilGet
sl_NetUtilCmd
sl_FsOpen
sl_FsClose
sl_FsRead
sl_FsWrite
sl_FsGetInfo
sl_FsDel
sl_FsCtl
sl_FsProgram
sl_FsGetFileList
Device Wlan Socket
NetCfg NetUtil FS
DeviceFatalErrorEventHandler
DeviceGeneralEventHandler
WlanEventHandler SocketEventHandler
NetCfgEventHandler NetUtilEventHandler
sl_NetAppStart
sl_NetAppStop
sl_NetAppDnsGetHostByName
sl_NetAppDnsGetHostByService
sl_NetAppGetServiceList
sl_NetAppMDNSUnRegisterService
sl_NetAppMDNSRegisterService
sl_NetAppPingStart
sl_NetAppSet
sl_NetAppGet
NetApp
NetAppEventHandler
Legend
- API function
- Application Event Handler
Host Driver Overview www.ti.com
18 SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
Overview
Figure 1-3. Quick Host APIs Reference
For more information on these APIs, refer Appendix A.

Platform Dependent
OS Adaptation Interface Driver
sl_SyncObjCreate
sl_SyncObjDelete
sl_SyncObjSignal
sl_SyncObjSignalFromIRQ
sl_SyncObjWait
sl_LockObjCreate
sl_LockObjDelete
sl_LockObjLock
sl_LockObjUnlock
sl_IfOpen
sl_IfClose
sl_IfRead
sl_IfWrite
sl_IfRegIntHdlr
Platform General
sl_DeviceEnable
sl_DeviceDisable
Optional
sl_Spawn
slcb_SetErrno
Optional
sl_IfMaskIntHdlr
sl_IfUnMaskIntHdlr
Optional
slcb_GetTimestamp
sl_Malloc
sl_Free
www.ti.com Host Driver Overview
19
SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback Copyright © 2017, Texas Instruments Incorporated
Overview
1.4.4 Porting to Different Platforms
To use the driver on different platforms, the host must implement a few adaptation modules.
Figure 1-4 shows these adaptation modules.
Figure 1-4. Host Driver Adaptation Modules (Platform-Dependent)
For more information about porting the driver to new platforms, see Chapter 17.

20 SWRU455A–February 2017–Revised March 2017
Submit Documentation Feedback
Copyright © 2017, Texas Instruments Incorporated
Networking Application
Chapter 2
SWRU455A–February 2017–Revised March 2017
Networking Application
Topic ........................................................................................................................... Page
2.1 Introduction....................................................................................................... 21
2.1.1 Wi-Fi Connectivity ...................................................................................... 21
2.1.2 Traffic Types ............................................................................................ 22
2.1.3 Security .................................................................................................. 23
2.1.4 User Experience........................................................................................ 23
2.1.5 Power Consumption.................................................................................... 23
2.1.6 Provisioning ............................................................................................. 24
2.2 Basic Examples ................................................................................................ 24
2.2.1 Wi-Fi Doorbell .......................................................................................... 24
2.2.2 Power Socket .......................................................................................... 24
2.2.3 Wi-Fi Tag ................................................................................................ 25