Update install doc

ReadMe.md

@@ -1,21 +1,16 @@
-Aiko Engine MP ([microPython](http://micropython.org))
-==============
+# Aiko Engine MP ([microPython](http://micropython.org))
+
+## Contents
 
-Contents
---------
 - [Overview](#overview)
 - [Installation](#installation)
 - [Resources](#resources)
-
-Pages
------
+## Pages
 - [Contributors](Contributors.md)
 - [Software license](License)
 
-<a name="overview" />
+## Overview
 
-Overview
---------
 The Aiko Engine MP provides ...
 
 - Modular [microPython](http://micropython.org) based framework
@@ -30,57 +25,106 @@ The Aiko Engine MP provides ...
 - Supports [LCA2017 IoTuz project](http://www.openhardwareconf.org/wiki/OHC2017)
 - Tested on a range of ESP32 development boards
 
-<a name="installation" />
+## Installation
+
+Installation is a three stage process:
+
+1. Setup the correct tooling on your workstation
+2. Download and install MicroPython onto your ESP32 development board
+3. Install the Aiko software onto your ESP32 development board.
+
+**Notes**:
 
-Installation
--------------
+* If you are using Linux or macOS then you will be using a Posix shell (e.g. [Bash](https://www.gnu.org/software/bash/) or [zsh](http://zsh.sourceforge.net/))
+* If you are on Windows then we assume you are using [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/overview) on Windows 10.
+
+### 1. Setup
+
+- Make sure you have a current version of [Python3](https://www.python.org/) available on your workstation
+
+- Download the Aiko software code from https://github.com/geekscape/aiko_engine_mp
 
-- Download the source code from <https://github.com/geekscape/aiko_engine_mp>
 ```
     git clone https://github.com/geekscape/aiko_engine_mp
+```
+**Note**: If you don't have Git installed you can download a zip file from https://github.com/geekscape/aiko_engine_mp and unpack it
+
+
+```
     cd aiko_engine_mp
 ```
-- Ensure you have a
-  [compatible hardware board](https://github.com/micropython/micropython/wiki/Boards-Summary) or
-  [compatible microPython port](https://github.com/micropython/micropython/tree/master/ports)
-- Make sure you have a Python
-  [virtual environment](http://docs.python-guide.org/en/latest/dev/virtualenvs/#lower-level-virtualenv) set-up, including
-  [virtualenvwrapper](http://docs.python-guide.org/en/latest/dev/virtualenvs/#virtualenvwrapper)
-- Create `mkvirtualenv micropython` and work on the new virtual environment
+
+**Note**: All commands below assume that `.../aiko_engine_mp` is your current directory.
+
+
+- Setup a [virtual Python environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) for your badge project. e.g.
+
 ```
-    workon micropython
+python3 -m venv .venv
 ```
-- Install mpfshell
+
+- Make sure your Python virtual environment is active. **Note**: Do this every time a new terminal session is started
+
 ```
-    pip install esptool
-    pip install -U mpfshell
+. .venv/bin/activate # Linux and macOS
+. .venv\Scripts\activate.ps1 # Windows
 ```
-- Plug in your ESP32 device and make sure you can see it,
-  e.g `ls /dev/tty.*` provides e.g `/dev/tty.wchserial1410`
-- Export the serial port to an environment variable, so mpfshell can use it,
-  e.g `export AMPY_PORT=<port>` where `port` is the device address shown
-  by the `ls` command above
-- Download latest [microPython](http://micropython.org/download)
-- Flash microPython
+
+- Install Python packages [`esptool`](https://github.com/espressif/esptool/blob/master/README.md) and [`mpfshell`](https://github.com/wendlers/mpfshell/blob/master/README.md)
+
+```
+pip install -r requirements.txt
+```
+
+**Notes**:
+
+1. Some environments may need to install additional tools and libraries. e.g. on Debian or Ubuntu
+
+```
+sudo apt-get install -y libpython3-dev libffi-dev libssl-dev
+```
+
+2. You might find it useful to install an MQTT client for later use. There are packages [here](https://hivemq.github.io/mqtt-cli/docs/installation/packages.html).
+
+### 2. Download and install MicroPython
+
+- Download the latest MicroPython binary for your ESP32 board from https://micropython.org/download/
+
+  Note that you must have a
+    [compatible hardware board](https://github.com/micropython/micropython/wiki/Boards-Summary) or
+    [compatible microPython port](https://github.com/micropython/micropython/tree/master/ports)
+
+- Plug in your ESP32 device and make sure you can see it. For example on
+  - macOS or Linux:
+  `ls /dev/tty.*` provides something similar to `/dev/tty.wchserial1410`
+  - On Windows, use the command `change port /query` to discover the COM port.
+
+- Export the serial port to an environment variable, so helpder sripts can use it,
+  e.g `export AMPY_PORT=<port>` or  `$env:AMPY_PORT = COM<n>` where `port` is the device address shown
+  by the `ls` command above, or `COM<n>` is the serial port show by the command `change port` above.  **Note**: Do this every time a new terminal session is started
+
+- Flash microPython. Helper scripts are provided
+
 ```
     ./scripts/flash_micropython.sh
+    .\scripts\windows\flash_micropython.ps1
 ```
+
+### 3. Install the Aiko software
+
 - Run the Aiko Engine MP flash script
+
 ```
-    ./scripts/mpf_script.sh ./scripts/aiko.mpf
+    ./scripts/mpf_script.sh ./scripts/aiko.mpf # Linux or macOS
+    .\scripts\windows\mpf_script.ps1 .\scripts\aiko.mpf # Windows
 ```
 
 Note: For Lolin32-Lite boards, the serial port can be notoriously problematic
 and requires a slight delay in order for the connection to occur properly.
 If you're seeing errors that look like `Could not enter raw repl` then this is probably related.
 
-For `mpfshell` (version v0.9.1 and earlier) on Mac OS X or Windows, this
-problem may be fixed via this [patch](https://github.com/wendlers/mpfshell/commit/52b0636c82b06a07daa5731550f86b0d7ebc7608)
-
-<a name="resources" />
+## Resources
 
-Resources
----------
 Associated open-source ESP32 hardware projects ...
 
 - [OHMC team's](https://twitter.com/swagbadge2021) -

requirements.txt

@@ -0,0 +1,2 @@
+mpfshell==0.9.2
+esptool

scripts/windows/flash_micropython.ps1

@@ -0,0 +1,21 @@
+
+if ([string]::IsNullOrEmpty($env:AMPY_PORT)) {
+    $env:AMPY_PORT = 'COM9'
+}
+
+if ([string]::IsNullOrEmpty($env:BAUDRATE)) {
+    $env:BAUDRATE = '460800'
+}
+
+if ([string]::IsNullOrEmpty($env:ESP32_MICROPYTHON)) {
+    $env:ESP32_MICROPYTHON = './esp32-idf4-20191220-v1.12.bin'
+}
+
+
+echo "### Erase flash ###"
+py $env:VIRTUAL_ENV\Scripts\esptool.py-script.py --chip esp32 --port $env:AMPY_PORT erase_flash
+
+echo "### Flash microPython ###"
+py $env:VIRTUAL_ENV\Scripts\esptool.py-script.py --chip esp32 --port $env:AMPY_PORT --baud $env:BAUDRATE write_flash -z 0x1000 $env:ESP32_MICROPYTHON
+
+echo "### Complete ###"

scripts/windows/mpf_script.ps1

@@ -0,0 +1,10 @@
+
+if ([string]::IsNullOrEmpty($env:AMPY_PORT)) {
+    $env:AMPY_PORT = 'COM9'
+}
+
+$MPF_SCRIPT = $args[0]
+
+
+
+py $env:VIRTUAL_ENV\Scripts\mpfshell-script.py --reset -o $env:AMPY_PORT -s $MPF_SCRIPT