Merge pull request #118 from cnlohr/esp8266-docs

Esp8266 docs

README.md

@@ -1,6 +1,25 @@
 ColorChord
 ==========
 
+Table of Contents
+-----------------
+
+- [ColorChord](#colorchord)
+  - [Table of Contents](#table-of-contents)
+  - [What is ColorChord?](#what-is-colorchord)
+  - [Background](#background)
+  - [Current State of Affairs](#current-state-of-affairs)
+  - [ColorChord: Embedded](#colorchord-embedded)
+- [Build Instructions](#build-instructions)
+  - [Building ColorChord Embedded](#building-colorchord-embedded)
+  - [Building with Linux](#building-with-linux)
+  - [Building with Windows](#building-with-windows)
+    - [MSYS2](#msys2)
+    - [clang](#clang)
+    - [TCC](#tcc)
+  - [Using](#using)
+  - [Additional Videos](#additional-videos)
+
 What is ColorChord?
 -------------------
 
@@ -42,10 +61,21 @@ ColorChord: Embedded
 
 There is work on an embedded version of ColorChord, which avoids floating point operations anywhere in the output pipeline.  Though I have made efforts to port it to AVRs, it doesn't seem feasable to operate on AVRs without some shifty tricks which I'd like to avoid, so I have retargeted my efforts to 32-bit systems, such as the STM32F303, STM32F407, and (somehow) the ESP8266.  ColorChord Embedded uses a different codebase, located in the [embeddedcommon](/embeddedcommon) and distributed among the various embedded* folders.
 
+Build Instructions
+==================
+
+Building ColorChord Embedded
+----------------------------
+
+The embedded version of Colorchord has a different build system than the desktop versions of Colorchord. See the build instructions for each of the supported embedded architectures in their respective folders
+
+- [esp8266](embedded8266/README.md#build-instructions)
+- [stm32f303](embeddedstm32f303/README.md)
+- [stm32f407](embeddedstm32f407/) - TODO Add readme
 
 Building with Linux
 -----------------
-Use `apt-get` to install the following packages for Debian/Ubuntu/Mint:
+From the linux terminal use `apt-get` to install the following packages for Debian/Ubuntu/Mint:
 ```
 apt-get install build-essential libpulse-dev libasound2-dev libx11-dev libxext-dev libxinerama-dev libusb-1.0-0-dev libudev-dev
 ```
@@ -55,7 +85,12 @@ To get colorchord, type:
 ```
 git clone --recurse-submodules https://github.com/cnlohr/colorchord
 ```
+This will download the colorchord source code into the colorchord directory
 
+You really want to be using colorchord2, so we need to move to it's build directory to compile the source code.
+```
+cd colorchord/colorchord2
+```
 To make colorchord, type:
 
 ```
@@ -110,6 +145,7 @@ To run colorchord, use the following syntax:
 
 If you edit default.conf while the program is running and resave it, it will use the settings in the newly saved file.
 
+Note that the colorchord executable file is located in the colorchord2 directory in the colorchord repository. 
 
 Additional Videos
 -----------------

embedded8266/README.md

@@ -36,3 +36,70 @@ If you have problems with burning the firmware or transfering page data over net
 in `makeconf.inc`. This way the esp checks if the flash is written correctly.
 Especially with some ESP-01 modules there has been a problem with the flash
 not being written correctly.
+
+## Build Instructions
+
+To build colorchord for the esp8266, you first must install the development tools for the esp8266 so that you can compile the code and flash it to the device.
+
+### Setup Toolchain
+Follow the instructions in Charles' getting started video to install the toolchain (up until about 3:30 into the video).
+
+[![Toolchain installation video](https://img.youtube.com/vi/LiKNRBIcGII/0.jpg)](https://www.youtube.com/watch?v=LiKNRBIcGII)
+
+The instructions shown in the video are from the [esp82xx repo](https://github.com/cnlohr/esp82xx) on github.
+
+TLDR version: You should really watch the video and look at the other instructions though.
+1. if you are on Windows you need to install WSL1 (Windows Subsystem for Linux version 1). 
+2. Install Python2 and Make
+3. Install pip (for Python 2)
+4. Install pyserial (for Python 2)
+5. Install Charles' prepackaged toolchain to the `~/esp8266` directory (`esp8266` directory in your home folder).
+6. Set the `ESP_ROOT` environment variable in your `.profile` or `.bashrc` file. Check to see if one of these files exist (they are hidden by default), if one of them does exist, edit it adding the following line to the file.
+```
+export ESP_ROOT=$(HOME)/esp8266/esp-open-sdk
+```
+
+### Build Colorchord Embedded
+At this point you should have your development toolchain set up, now we will download and install colorchord.
+
+Start by cloning this git repository, in a terminal window use the command
+```
+git clone https://github.com/cnlohr/colorchord.git --recurse-submodules
+```
+This will download the source code for colorchord and all of its dependencies.
+
+Next, move to the `embedded8266` directory so that we can compile the version of colorchord for the esp8266.
+```
+cd colorchord/embedded8266
+```
+
+Now we will need to build colorchord, this step will need to be done if you make any changes to the colorchord code.
+```
+make all
+```
+Hopefully the previous command completed without errors, if it did not, please refer to the [common problems](#common-problems) section. If all went well, there should be three binary files in your build directory `image.elf`, `image.elf-0x00000.bin`, and `image.elf-0x10000.bin`. You can check this with the command
+```
+ls -l image.elf*
+```
+
+### Flash to the ESP8266
+Before flashing the program to the esp8266 it must be connected to the computer over a usb-to-serial connection and the correct port on the computer must be known. If using Windows (WSL) this will be the COM port shown by Windows Device Manager. For example, `COM4` in Windows will refer to `/dev/ttyS4` in WSL (See [2:35](https://youtu.be/LiKNRBIcGII?t=155) from the previously mentioned video). On a Linux machine it will most likely be `/dev/ttyUSB0`. The file determined here will specify the `PORT` value in later commands, so if you had `COM4`, then `PORT` would be `/dev/ttyS4`.
+
+If this is your first time using the esp8266 module with colorchord run the following command.
+```
+PORT=<port value> make erase
+PORT=<port value> make burnitall
+```
+These two commands erase the contents of esp8266 memory and flash the program (and some base files) to it.
+
+If you have made some changes to colorchord and you want to test them use the command
+```
+PORT=<port_value> make burn
+```
+### Connect to the ESP8266
+If all went well, the esp module should be broadcasting a wifi access point that you can connect to. Once that is done, you should be able to see the colorchord webpage dashboard at the ip address [192.168.4.1](http://192.168.4.1). That should be it! Enjoy using colorchord, and don't hesitate to reach out if you have any issues.
+
+## Common Problems
+**Under Construction**
+
+If you experience any issues building colorchord embedded, please open an issue and we will try and work through it. I will try and keep this section up to date with relevant information.

embedded8266/user.cfg

@@ -10,7 +10,7 @@ COM_PORT     = 7777
 BACKEND_PORT = 7878
 MFS_PAGE_OFFSET = 532480 # 0x82000
 
-#SDK_DEFAULT  = $(HOME)/esp8266/esp-open-sdk
+SDK_DEFAULT  = $(HOME)/esp8266/esp-open-sdk
 ESP_GCC_VERS = 4.8.5
 #SDK  = $(HOME)/esp8266/esp_iot_sdk_v1.5.2
 PAGE_SCRIPTS = main.js