diff --git a/README.md b/README.md index 4825795e8ca..2ed2e00e805 100644 --- a/README.md +++ b/README.md @@ -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 - diff --git a/ISSUE_TEMPLATE.md b/docs/ISSUE_TEMPLATE.md similarity index 100% rename from ISSUE_TEMPLATE.md rename to docs/ISSUE_TEMPLATE.md diff --git a/docs/arduino-ide/debian_ubuntu.md b/docs/arduino-ide/debian_ubuntu.md new file mode 100644 index 00000000000..0f95cf2ac31 --- /dev/null +++ b/docs/arduino-ide/debian_ubuntu.md @@ -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 diff --git a/docs/arduino-ide/fedora.md b/docs/arduino-ide/fedora.md new file mode 100644 index 00000000000..6672183989f --- /dev/null +++ b/docs/arduino-ide/fedora.md @@ -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 diff --git a/docs/arduino-ide/mac.md b/docs/arduino-ide/mac.md new file mode 100644 index 00000000000..e8c4c6cc290 --- /dev/null +++ b/docs/arduino-ide/mac.md @@ -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 diff --git a/doc/arduino-ide.png b/docs/arduino-ide/win-screenshots/arduino-ide.png similarity index 100% rename from doc/arduino-ide.png rename to docs/arduino-ide/win-screenshots/arduino-ide.png diff --git a/doc/win-gui-1.png b/docs/arduino-ide/win-screenshots/win-gui-1.png similarity index 100% rename from doc/win-gui-1.png rename to docs/arduino-ide/win-screenshots/win-gui-1.png diff --git a/doc/win-gui-2.png b/docs/arduino-ide/win-screenshots/win-gui-2.png similarity index 100% rename from doc/win-gui-2.png rename to docs/arduino-ide/win-screenshots/win-gui-2.png diff --git a/doc/win-gui-3.png b/docs/arduino-ide/win-screenshots/win-gui-3.png similarity index 100% rename from doc/win-gui-3.png rename to docs/arduino-ide/win-screenshots/win-gui-3.png diff --git a/doc/win-gui-4.png b/docs/arduino-ide/win-screenshots/win-gui-4.png similarity index 100% rename from doc/win-gui-4.png rename to docs/arduino-ide/win-screenshots/win-gui-4.png diff --git a/doc/win-gui-5.png b/docs/arduino-ide/win-screenshots/win-gui-5.png similarity index 100% rename from doc/win-gui-5.png rename to docs/arduino-ide/win-screenshots/win-gui-5.png diff --git a/doc/win-gui-update-1.png b/docs/arduino-ide/win-screenshots/win-gui-update-1.png similarity index 100% rename from doc/win-gui-update-1.png rename to docs/arduino-ide/win-screenshots/win-gui-update-1.png diff --git a/doc/win-gui-update-2.png b/docs/arduino-ide/win-screenshots/win-gui-update-2.png similarity index 100% rename from doc/win-gui-update-2.png rename to docs/arduino-ide/win-screenshots/win-gui-update-2.png diff --git a/doc/windows.md b/docs/arduino-ide/windows.md similarity index 76% rename from doc/windows.md rename to docs/arduino-ide/windows.md index 6764cb034c4..efd38fc05f6 100644 --- a/doc/windows.md +++ b/docs/arduino-ide/windows.md @@ -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) diff --git a/docs/esp-idf_component.md b/docs/esp-idf_component.md new file mode 100644 index 00000000000..abf6f0c4ea0 --- /dev/null +++ b/docs/esp-idf_component.md @@ -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 diff --git a/doc/esp32_pinmap.png b/docs/esp32_pinmap.png similarity index 100% rename from doc/esp32_pinmap.png rename to docs/esp32_pinmap.png diff --git a/docs/make.md b/docs/make.md new file mode 100644 index 00000000000..1fca5d79f9f --- /dev/null +++ b/docs/make.md @@ -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. diff --git a/docs/platformio.md b/docs/platformio.md new file mode 100644 index 00000000000..afa5c93187a --- /dev/null +++ b/docs/platformio.md @@ -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)