diff --git a/README.md b/README.md index d9c0d8b..9587b81 100644 --- a/README.md +++ b/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 ----------------- diff --git a/embedded8266/README.md b/embedded8266/README.md index 7c24b10..038204c 100644 --- a/embedded8266/README.md +++ b/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= make erase +PORT= 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= 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. diff --git a/embedded8266/user.cfg b/embedded8266/user.cfg index 9463bb5..96df125 100644 --- a/embedded8266/user.cfg +++ b/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