Merge pull request #118 from cnlohr/esp8266-docs

Esp8266 docs
This commit is contained in:
CNLohr 2021-02-13 11:34:42 -08:00 committed by GitHub
commit 9cae6dc38d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 105 additions and 2 deletions

View file

@ -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
-----------------

View file

@ -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.

View file

@ -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