update README.md, and add Arduino instructions

README.md

@@ -1,2 +1,102 @@
-# esp8266-web-interface
+esp8266-web-interface
+=====================
 Web interface for Huebner inverter
+
+# Table of Contents
+<details>
+ <summary>Click to open TOC</summary>
+<!-- MarkdownTOC autolink="true" levels="1,2,3,4,5,6" bracket="round" style="unordered" indent="    " autoanchor="false" markdown_preview="github" -->
+
+- [About](#about)
+- [Usage](#usage)
+    - [Wifi network](#wifi-network)
+    - [Reaching the board](#reaching-the-board)
+- [Hardware](#hardware)
+- [Firmware](#firmware)
+- [Flashing / Upgrading](#flashing--upgrading)
+    - [Wirelessly](#wirelessly)
+    - [Wired](#wired)
+- [Documentations](#documentations)
+- [Development](#development)
+    - [Arduino](#arduino)
+
+<!-- /MarkdownTOC -->
+</details>
+
+# About
+This repository hosts the source code for the Web Interface for the Huebner inverter, and derivated projects:
+* [OpenInverter Sine (and FOC) firmware](https://github.com/jsphuebner/stm32-sine)
+* [Vehicle Control Unit for Electric Vehicle Conversion Projects](https://github.com/damienmaguire/Stm32-vcu)
+* [OpenInverter buck or boost mode charger firmware](https://github.com/jsphuebner/stm32-charger)
+* [OpenInverter non-grid connected inverter](https://github.com/jsphuebner/stm32-island)
+* [BMS project firmware](https://github.com/jsphuebner/bms-software)
+* ...
+
+It is written with the Arduino development environment and libraries.
+
+# Usage
+To use the web interface 2 things are needed :
+* You need to have a computer on the same WiFi network as the board,
+* You need to 'browse' the web interface page.
+
+## Wifi network
+There are 2 possibilities:
+* Either you connect to an Access Point generated by the board. The default name for this access point is 'ESP-xxxxx' but can be customized. In that case, the board will have a fixed IP address of `192.168.4.1` (and will be reachable on http://192.168.4.1/)
+* Or you can configure the board to join your own WiFi network ; and in that case you may need to tweak your network configuration to provide a fixed address to the board (not necessary).
+
+## Reaching the board
+The board announces itself to the world using mDNS protocol (aka Bonjour, or Rendezvous, or Zeroconf), so you may be able to reach the board using a local name of `inverter.local`.
+So first try to reach it on http://inverter.local/
+
+# Hardware
+The web interface has been initially designed to run on ESP8266 boards, such as:
+* [Olimex MOD-WIFI-ESP8266](https://www.olimex.com/Products/IoT/ESP8266/MOD-WIFI-ESP8266/open-source-hardware)
+
+(Pay attention to the SPI flash chip on your board: some need a special mode `QOUT` instead of `QIO` for programming)
+
+You can buy pre-programmed boards:
+* [OpenInverter shop](https://openinverter.org/shop/index.php?route=product/product&path=59&product_id=56)
+* [EVBMW Shop](https://www.evbmw.com/index.php/evbmw-webshop/vcu-boards/wifi-progged) (Note : you can choose between OpenInverter or Lexus VCU firmware version )
+
+# Firmware
+You can find pre-compiled versions of the firmware on the [OpenInverter forum](https://openinverter.org/forum), or can compile it yourself
+by following the [instructions below](#development).
+
+# Flashing / Upgrading
+## Wirelessly
+If your board is already programmed with this esp8266-web-interface firmware, or with a firmware that has either ESP8266HTTPUpdateServer or ArduinoOTA components compiled in (it may be the case with the default firmware when you buy a new module), and if you can already reach it (WiFi + network); then you can use one of these approachs:
+
+* Using ESP8266HTTPUpdateServer component
+  * Either go to http://inverter.local/update and upload the binary firmware file
+  * Or use this command line `curl -F "image=@firmware.bin" inverter.local/update`
+* Using the ArduinoOTA component
+  * Use the `espota.py` tool (available in the Arduino tools) to upload either a binary firmware file, or a binary filesystem file:
+    * Firmware: `python ..../Arduino15/packages/esp8266/hardware/esp8266/3.0.2/tools/espota.py -i esp8266-761bb8.local --progress  --file firmware.bin`
+    * Filesystem: `python ..../Arduino15/packages/esp8266/hardware/esp8266/3.0.2/tools/espota.py -i esp8266-761bb8.local --spiffs --progress --file spiffs.bin`
+  * Using your development environment (see the [instructions below](#development))
+
+## Wired
+If your board is new and unprogrammed, or if you want to fully re-program it, you'll need to have a wired connection between your computer and the board.
+Assuming you're using the original Olimex board, you'll need :
+* A 3.3v capable USB / Serial adapter
+* the following connections:  
+
+Pin#  | ESP8266 Board Function | USB / Serial adapter
+----- | ---------------------- | --------------------
+1     | +3.3v input            | (Some adapters provide a +3.3v output, you can use it)
+2     | GND                    | GND
+3     | RXD input              | TXD output
+4     | TXD output             | RXD input
+
+Then you would use any of the the [development tool below](#development) ; or the `esptool.py` tool to upload either a binary firmware file, or a binary filesystem file.
+
+# Documentations
+* [Openinverter Web Interface Protocol](PROTOCOL.md)
+
+# Development
+You can choose between the following tools:
+
+## Arduino
+[Arduino IDE](https://www.arduino.cc/en/software) is an easy-to-use desktop IDE, which provides a quick and integrated way to develop and update your board.
+* [Initial setup](doc/ARDUINO_IDE_setup.md)
+* [Day to day usage](doc/ARDUINO_IDE_usage.md)

doc/ARDUINO_IDE_setup.md

@@ -0,0 +1,65 @@
+Arduino IDE setup
+=================
+
+# Table of Contents
+<details>
+ <summary>Click to open TOC</summary>
+<!-- MarkdownTOC autolink="true" levels="1,2,3,4,5,6" bracket="round" style="unordered" indent="    " autoanchor="false" markdown_preview="github" -->
+
+- [About Arduino IDE](#about-arduino-ide)
+- [Installing Arduino IDE and plugins](#installing-arduino-ide-and-plugins)
+- [Configuring Arduino IDE](#configuring-arduino-ide)
+
+<!-- /MarkdownTOC -->
+</details>
+
+# About Arduino IDE
+
+Arduino IDE is an open-source integrated development environment with support for multiple platforms.  
+
+Learn more : https://www.arduino.cc/en/software
+
+# Installing Arduino IDE and plugins
+
+[Download](https://www.arduino.cc/en/software#download) the IDE, and follow the [Getting Started](https://www.arduino.cc/en/Guide)
+guide.
+
+Additionally, install (by following the instructions in the following links) the 2 following IDE plugins:
+* https://github.com/esp8266/arduino-esp8266fs-plugin
+* https://github.com/earlephilhower/arduino-esp8266littlefs-plugin
+
+When you start the Arduino IDE, you should now have two additional options in the `Tools` menu:
+* ESP8266 LittleFS Data Upload
+* ESP8266 Sketch Data Upload
+
+# Configuring Arduino IDE
+
+In the `Preferences` pane for the IDE, look for `Additional Boards Manager URLs`, click on the button on the right, and append the following URL:
+`https://arduino.esp8266.com/stable/package_esp8266com_index.json`
+
+In the `Tools` menu, select the `Board` entry, click on the `Boards Manager...` submenu, enter `esp8266` in the search box and press Enter.
+
+You should have one entry named `esp8266 by ESP8266 Community` ; click on `Install` and wait for installation.
+
+Open the project `File` > `Open` and navigate to the `FSBrowser.ino` file, and open it.
+
+Go back to the `Tools` menu, and in the `Board` entry select the `ESP8266 Boards` choose your board (`Olimex MOD-WIFI-ESP8266(-DEV))
+
+Configure the other parameters the following way:
+
+* Upload Speed : 921600
+* CPU Frequency : 80MHz
+* Flash Size: 2MB (FS:512KB OTA:~768KB)
+* Debug port: Disabled
+* Debug level: None
+* lwIP Variant: v2 Lower Memory
+* VTables: Flash
+* C++ Exceptions: Disabled (new aborts on oom)
+* Stack Protection: Disabled
+* Erase Flash: Only Sketch
+* SSL Support: All SSL Ciphers (most compatible)
+* MMU: 32KB cache + 32KB IRAM (balanced)
+* Non-32-bit access: Use pgm_read macros for IRAM/PROGMEM
+* Port: (_lookup the port on which your USB/Serial adapter is. You can also choose the board if it's up, connected to your WiFi, for OTA flashing_)
+
+That's it ! Your IDE should now be configured for your day to day operations.

doc/ARDUINO_IDE_usage.md

@@ -0,0 +1,29 @@
+Arduino IDE usage
+=================
+
+# Table of Contents
+<details>
+ <summary>Click to open TOC</summary>
+<!-- MarkdownTOC autolink="true" levels="1,2,3,4,5,6" bracket="round" style="unordered" indent="    " autoanchor="false" markdown_preview="github" -->
+
+- [Compilation](#compilation)
+- [Compile and Flash board](#compile-and-flash-board)
+- [Flashing the filesystem](#flashing-the-filesystem)
+- [Debugging](#debugging)
+
+<!-- /MarkdownTOC -->
+</details>
+
+# Compilation
+To compile, you need to choose, in the `Sketch` menu, `Verify / Compile`
+
+# Compile and Flash board
+Choose, in the `Sketch` menu, `Upload`. It will compile and send to the board with the chosen method (serial / OTA)
+
+# Flashing the filesystem
+Choose, in the `Tools` menu, the `ESP8266 Sketch Data Upload` option, which will package, and flash the files in the `data` directory (HTML files for the web interface)
+
+# Debugging
+In case you're debugging and have enabled (`Tools` > `Debug port` / `Tools` > `Debug level`) some kind of debugging output, you may use the `Tools` / `Serial monitor` to check the debug messages.
+
+Please note that the serial port is intended to be attached to the inverter (or other application), so do not leave debug messages in normal operation.