From 2fc488ff064ee7ac431b5e7a86a47df07796a8fd Mon Sep 17 00:00:00 2001 From: Ludovic LANGE Date: Sun, 10 Jul 2022 20:43:35 +0200 Subject: [PATCH] update README.md, and add Arduino instructions --- README.md | 102 ++++++++++++++++++++++++++++++++++++++- doc/ARDUINO_IDE_setup.md | 65 +++++++++++++++++++++++++ doc/ARDUINO_IDE_usage.md | 29 +++++++++++ 3 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 doc/ARDUINO_IDE_setup.md create mode 100644 doc/ARDUINO_IDE_usage.md diff --git a/README.md b/README.md index fba97c4..6b0d0e0 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,102 @@ -# esp8266-web-interface +esp8266-web-interface +===================== Web interface for Huebner inverter + +# Table of Contents +
+ Click to open TOC + + +- [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) + + +
+ +# 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) diff --git a/doc/ARDUINO_IDE_setup.md b/doc/ARDUINO_IDE_setup.md new file mode 100644 index 0000000..3c79164 --- /dev/null +++ b/doc/ARDUINO_IDE_setup.md @@ -0,0 +1,65 @@ +Arduino IDE setup +================= + +# Table of Contents +
+ Click to open TOC + + +- [About Arduino IDE](#about-arduino-ide) +- [Installing Arduino IDE and plugins](#installing-arduino-ide-and-plugins) +- [Configuring Arduino IDE](#configuring-arduino-ide) + + +
+ +# 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. diff --git a/doc/ARDUINO_IDE_usage.md b/doc/ARDUINO_IDE_usage.md new file mode 100644 index 0000000..4d8b525 --- /dev/null +++ b/doc/ARDUINO_IDE_usage.md @@ -0,0 +1,29 @@ +Arduino IDE usage +================= + +# Table of Contents +
+ Click to open TOC + + +- [Compilation](#compilation) +- [Compile and Flash board](#compile-and-flash-board) +- [Flashing the filesystem](#flashing-the-filesystem) +- [Debugging](#debugging) + + +
+ +# 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. \ No newline at end of file