1.. _cc3220sf_launchxl:
2
3CC3220SF LaunchXL
4#################
5
6Overview
7********
8The SimpleLink Wi-Fi CC3220SF LaunchPad development kit (CC3220SF-LAUNCHXL)
9highlights CC3220SF, a single-chip wireless microcontroller (MCU) with
101MB internal flash, 4MB external serial flash, 256KB of RAM and enhanced
11security features.
12
13See the `TI CC3220 Product Page`_ for details.
14
15Features:
16=========
17
18* Two separate execution environments: a user application dedicated ARM
19  Cortex-M4 MCU and a network processor MCU to run all Wi-Fi and
20  internet logical layers
21* 40-pin LaunchPad standard leveraging the BoosterPack ecosystem
22* On-board accelerometer and temperature sensor
23* Two buttons and three LEDs for user interaction
24* UART through USB to PC
25* BoosterPack plug-in module for adding graphical displays, audio
26  codecs, antenna selection, environmental sensing, and more
27* Power from USB for the LaunchPad and optional external BoosterPack
28* XDS110-based JTAG emulation with serial port for flash programming
29
30Details on the CC3220SF LaunchXL development board can be found in the
31`CC3220SF LaunchPad Dev Kit Hardware User's Guide`_.
32
33Hardware
34********
35
36The CC3220SF SoC has two MCUs:
37
38#. Applications MCU - an ARM |reg| Cortex |reg|-M4 Core at 80 MHz, with 256Kb RAM,
39   and access to external serial 4MB flash with bootloader and peripheral
40   drivers in ROM.
41
42#. Network Coprocessor (NWP) - a dedicated ARM MCU, which completely
43   offloads Wi-Fi and internet protocols from the application MCU.
44
45Complete details of the CC3220SF SoC can be found in the `CC3220 TRM`_.
46
47Supported Features
48==================
49
50Zephyr has been ported to the Applications MCU, with basic peripheral
51driver support.
52
53+-----------+------------+-----------------------+
54| Interface | Controller | Driver/Component      |
55+===========+============+=======================+
56| UART      | on-chip    | serial port-interrupt |
57+-----------+------------+-----------------------+
58| GPIO      | on-chip    | gpio                  |
59+-----------+------------+-----------------------+
60| I2C       | on-chip    | i2c                   |
61+-----------+------------+-----------------------+
62| SPI_0     | on-chip    | Wi-Fi host driver     |
63+-----------+------------+-----------------------+
64
65.. note::
66
67   For consistency with TI SimpleLink SDK and BoosterPack examples,
68   the I2C driver defaults to I2C_BITRATE_FAST mode (400 kHz) bus speed
69   on bootup.
70
71The accelerometer, temperature sensors, or other peripherals
72accessible through the BoosterPack, are not currently supported.
73
74Connections and IOs
75====================
76
77Peripherals on the CC3220SF LaunchXL are mapped to the following pins in
78the file :zephyr_file:`boards/arm/cc3220sf_launchxl/pinmux.c`.
79
80+------------+-------+-------+
81| Function   | PIN   | GPIO  |
82+============+=======+=======+
83| UART0_TX   | 55    | N/A   |
84+------------+-------+-------+
85| UART0_RX   | 57    | N/A   |
86+------------+-------+-------+
87| LED D7 (R) | 64    | 9     |
88+------------+-------+-------+
89| LED D6 (O) | 01    | 10    |
90+------------+-------+-------+
91| LED D5 (G) | 02    | 11    |
92+------------+-------+-------+
93| Switch SW2 | 15    | 22    |
94+------------+-------+-------+
95| Switch SW3 | 04    | 13    |
96+------------+-------+-------+
97
98The default configuration can be found in the Kconfig file at
99:zephyr_file:`boards/arm/cc3220sf_launchxl/cc3220sf_launchxl_defconfig`.
100
101
102Programming and Debugging
103*************************
104
105TI officially supports development on the CC3220SF using the TI
106`CC3220 SDK`_ on Windows and Linux using TI tools: Code Composer
107Studio for debugging and `UniFlash`_ for flashing.
108
109For Windows developers, see the `CC3220 Getting Started Guide`_ for
110instructions on installation of tools, and how to flash the board using
111UniFlash.
112
113Note that zephyr.bin produced by the Zephyr SDK may not load via
114UniFlash tool.  If encountering difficulties, use the zephyr.elf
115file and openocd instead (see below).
116
117The following instructions are geared towards Linux developers who
118prefer command line tools to an IDE.
119
120Before flashing and debugging the board, there are a few one-time board
121setup steps to follow.
122
123Prerequisites:
124==============
125
126#. Download and install the latest version of `UniFlash`_.
127#. Jumper SOP[2..0] (J15) to [010], and connect the USB cable to the PC.
128
129   This should result in a new device "Texas Instruments XDS110 Embed
130   with CMSIS-DAP" appearing at /dev/ttyACM1 and /dev/ttyACM0.
131
132#. Update the service pack, and place the board in "Development Mode".
133
134   Setting "Development Mode" enables the JTAG interface, necessary
135   for subsequent use of OpenOCD and updating XDS110 firmware.
136
137   Follow the instructions in Section 2.4 "Download the Application",
138   in the `CC3220 Getting Started Guide`_, except for steps 5 and 6 in
139   Section 2.4.1 which select an MCU image.
140
141#. Ensure the XDS-110 emulation firmware is updated.
142
143   Download and install the latest `XDS-110 emulation package`_.
144
145   Follow these `xds110 firmware update directions
146   <http://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds110.html#updating-the-xds110-firmware>`_
147
148   Note that the emulation package install may place the xdsdfu utility
149   in ``<install_dir>/ccs_base/common/uscif/xds110/``.
150
151#. Switch Jumper SOP[2..0] (J15) back to [001].
152
153   Remove power from the board (disconnect USB cable) before switching jumpers.
154
155#. Install OpenOCD
156
157   You can obtain OpenOCD by following these
158   :ref:`installing the latest Zephyr SDK instructions <toolchain_zephyr_sdk>`.
159
160   After the installation, add the directory containing the OpenOCD executable
161   to your environment's PATH variable. For example, use this command in Linux:
162
163   .. code-block:: console
164
165      export PATH=$ZEPHYR_SDK_INSTALL_DIR/sysroots/x86_64-pokysdk-linux/usr/bin/openocd:$PATH
166
167   If you had previously installed TI OpenOCD, you can simply switch to use
168   the one in the Zephyr SDK. If for some reason you wish to continue to use
169   your TI OpenOCD installation, you can set the OPENOCD and
170   OPENOCD_DEFAULT_PATH variables in
171   :zephyr_file:`boards/arm/cc3220sf_launchxl/board.cmake` to point the build
172   to the paths of the OpenOCD binary and its scripts, before
173   including the common openocd.board.cmake file:
174
175   .. code-block:: cmake
176
177      set(OPENOCD "/usr/local/bin/openocd" CACHE FILEPATH "" FORCE)
178      set(OPENOCD_DEFAULT_PATH /usr/local/share/openocd/scripts)
179      include(${ZEPHYR_BASE}/boards/common/openocd.board.cmake)
180
181#. Ensure CONFIG_XIP=y (default) is set.
182
183   This locates the program into flash, and sets CONFIG_CC3220SF_DEBUG=y,
184   which prepends a debug header enabling the flash to persist over
185   subsequent reboots, bypassing the bootloader flash signature
186   verification.
187
188   See Section 21.10 "Debugging Flash User Application Using JTAG" of the
189   `CC3220 TRM`_ for details on the secure flash boot process.
190
191
192Once the above prerequisites are met, applications for the ``_cc3220sf_launchxl``
193board can be built, flashed, and debugged with openocd and gdb per the Zephyr
194Application Development Primer (see :ref:`build_an_application` and
195:ref:`application_run`).
196
197Flashing
198========
199
200To build and flash an application, execute the following commands for <my_app>:
201
202.. zephyr-app-commands::
203   :zephyr-app: <my_app>
204   :board: cc3220sf_launchxl
205   :goals: flash
206
207This will load the image into flash.
208
209To see program output from UART0, connect a separate terminal window:
210
211.. code-block:: console
212
213  % screen /dev/ttyACM0 115200 8N1
214
215Then press the reset button (SW1) on the board to run the program.
216
217When using OpenOCD from Zephyr SDK to flash the device, you may notice
218the program hangs when starting the network processor on the device, if the
219program uses it. There is a known issue with how that version of OpenOCD
220resets the network processor. You would need to manually hit the reset button
221on the board to properly reset the device after flashing.
222
223Debugging
224=========
225
226To debug a previously flashed image, after resetting the board, use the 'debug'
227build target:
228
229.. zephyr-app-commands::
230   :zephyr-app: <my_app>
231   :board: cc3220sf_launchxl
232   :maybe-skip-config:
233   :goals: debug
234
235
236Wi-Fi Support
237*************
238
239The SimpleLink Host Driver, imported from the SimpleLink SDK, has been ported
240to Zephyr, and communicates over a dedicated SPI to the network co-processor.
241It is available as a Zephyr Wi-Fi device driver in
242:zephyr_file:`drivers/wifi/simplelink`.
243
244Usage:
245======
246
247Set :kconfig:option:`CONFIG_WIFI_SIMPLELINK` and :kconfig:option:`CONFIG_WIFI` to ``y``
248to enable Wi-Fi.
249See :zephyr_file:`samples/net/wifi/boards/cc3220sf_launchxl.conf`.
250
251Provisioning:
252=============
253
254SimpleLink provides a few rather sophisticated Wi-Fi provisioning methods.
255To keep it simple for Zephyr development and demos, the SimpleLink
256"Fast Connect" policy is enabled, with one-shot scanning.
257This enables the cc3220sf_launchxl to automatically reconnect to the last
258good known access point (AP), without having to restart a scan, and
259re-specify the SSID and password.
260
261To connect to an AP, first run the Zephyr Wi-Fi shell sample application,
262and connect to a known AP with SSID and password.
263
264See :zephyr:code-sample:`wifi-shell`
265
266Once the connection succeeds, the network co-processor keeps the AP identity in
267its persistent memory.  Newly loaded Wi-Fi applications then need not explicitly
268execute any Wi-Fi scan or connect operations, until the need to change to a new AP.
269
270Secure Socket Offload
271*********************
272
273The SimpleLink Wi-Fi driver provides socket operations to the Zephyr socket
274offload point, enabling Zephyr BSD socket API calls to be directed to the
275SimpleLink Wi-Fi driver, by setting :kconfig:option:`CONFIG_NET_SOCKETS_OFFLOAD`
276to ``y``.
277
278Secure socket (TLS) communication is handled as part of the socket APIs,
279and enabled by:
280
281- setting both :kconfig:option:`CONFIG_NET_SOCKETS_SOCKOPT_TLS`
282  and :kconfig:option:`CONFIG_TLS_CREDENTIAL_FILENAMES` to ``y``,
283- using the TI Uniflash tool to program the required certificates and
284  keys to the secure flash filesystem, and enabling the TI Trusted
285  Root-Certificate Catalog.
286
287See :zephyr:code-sample:`sockets-http-get` and
288:zephyr_file:`samples/net/sockets/http_get/boards/cc3220sf_launchxl.conf` for an
289example.
290
291See the document `Simplelink Wi-Fi Certificates Handling`_ for details on
292using the TI UniFlash tool for certificate programming.
293
294References
295**********
296
297CC32xx Wiki:
298    http://processors.wiki.ti.com/index.php/CC31xx_%26_CC32xx
299
300.. _TI CC3220 Product Page:
301    http://www.ti.com/product/cc3220
302
303.. _CC3220 TRM:
304   http://www.ti.com/lit/pdf/swru465
305
306.. _CC3220 Programmer's Guide:
307   http://www.ti.com/lit/pdf/swru464
308
309.. _CC3220 Getting Started Guide:
310   http://www.ti.com/lit/pdf/swru461
311
312.. _UniFlash:
313   http://processors.wiki.ti.com/index.php/Category:CCS_UniFlash
314
315.. _CC3220 SDK:
316   http://www.ti.com/tool/download/SIMPLELINK-CC3220-SDK
317
318.. _CC3220SF LaunchPad Dev Kit Hardware User's Guide:
319   http://www.ti.com/lit/pdf/swru463
320
321..  _XDS-110 emulation package:
322   http://processors.wiki.ti.com/index.php/XDS_Emulation_Software_Package#XDS_Emulation_Software_.28emupack.29_Download
323
324..  _Simplelink Wi-Fi Certificates Handling:
325   http://www.ti.com/lit/pdf/swpu332
326