Skip to content

Commit e041e17

Browse files
pedrominatelpedrominatel
committed
Added Linux and macOS install guide
1 parent 8caf585 commit e041e17

File tree

4 files changed

+171
-35
lines changed

4 files changed

+171
-35
lines changed

‎docs/Makefile

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,14 @@ SPHINXBUILD ?= sphinx-build
88
SOURCEDIR = source
99
BUILDDIR = build
1010

11+
LINKCHECKDIR = build/linkcheck
12+
13+
.PHONY: checklinks
14+
checklinks:
15+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(LINKCHECKDIR)
16+
@echo
17+
@echo "Check finished. Report is in $(LINKCHECKDIR)."
18+
1119
# Put it first so that "make" without argument is like "make help".
1220
help:
1321
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/source/conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3232
# ones.
3333
extensions = [
34+
'sphinx_copybutton'
3435
]
3536

3637
# Add any paths that contain templates here, relative to this directory.

‎docs/source/installing.rst

Lines changed: 137 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,57 +5,171 @@ Installing
55
Before Installing
66
-----------------
77

8-
9-
108
Installing using Boards Manager
119
-------------------------------
1210

13-
- Stable release link:
11+
- Stable release link::
1412

1513
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
1614

17-
- Development release link:
15+
- Development release link::
1816

1917
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json
2018

19+
2120
Starting with 1.6.4, Arduino allows installation of third-party platform
2221
packages using Boards Manager. We have packages available for Windows,
23-
Mac OS, and Linux (x86, amd64, armhf and arm64).
22+
macOS, and Linux (x86, amd64, armhf and arm64).
23+
24+
25+
- Install the current upstream Arduino IDE at the 1.8 level or later. The current version is at the `arduino.cc`_ website.
2426

25-
- Install the current upstream Arduino IDE at the 1.8 level or later.
26-
The current version is at the `Arduino
27-
website <http://www.arduino.cc/en/main/software>`__.
2827
- Start Arduino and open Preferences window.
29-
- Enter one of the release links above into *Additional Board Manager
30-
URLs* field. You can add multiple URLs, separating them with commas.
31-
- Open Boards Manager from Tools > Board menu and install *esp32*
32-
platform (and do not forget to select your ESP32 board from Tools >
33-
Board menu after installation).
28+
29+
- Enter one of the release links above into *Additional Board Manager URLs* field. You can add multiple URLs, separating them with commas.
30+
31+
- Open Boards Manager from Tools > Board menu and install *esp32* platform (and do not forget to select your ESP32 board from Tools > Board menu after installation).
3432

3533
Windows
3634
-------
3735

36+
37+
3838
Linux
3939
-----
4040

