cc3200/README: Reorganize and update to the current state of affairs.

Try to put sections in more logical order, and information about cc3200tool
to be the default flashing method.

cc3200/README.md

@@ -1,36 +1,66 @@
-# Build Instructions for the CC3200
+MicroPython port to CC3200 WiFi SoC
+===================================
 
-Currently the CC3200 port of MicroPython builds under Linux and OSX **but not under Windows**.
+This is a MicroPython port to Texas Instruments CC3200 WiFi SoC (ARM Cortex-M4
+architecture). This port supports 2 boards: WiPy and TI CC3200-LAUNCHXL.
 
-The tool chain required for the build can be found at <https://launchpad.net/gcc-arm-embedded>.
+## Build Instructions for the CC3200
 
-In order to download the image to the CC3200 you will need the CCS_Uniflash tool from TI, which at this 
-moment is only available for Windows, so, you need Linux/OSX to build and Windows to flash the image.
+Currently the CC3200 port of MicroPython builds under Linux and OSX,
+but not under Windows.
 
-## To build an image suitable for debugging:
+The toolchain required for the build can be found at
+<https://launchpad.net/gcc-arm-embedded>.
+
+In order to flash the image to the CC3200 you will need the
+[cc3200tool](https://github.com/ALLTERCO/cc3200tool). An alternative is
+to use CCS_Uniflash tool from TI, which works only under Windows, and all
+support is provided by TI itself.
+
+Building the bootloader:
 
-In order to debug the port specific code, optimizations need to be disabled on the 
-port file (check the Makefile for specific details). You can use CCS from TI.
-Use the CC3200.ccxml file supplied with this distribution for the debuuger configuration. 
-```bash
-make BTARGET=application BTYPE=debug BOARD=LAUNCHXL
 ```
-## To build an image suitable to be flashed to the device:
-```bash
-make BTARGET=application BTYPE=release BOARD=LAUNCHXL
-```
-## Building the bootloader
-```bash
 make BTARGET=bootloader BTYPE=release BOARD=LAUNCHXL
 ```
 
-## Regarding old revisions of the CC3200-LAUNCHXL
-First silicon (pre-release) revisions of the CC3200 had issues with the ram blocks, and MicroPython cannot run
-there. Make sure to use a **v4.1 (or higer) LAUNCHXL board** when trying this port, otherwise it won't work.
+Building the "release" image:
+
+```
+make BTARGET=application BTYPE=release BOARD=LAUNCHXL
+```
+
+To build an image suitable for debugging:
+
+In order to debug the port specific code, optimizations need to be disabled on the
+port file (check the Makefile for specific details). You can use CCS from TI.
+Use the CC3200.ccxml file supplied with this distribution for the debuuger configuration.
+
+```
+make BTARGET=application BTYPE=debug BOARD=LAUNCHXL
+```
+
+## Flashing the CC3200-LAUNCHXL
+
+Note that WiPy comes factory programmed with a default version of MicroPython,
+it cannot be programmed via serial, and can be upgraded only with OTA (see
+below).
 
-## Flashing the CC3200
 - Make sure that you have built both the *bootloader* and the *application* in **release** mode.
 - Make sure the SOP2 jumper is in position.
+- Make sure you Linux system recognized the board and created `ttyUSB*`
+  devices (see below for configuration of `ftdi_sio` driver).
+- Run "make erase" and immediately press Reset button on the device.
+- Wait few seconds.
+- Run "make deploy" and immediately press Reset button on the device.
+- You are recommended to install the latest vendor WiFi firmware
+  servicepack from http://www.ti.com/tool/cc3200sdk. Download
+  CC3200SDK-SERVICEPACK package, install it, and locate `ota_*.ucf`
+  and `ota_*.ucf.signed.bin` files. Copy them to the port's directory
+  and run "make servicepack", with immediate press of Reset button.
+- Remove the SOP2 jumper and reset the board.
+
+Flashing process using TI Uniflash:
+
 - Open CCS_Uniflash and connect to the board (by default on port 22). 
 - Format the serial flash (select 1MB size in case of the CC3200-LAUNCHXL, 2MB in case of the WiPy, leave the rest unchecked).
 - Mark the following files for erasing: `/cert/ca.pem`, `/cert/client.pem`, `/cert/private.key` and `/tmp/pac.bin`.
@@ -44,14 +74,14 @@ there. Make sure to use a **v4.1 (or higer) LAUNCHXL board** when trying this po
 
 Once the software is running, you have two options to access the MicroPython REPL:
 
-- Through telnet. 
+- Through telnet.
   * Connect to the network created by the board (as boots up in AP mode), **ssid = "wipy-wlan", key = "www.wipy.io"**.
     * You can also reinitialize the WLAN in station mode and connect to another AP, or in AP mode but with a
       different ssid and/or key.
   * Use your favourite telnet client with the following settings: **host = 192.168.1.1, port = 23.**
   * Log in with **user = "micro" and password = "python"**
 
-- Thru UART (serial).
+- Through UART (serial).
   * This is enabled by default in the standard configuration, for UART0 (speed 115200).
   * For CC3200-LAUNCHXL, you will need to configure Linux `ftdi_sio` driver as described
     in the [blog post](http://www.achanceofbrainshowers.com/blog/tech/2014/8/19/cc3200-development-under-linux/).
@@ -72,15 +102,19 @@ SD cards are also supported, you can connect any SD card and configure the pinou
 To upload your MicroPython scripts to the FTP server, open your FTP client of choice and connect to:
 **ftp://192.168.1.1, user = "micro", password = "python"**
 
-I have tested the FTP server with **FileZilla, FireFTP, FireFox, IE and Chrome,** other clients should work as well, but I am 
-not 100% sure of it.
+Tested FTP clients are: FileZilla, FireFTP, FireFox, IE and Chrome. Other
+clients should work as well, but you may need to configure them to use a
+single connection (this should be the default for any compliant FTP client).
 
-## Upgrading the firmware Over The Air:
+## Upgrading the firmware Over The Air (OTA)
 
-OTA software updates can be performed through the FTP server. After building a new **mcuimg.bin** in release mode, upload it to:
-`/flash/sys/mcuimg.bin` it will take around 6s (The TI simplelink file system is quite slow because every file is mirrored for
-safety). You won't see the file being stored inside `/flash/sys/` because it's actually saved bypassing FatFS, but rest assured that
-the file was successfully transferred, and it has been signed with a MD5 checksum to verify its integrity. 
+OTA software updates can be performed through the builtin FTP server. After
+building a new `mcuimg.bin` in release mode, upload it to:
+`/flash/sys/mcuimg.bin`. It will take around 6s (The TI SimpleLink file
+system is quite slow because every file is mirrored for safety). You won't
+see the file being stored inside `/flash/sys/` because it's actually saved
+bypassing FatFS, but rest assured that the file was successfully transferred,
+and it has been signed with a MD5 checksum to verify its integrity.
 Now, reset the MCU by pressing the switch on the board, or by typing:
 
 ```python
@@ -98,10 +132,17 @@ make BTARGET=application BTYPE=release BOARD=LAUNCHXL WIPY_IP=192.168.1.1 WIPY_U
 
 If `WIPY_IP`, `WIPY_USER` or `WIPY_PWD` are omitted the default values (the ones shown above) will be used.
 
-### Note regarding FileZilla:
+
+## Notes and known issues
+
+## Regarding old revisions of the CC3200-LAUNCHXL
+
+First silicon (pre-release) revisions of the CC3200 had issues with the ram blocks, and MicroPython cannot run
+there. Make sure to use a **v4.1 (or higer) LAUNCHXL board** when trying this port, otherwise it won't work.
+
+### Note regarding FileZilla
 
 Do not use the quick connect button, instead, open the site manager and create a new configuration. In the "General" tab make 
 sure that encryption is set to: "Only use plain FTP (insecure)". In the Transfer Settings tab limit the max number of connections 
 to one, otherwise FileZilla will try to open a second command connection when retrieving and saving files, and for simplicity and 
 to reduce code size, only one command and one data connections are possible.
-