Skip to content

GitLab

A
arduino-esp32
Commit e6ba0f62 authored by Pranav Cherukupalli's avatar Pranav Cherukupalli Committed by Me No Dev
Browse files
Options

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
parent 3a8e28dc
Hide whitespace changes
Inline Side-by-side
Showing with 159 additions and 153 deletions
README.md
View file @ e6ba0f62
......@@ -2,160 +2,46 @@
[![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)
- [Installation Instructions](#installation-instructions):
+ [Using Arduino IDE](#using-through-arduino-ide)
+ [Windows](https://github.com/espressif/arduino-esp32/blob/master/doc/windows.md)
+ [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)
- [Installation Instructions](#installation-instructions)
- [Decoding Exceptions](#decoding-exceptions)
- [Issue/Bug report template](#issuebug-report-template)
- [ESP32Dev Board PINMAP](#esp32dev-board-pinmap)
## 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:
- 16 channels [LEDC](https://github.com/espressif/arduino-esp32/blob/master/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
- 2 channels [DAC](https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/esp32-hal-dac.h) which gives real analog output
- 16 channels [LEDC](cores/esp32/esp32-hal-ledc.h) which is PWM
- 8 channels [SigmaDelta](cores/esp32/esp32-hal-sigmadelta.h) which uses SigmaDelta modulation
- 2 channels [DAC](cores/esp32/esp32-hal-dac.h) which gives real analog output
## Installation Instructions
### Using through Arduino IDE
#### [Instructions for Windows](doc/windows.md)
#### Instructions for Mac
- 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
#### 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
- Using Arduino IDE
+ [Instructions for Windows](docs/arduino-ide/windows.md)
+ [Instructions for Mac](docs/arduino-ide/mac.md)
+ [Instructions for Debian/Ubuntu Linux](docs/arduino-ide/debian_ubuntu.md)
+ [Instructions for Fedora](docs/arduino-ide/fedora.md)
- [Using PlatformIO](docs/platformio.md)
- [Building with make](docs/make.md)
- [Using as ESP-IDF component](docs/esp-idf_component.md)
#### Decoding exceptions
You can use [EspExceptionDecoder](https://github.com/me-no-dev/EspExceptionDecoder) to get meaningful call trace.
### 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)
### Building with make
#### 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).
[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.
Finally, if you're sure no one else had the issue, follow the [ISSUE_TEMPLATE](docs/ISSUE_TEMPLATE.md) while reporting any issue.
### 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
![Pin Functions](doc/esp32_pinmap.png)
![Pin Functions](docs/esp32_pinmap.png)
## Hint
Sometimes to program ESP32 via serial you must keep GPIO0 LOW during the programming process
docs/arduino-ide/debian_ubuntu.md 0 → 100644
View file @ e6ba0f62
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
docs/arduino-ide/fedora.md 0 → 100644
View file @ e6ba0f62
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
docs/arduino-ide/mac.md 0 → 100644
View file @ e6ba0f62
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
doc/windows.md → docs/arduino-ide/windows.md
View file @ e6ba0f62
......@@ -5,45 +5,45 @@
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:
- Select ```Clone Existing Repository```
![Step 1](win-gui-1.png)
![Step 1](win-screenshots/win-gui-1.png)
- Select source and destination
- Source Location: ```https://github.com/espressif/arduino-esp32.git```
- 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.
- Click ```Clone``` to start cloning the repository
![Step 2](win-gui-2.png)
![Step 3](win-gui-3.png)
![Step 2](win-screenshots/win-gui-2.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```
![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
![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)
5. Start Arduino IDE
6. Select your board in ```Tools > Board``` menu
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)
![Arduino IDE Example](arduino-ide.png)
![Arduino IDE Example](win-screenshots/arduino-ide.png)
### How to update to the latest code
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```
![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```
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)
docs/esp-idf_component.md 0 → 100644
View file @ e6ba0f62
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
docs/make.md 0 → 100644
View file @ e6ba0f62
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.
docs/platformio.md 0 → 100644
View file @ e6ba0f62
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)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment