DOCUMENTATION: Moved installation instructions to separate page (#561)

* DOCUMENTATION: Moved installation instructions to separate page

* Added Fedora to contents table
* Added Issue/Bug Report section to README
* Some minor improvements

* DOCUMENTATION: Rename directory doc to docs

* Also move ISSUE_TEMPLATE.md to docs directory

* DOCUMENTATION: Use current repo's files

* This makes it consistent instead  of having few local and few pointing to
  espressif/arduino-esp32 by all linking to local files

* DOCUMENTATION: Fix hyperlink to issue/bug template in contents

* DOCUMENTATION: contents: supress platform specific installation instruction
This commit is contained in:
Pranav Cherukupalli 2017-08-17 18:44:01 +05:30 committed by Me No Dev
parent 3a8e28dc87
commit e6ba0f6281
18 changed files with 159 additions and 153 deletions

154
README.md
View File

@ -2,160 +2,46 @@
[![Build Status](https://travis-ci.org/espressif/arduino-esp32.svg?branch=master)](https://travis-ci.org/espressif/arduino-esp32) [![Build Status](https://travis-ci.org/espressif/arduino-esp32.svg?branch=master)](https://travis-ci.org/espressif/arduino-esp32)
## Need help or have a question? Join the chat at [![https://gitter.im/espressif/arduino-esp32](https://badges.gitter.im/espressif/arduino-esp32.svg)](https://gitter.im/espressif/arduino-esp32?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ### Need help or have a question? Join the chat at [![https://gitter.im/espressif/arduino-esp32](https://badges.gitter.im/espressif/arduino-esp32.svg)](https://gitter.im/espressif/arduino-esp32?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
## Contents
- [Development Status](#development-status) - [Development Status](#development-status)
- [Installation Instructions](#installation-instructions): - [Installation Instructions](#installation-instructions)
+ [Using Arduino IDE](#using-through-arduino-ide) - [Decoding Exceptions](#decoding-exceptions)
+ [Windows](https://github.com/espressif/arduino-esp32/blob/master/doc/windows.md) - [Issue/Bug report template](#issuebug-report-template)
+ [Mac OS](#instructions-for-mac)
+ [Debian/Ubuntu](#instructions-for-debianubuntu-linux)
+ [Decoding Exceptions](#decoding-exceptions)
+ [Using PlatformIO](#using-platformio)
+ [Using as ESP-IDF component](#using-as-esp-idf-component)
- [ESP32Dev Board PINMAP](#esp32dev-board-pinmap) - [ESP32Dev Board PINMAP](#esp32dev-board-pinmap)
## Development Status ## Development Status
Most of the framework is implemented. Most noticable is the missing analogWrite. While analogWrite is on it's way, there are a few other options that you can use: Most of the framework is implemented. Most noticable is the missing analogWrite. While analogWrite is on it's way, there are a few other options that you can use:
- 16 channels [LEDC](https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/esp32-hal-ledc.h) which is PWM - 16 channels [LEDC](cores/esp32/esp32-hal-ledc.h) which is PWM
- 8 channels [SigmaDelta](https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/esp32-hal-sigmadelta.h) which uses SigmaDelta modulation - 8 channels [SigmaDelta](cores/esp32/esp32-hal-sigmadelta.h) which uses SigmaDelta modulation
- 2 channels [DAC](https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/esp32-hal-dac.h) which gives real analog output - 2 channels [DAC](cores/esp32/esp32-hal-dac.h) which gives real analog output
## Installation Instructions ## Installation Instructions
### Using through Arduino IDE - Using Arduino IDE
+ [Instructions for Windows](docs/arduino-ide/windows.md)
#### [Instructions for Windows](doc/windows.md) + [Instructions for Mac](docs/arduino-ide/mac.md)
+ [Instructions for Debian/Ubuntu Linux](docs/arduino-ide/debian_ubuntu.md)
#### Instructions for Mac + [Instructions for Fedora](docs/arduino-ide/fedora.md)
- Install latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software) - [Using PlatformIO](docs/platformio.md)
- Open Terminal and execute the following command (copy->paste and hit enter): - [Building with make](docs/make.md)
- [Using as ESP-IDF component](docs/esp-idf_component.md)
```bash
mkdir -p ~/Documents/Arduino/hardware/espressif && \
cd ~/Documents/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32/tools/ && \
python get.py
```
- Restart Arduino IDE
#### Instructions for Debian/Ubuntu Linux
- Install latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software)
- Open Terminal and execute the following command (copy->paste and hit enter):
```bash
sudo usermod -a -G dialout $USER && \
sudo apt-get install git && \
wget https://bootstrap.pypa.io/get-pip.py && \
sudo python get-pip.py && \
sudo pip install pyserial && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32/tools/ && \
python get.py
```
- Restart Arduino IDE
#### Instructions for Fedora
- Install the latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software). `$ sudo dnf -y install arduino` will most likely install an older release.
- Open Terminal and execute the following command (copy->paste and hit enter):
```bash
sudo usermod -a -G dialout $USER && \
sudo dnf install git python3-pip python3-pyserial && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32/tools/ && \
python get.py
```
- Restart Arduino IDE
#### Decoding exceptions #### Decoding exceptions
You can use [EspExceptionDecoder](https://github.com/me-no-dev/EspExceptionDecoder) to get meaningful call trace. You can use [EspExceptionDecoder](https://github.com/me-no-dev/EspExceptionDecoder) to get meaningful call trace.
### Using PlatformIO #### Issue/Bug report template
Before reporting an issue, make sure you've searched for similar one that was already created. Also make sure to go through all the issues labelled as [for reference](https://github.com/espressif/arduino-esp32/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3A%22for%20reference%22%20).
[PlatformIO](http://platformio.org) is an open source ecosystem for IoT Finally, if you're sure no one else had the issue, follow the [ISSUE_TEMPLATE](docs/ISSUE_TEMPLATE.md) while reporting any issue.
development with cross platform build system, library manager and full support
for Espressif ESP32 development. It works on the popular host OS: Mac OS X, Windows,
Linux 32/64, Linux ARM (like Raspberry Pi, BeagleBone, CubieBoard).
- [What is PlatformIO?](http://docs.platformio.org/page/what-is-platformio.html)
- [PlatformIO IDE](http://platformio.org/platformio-ide)
- Quick Start with [PlatformIO IDE](http://docs.platformio.org/page/ide/atom.html#quick-start) or [PlatformIO Core](http://docs.platformio.org/page/core.html)
- [Integration with Cloud and Standalone IDEs](http://docs.platformio.org/page/ide.html) -
Cloud9, Codeanywehre, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM and Visual Studio
- [Project Examples](https://github.com/platformio/platform-espressif32/tree/develop/examples)
- [Using "Stage" (Git) version of Arduino Core](http://docs.platformio.org/page/platforms/espressif32.html#using-arduino-framework-with-staging-version)
### Building with make
[makeEspArduino](https://github.com/plerup/makeEspArduino) is a generic makefile for any ESP8266/ESP32 Arduino project.
Using make instead of the Arduino IDE makes it easier to do automated and production builds.
### Using as ESP-IDF component
- Download and install [esp-idf](https://github.com/espressif/esp-idf)
- Create blank idf project (from one of the examples)
- in the project folder, create a folder called components and clone this repository inside
```bash
mkdir -p components && \
cd components && \
git clone https://github.com/espressif/arduino-esp32.git arduino && \
cd .. && \
make menuconfig
```
- ```make menuconfig``` has some Arduino options
- "Autostart Arduino setup and loop on boot"
- If you enable this options, your main.cpp should be formated like any other sketch
```arduino
//file: main.cpp
#include "Arduino.h"
void setup(){
Serial.begin(115200);
}
void loop(){
Serial.println("loop");
delay(1000);
}
```
- Else you need to implement ```app_main()``` and call ```initArduino();``` in it.
Keep in mind that setup() and loop() will not be called in this case.
If you plan to base your code on examples provided in [esp-idf](https://github.com/espressif/esp-idf/tree/master/examples), please make sure move the app_main() function in main.cpp from the files in the example.
```arduino
//file: main.cpp
#include "Arduino.h"
extern "C" void app_main()
{
initArduino();
pinMode(4, OUTPUT);
digitalWrite(4, HIGH);
//do your own thing
}
```
- "Disable mutex locks for HAL"
- If enabled, there will be no protection on the drivers from concurently accessing them from another thread/interrupt/core
- "Autoconnect WiFi on boot"
- If enabled, WiFi will start with the last known configuration
- Else it will wait for WiFi.begin
- ```make flash monitor``` will build, upload and open serial monitor to your board
## ESP32Dev Board PINMAP ## ESP32Dev Board PINMAP
![Pin Functions](doc/esp32_pinmap.png) ![Pin Functions](docs/esp32_pinmap.png)
## Hint ## Hint
Sometimes to program ESP32 via serial you must keep GPIO0 LOW during the programming process Sometimes to program ESP32 via serial you must keep GPIO0 LOW during the programming process

View File

@ -0,0 +1,19 @@
Installation instructions for Debian / Ubuntu OS
=================================================
- Install latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software)
- Open Terminal and execute the following command (copy->paste and hit enter):
```bash
sudo usermod -a -G dialout $USER && \
sudo apt-get install git && \
wget https://bootstrap.pypa.io/get-pip.py && \
sudo python get-pip.py && \
sudo pip install pyserial && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32/tools/ && \
python get.py
```
- Restart Arduino IDE

View File

@ -0,0 +1,16 @@
Installation instructions for Fedora
=====================================
- Install the latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software). `$ sudo dnf -y install arduino` will most likely install an older release.
- Open Terminal and execute the following command (copy->paste and hit enter):
```bash
sudo usermod -a -G dialout $USER && \
sudo dnf install git python3-pip python3-pyserial && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32/tools/ && \
python get.py
```
- Restart Arduino IDE

14
docs/arduino-ide/mac.md Normal file
View File

@ -0,0 +1,14 @@
Installation instructions for Mac OS
=====================================
- Install latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software)
- Open Terminal and execute the following command (copy->paste and hit enter):
```bash
mkdir -p ~/Documents/Arduino/hardware/espressif && \
cd ~/Documents/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32/tools/ && \
python get.py
```
- Restart Arduino IDE

View File

Before

Width:  |  Height:  |  Size: 186 KiB

After

Width:  |  Height:  |  Size: 186 KiB

View File

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 27 KiB

View File

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

View File

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 27 KiB

View File

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

View File

Before

Width:  |  Height:  |  Size: 84 KiB

After

Width:  |  Height:  |  Size: 84 KiB

View File

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 27 KiB

View File

Before

Width:  |  Height:  |  Size: 39 KiB

After

Width:  |  Height:  |  Size: 39 KiB

View File

@ -5,45 +5,45 @@
2. Download and install Git from [git-scm.com](https://git-scm.com/download/win) 2. Download and install Git from [git-scm.com](https://git-scm.com/download/win)
3. Start ```Git GUI``` and run through the following steps: 3. Start ```Git GUI``` and run through the following steps:
- Select ```Clone Existing Repository``` - Select ```Clone Existing Repository```
![Step 1](win-gui-1.png) ![Step 1](win-screenshots/win-gui-1.png)
- Select source and destination - Select source and destination
- Source Location: ```https://github.com/espressif/arduino-esp32.git``` - Source Location: ```https://github.com/espressif/arduino-esp32.git```
- Target Directory: ```C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32``` - Target Directory: ```C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32```
- Change this to your Sketchbook Location if you have a different directory listed underneath the "Sketchbook location" in Arduino preferences. - Change this to your Sketchbook Location if you have a different directory listed underneath the "Sketchbook location" in Arduino preferences.
- Click ```Clone``` to start cloning the repository - Click ```Clone``` to start cloning the repository
![Step 2](win-gui-2.png) ![Step 2](win-screenshots/win-gui-2.png)
![Step 3](win-gui-3.png) ![Step 3](win-screenshots/win-gui-3.png)
- Open ```C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32/tools``` and double-click ```get.exe``` - Open ```C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32/tools``` and double-click ```get.exe```
![Step 4](win-gui-4.png) ![Step 4](win-screenshots/win-gui-4.png)
- When ```get.exe``` finishes, you should see the following files in the directory - When ```get.exe``` finishes, you should see the following files in the directory
![Step 5](win-gui-5.png) ![Step 5](win-screenshots/win-gui-5.png)
4. Plug your ESP32 board and wait for the drivers to install (or install manually any that might be required) 4. Plug your ESP32 board and wait for the drivers to install (or install manually any that might be required)
5. Start Arduino IDE 5. Start Arduino IDE
6. Select your board in ```Tools > Board``` menu 6. Select your board in ```Tools > Board``` menu
7. Select the COM port that the board is attached to 7. Select the COM port that the board is attached to
8. Compile and upload (You might need to hold the boot button while uploading) 8. Compile and upload (You might need to hold the boot button while uploading)
![Arduino IDE Example](arduino-ide.png) ![Arduino IDE Example](win-screenshots/arduino-ide.png)
### How to update to the latest code ### How to update to the latest code
1. Start ```Git GUI``` and you should see the repository under ```Open Recent Repository```. Click on it! 1. Start ```Git GUI``` and you should see the repository under ```Open Recent Repository```. Click on it!
![Update Step 1](win-gui-update-1.png) ![Update Step 1](win-screenshots/win-gui-update-1.png)
2. From menu ```Remote``` select ```Fetch from``` > ```origin``` 2. From menu ```Remote``` select ```Fetch from``` > ```origin```
![Update Step 2](win-gui-update-2.png) ![Update Step 2](win-screenshots/win-gui-update-2.png)
3. Wait for git to pull any changes and close ```Git GUI``` 3. Wait for git to pull any changes and close ```Git GUI```
4. Open ```C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32/tools``` and double-click ```get.exe``` 4. Open ```C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32/tools``` and double-click ```get.exe```
![Step 4](win-gui-4.png) ![Step 4](win-screenshots/win-gui-4.png)

55
docs/esp-idf_component.md Normal file
View File

@ -0,0 +1,55 @@
To use as a component of ESP-IDF
=================================================
- Download and install [esp-idf](https://github.com/espressif/esp-idf)
- Create blank idf project (from one of the examples)
- in the project folder, create a folder called components and clone this repository inside
```bash
mkdir -p components && \
cd components && \
git clone https://github.com/espressif/arduino-esp32.git arduino && \
cd .. && \
make menuconfig
```
- ```make menuconfig``` has some Arduino options
- "Autostart Arduino setup and loop on boot"
- If you enable this options, your main.cpp should be formated like any other sketch
```arduino
//file: main.cpp
#include "Arduino.h"
void setup(){
Serial.begin(115200);
}
void loop(){
Serial.println("loop");
delay(1000);
}
```
- Else you need to implement ```app_main()``` and call ```initArduino();``` in it.
Keep in mind that setup() and loop() will not be called in this case.
If you plan to base your code on examples provided in [esp-idf](https://github.com/espressif/esp-idf/tree/master/examples), please make sure move the app_main() function in main.cpp from the files in the example.
```arduino
//file: main.cpp
#include "Arduino.h"
extern "C" void app_main()
{
initArduino();
pinMode(4, OUTPUT);
digitalWrite(4, HIGH);
//do your own thing
}
```
- "Disable mutex locks for HAL"
- If enabled, there will be no protection on the drivers from concurently accessing them from another thread/interrupt/core
- "Autoconnect WiFi on boot"
- If enabled, WiFi will start with the last known configuration
- Else it will wait for WiFi.begin
- ```make flash monitor``` will build, upload and open serial monitor to your board

View File

Before

Width:  |  Height:  |  Size: 537 KiB

After

Width:  |  Height:  |  Size: 537 KiB

4
docs/make.md Normal file
View File

@ -0,0 +1,4 @@
To use make
============
[makeEspArduino](https://github.com/plerup/makeEspArduino) is a generic makefile for any ESP8266/ESP32 Arduino project.Using make instead of the Arduino IDE makes it easier to do automated and production builds.

12
docs/platformio.md Normal file
View File

@ -0,0 +1,12 @@
Installation instructions for using PlatformIO
=================================================
[PlatformIO](http://platformio.org) is an open source ecosystem for IoT development with cross platform build system, library manager and full support for Espressif ESP32 development. It works on the popular host OS: Mac OS X, Windows,Linux 32/64, Linux ARM (like Raspberry Pi, BeagleBone, CubieBoard).
- [What is PlatformIO?](http://docs.platformio.org/page/what-is-platformio.html)
- [PlatformIO IDE](http://platformio.org/platformio-ide)
- Quick Start with [PlatformIO IDE](http://docs.platformio.org/page/ide/atom.html#quick-start) or [PlatformIO Core](http://docs.platformio.org/page/core.html)
- [Integration with Cloud and Standalone IDEs](http://docs.platformio.org/page/ide.html) -
Cloud9, Codeanywehre, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM and Visual Studio
- [Project Examples](https://github.com/platformio/platform-espressif32/tree/develop/examples)
- [Using "Stage" (Git) version of Arduino Core](http://docs.platformio.org/page/platforms/espressif32.html#using-arduino-framework-with-staging-version)