41-
MacOS
42-
-----
41+
Debian/Ubuntu
42+
===============
43+
44+
- Install latest Arduino IDE from `arduino.cc`_.
45+
46+
- Open Terminal and execute the following command (copy -> paste and hit enter):
47+
48+
.. code-block:: bash
49+
50+
sudo usermod -a -G dialout $USER && \
51+
sudo apt-get install git && \
52+
wget https://bootstrap.pypa.io/get-pip.py && \
53+
sudo python3 get-pip.py && \
54+
sudo pip3 install pyserial && \
55+
mkdir -p ~/Arduino/hardware/espressif && \
56+
cd ~/Arduino/hardware/espressif && \
57+
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
58+
cd esp32 && \
59+
git submodule update --init --recursive && \
60+
cd tools && \
61+
python3 get.py
62+
63+
- Restart Arduino IDE.
64+
65+
- If you have Arduino installed to ~/, modify the installation as follows, beginning at `mkdir -p ~/Arduino/hardware`:
66+
67+
.. code-block:: bash
68+
69+
cd ~/Arduino/hardware
70+
mkdir -p espressif && \
71+
cd espressif && \
72+
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
73+
cd esp32 && \
74+
git submodule update --init --recursive && \
75+
cd tools && \
76+
python3 get.py
77+
78+
Fedora
79+
======
80+
81+
- Install the latest Arduino IDE from `arduino.cc`_.
82+
- Command ``$ sudo dnf -y install arduino`` will most likely install an older release.
83+
84+
- Open Terminal and execute the following command (copy -> paste and hit enter):
85+
86+
.. code-block:: bash
4387
88+
sudo usermod -a -G dialout $USER && \
89+
sudo dnf install git python3-pip python3-pyserial && \
90+
mkdir -p ~/Arduino/hardware/espressif && \
91+
cd ~/Arduino/hardware/espressif && \
92+
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
93+
cd esp32 && \
94+
git submodule update --init --recursive && \
95+
cd tools && \
96+
python get.py
97+
98+
- Restart Arduino IDE.
99+
100+
openSUSE
101+
========
102+
103+
- Install the latest Arduino IDE from `arduino.cc`_.
104+
105+
- Open Terminal and execute the following command (copy -> paste and hit enter):
106+
107+
.. code-block:: bash
108+
109+
sudo usermod -a -G dialout $USER && \
110+
if [ `python --version 2>&1 | grep '2.7' | wc -l` = "1" ]; then \
111+
sudo zypper install git python-pip python-pyserial; \
112+
else \
113+
sudo zypper install git python3-pip python3-pyserial; \
114+
fi && \
115+
mkdir -p ~/Arduino/hardware/espressif && \
116+
cd ~/Arduino/hardware/espressif && \
117+
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
118+
cd esp32 && \
119+
git submodule update --init --recursive && \
120+
cd tools && \
121+
python get.py
122+
123+
- Restart Arduino IDE.
124+
125+
126+
macOS
127+
=====
128+
129+
- Install the latest Arduino IDE from `arduino.cc`_.
130+
131+
- Open Terminal and execute the following command (copy -> paste and hit enter):
132+
133+
.. code-block:: bash
134+
135+
mkdir -p ~/Documents/Arduino/hardware/espressif && \
136+
cd ~/Documents/Arduino/hardware/espressif && \
137+
git clone https://github.com/espressif/arduino-esp32.git esp32 --depth 1 && \
138+
cd esp32 && \
139+
git submodule update --init --recursive --depth 1 && \
140+
cd tools && \
141+
python get.py
142+
143+
Where ``~/Documents/Arduino`` represents your sketch book location as per "Arduino" > "Preferences" > "Sketchbook location" (in the IDE once started). Adjust the command above accordingly if necessary!
144+
145+
- If you get the error below. Install the command line dev tools with xcode-select --install and try the command above again:
146+
147+
```xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun```
148+
149+
```xcode-select --install```
150+
151+
- Try `python3` instead of `python` if you get the error: `IOError: [Errno socket error] [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590)` when running `python get.py`
152+
153+
- If you get the following error when running `python get.py` urllib.error.URLError: <urlopen error SSL: CERTIFICATE_VERIFY_FAILED, go to Macintosh HD > Applications > Python3.6 folder (or any other python version), and run the following scripts: Install Certificates.command and Update Shell Profile.command
154+
155+
- Restart Arduino IDE.
44156

45157
PlatformIO
46158
----------
47159

48-
Installation instructions for using PlatformIO
49-
**********************************************
160+
- `What is PlatformIO? <https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=github&utm_medium=arduino-esp32>`_
161+
162+
- `PlatformIO IDE <https://platformio.org/platformio-ide?utm_source=github&utm_medium=arduino-esp32>`_
50163

51-
`What is PlatformIO? <https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=github&utm_medium=arduino-esp32>`_
164+
- `PlatformIO Core <https://docs.platformio.org/en/latest/core.html?utm_source=github&utm_medium=arduino-esp32>`_
52165

53-
`PlatformIO IDE <https://platformio.org/platformio-ide?utm_source=github&utm_medium=arduino-esp32>`_
166+
- `Advanced usage <https://docs.platformio.org/en/latest/platforms/espressif32.html?utm_source=github&utm_medium=arduino-esp32>`_: Custom settings, uploading to SPIFFS, Over-the-Air (OTA), staging version
54167

55-
`PlatformIO Core <https://docs.platformio.org/en/latest/core.html?utm_source=github&utm_medium=arduino-esp32>`_
168+
- `Integration with Cloud and Standalone IDEs <https://docs.platformio.org/en/latest/ide.html?utm_source=github&utm_medium=arduino-esp32>`_: Cloud9, Codeanywhere, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM, Visual Studio, and VSCode
56169

