diff --git a/ReadMe.md b/ReadMe.md index 80d851f..427825f 100644 --- a/ReadMe.md +++ b/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) - +## 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 - +## 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 ``` 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=` 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=` or `$env:AMPY_PORT = COM` where `port` is the device address shown + by the `ls` command above, or `COM` 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) - - +## Resources -Resources ---------- Associated open-source ESP32 hardware projects ... - [OHMC team's](https://twitter.com/swagbadge2021) - diff --git a/Windows-Device-Manager-Example.png b/Windows-Device-Manager-Example.png new file mode 100644 index 0000000..fd229d2 Binary files /dev/null and b/Windows-Device-Manager-Example.png differ diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..633806f --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +mpfshell==0.9.2 +esptool diff --git a/scripts/windows/flash_micropython.ps1 b/scripts/windows/flash_micropython.ps1 new file mode 100644 index 0000000..2324a5d --- /dev/null +++ b/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 ###" diff --git a/scripts/windows/mpf_script.ps1 b/scripts/windows/mpf_script.ps1 new file mode 100644 index 0000000..8d1c6b8 --- /dev/null +++ b/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