57-
`Advanced usage <https://docs.platformio.org/en/latest/platforms/espressif32.html?utm_source=github&utm_medium=arduino-esp32>`_: Custom settings, uploading to SPIFFS, Over-the-Air (OTA), staging version
170+
- `Project Examples <https://docs.platformio.org/en/latest/platforms/espressif32.html?utm_source=github&utm_medium=arduino-esp32#examples>`_
58171

59-
`Integration with Cloud and Standalone IDEs <https://docs.platformio.org/en/latest/ide.html?utm_source=github&utm_medium=arduino-esp32>`_: Cloud9, Codeanywhere, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM, Visual Studio, and VSCode
172+
References
173+
==========
60174

61-
`Project Examples <https://docs.platformio.org/en/latest/platforms/espressif32.html?utm_source=github&utm_medium=arduino-esp32#examples>`_
175+
.. _Arduino.cc: https://www.arduino.cc/en/Main/Software

‎docs/source/lib_builder.rst

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,34 @@ Library Builder
44
How to Use Library Builder
55
**************************
66

7-
Espressif has provided a [tool](https://github.com/espressif/esp32-arduino-lib-builder) to simplify building your own compiled libraries for use in Arduino IDE (or your favorite IDE).
7+
Espressif has provided a `tool <https://github.com/espressif/esp32-arduino-lib-builder>`_ to simplify building your own compiled libraries for use in Arduino IDE (or your favorite IDE).
88
To use it to generate custom libraries, follow these steps:
99

1010

11-
- Ubuntu and Debian::
11+
- Step 1 - Clone the ESP32 Arduino lib builder::
1212

13-
git clone https://github.com/espressif/esp32-arduino-lib-builder
13+
git clone https://github.com/espressif/esp32-arduino-lib-builder
1414

15-
#. Step 1. ``
16-
#. Step 2. `cd esp32-arduino-lib-builder`
17-
#. Step 3. `./tools/update-components.sh`
18-
#. Step 4. `./tools/install-esp-idf.sh` (if you already have an $IDF_PATH defined, it will use your local copy of the repository)
19-
#. Step 5. `make menuconfig` or directly edit sdkconfig.
20-
#. Step 6. `./build.sh`
15+
- Step 2 - Go to the ``esp32-arduino-lib-builder`` folder::
2116

22-
The script automates the process of building [arduino as an ESP-IDF component](https://github.com/espressif/arduino-esp32/blob/master/docs/esp-idf_component.md).
23-
Once it is complete, you can cherry pick the needed libraries from `out/tools/sdk/lib`, or run `tools/copy-to-arduino.sh` to copy the entire built system.
24-
`tools/config.sh` contains a number of variables that control the process, particularly the $IDF_BRANCH variable. You can adjust this to try building against newer versions, but there are absolutely no guarantees that any components will work or even successfully compile against a newer IDF.
17+
cd esp32-arduino-lib-builder
18+
19+
- Step 3 - Run the ``update-components`` script::
20+
21+
./tools/update-components.sh`
22+
23+
- Step 4 - Run ``install-esp-idf`` installation script (if you already have an ``$IDF_PATH`` defined, it will use your local copy of the repository)::
24+
25+
./tools/install-esp-idf.sh
26+
27+
- Step 5 - Run the configuration or directly edit sdkconfig::
28+
29+
make menuconfig
30+
31+
- Step 6 - Build::
32+
33+
./build.sh
34+
35+
The script automates the process of building `arduino as an ESP-IDF component <https://github.com/espressif/arduino-esp32/blob/master/docs/esp-idf_component.md>`_.
36+
Once it is complete, you can cherry pick the needed libraries from ``out/tools/sdk/lib``, or run ``tools/copy-to-arduino.sh`` to copy the entire built system.
37+
``tools/config.sh`` contains a number of variables that control the process, particularly the $IDF_BRANCH variable. You can adjust this to try building against newer versions, but there are absolutely no guarantees that any components will work or even successfully compile against a newer IDF.

0 commit comments

Comments
 (0)